Docs HOWTO (For Contributors)

Purpose: How to keep docs in sync with code, structure updates, and review checklist. Audience: Developer, AI Agent, Reviewer

When to update docs

• Routes: Add/change routes → update docs/architecture/routing.md (source: src/components/routing/AppRoutes.tsx)
• Features: New user-facing capability → add/extend a page in docs/features/* and link in docs/toc.md
• Data model: DB changes (tables/columns/enums/RPCs) → update docs/data-model/schema.md with references to supabase/backups/remote-schema.sql
• Edge Functions: New/changed function → update docs/architecture/edge-functions.md and, if applicable, examples in docs/architecture/apis.md
• Notifications/Emails: Template or flow changes → update docs/architecture/email-templates.md
• Admin: New admin capability → update docs/admin/guide.md and playbooks under docs/operations/*
• i18n/Theming: Update the respective pages under docs/architecture/*

How to structure updates

• Keep docs concise and task-oriented; begin with Purpose/Audience/Prerequisites
• Use relative links and file path references path:line to anchor in code
• Prefer short runnable examples and SQL quick checks where useful
• Add a “Related” or “Next steps” footer to cross-link

Redaction rules

• Never commit secrets (keys, project refs) in docs or code
• Use placeholders: YOUR_SUPABASE_PROJECT_REF, YOUR_STRIPE_SECRET_KEY
• If you discover hardcoded secrets, move to env and rotate

Docs discipline (from archived rules)

• Keep docs/ as the public source of truth.
• When code diverges from docs, update docs in the same PR as the code change.
• For complex areas (blur policy, subscriptions, storage security), include: Purpose/Audience, quick SQL checks, API examples, and “Related” links.

Process

• Implement code changes
• Update or create the relevant doc pages (see “When to update docs”)
• Add links in docs/toc.md
• Run link check:
  • Manually: verify all links resolve in the editor
  • Or run an automated check (see internal script used in this repo)
• Submit PR with both code and docs; mention sections updated

PR checklist (docs)

• [ ] Routes documented (if changed)
• [ ] Features/flows described with references to code
• [ ] Data model updated (tables/enums/RPCs) and SQL checks provided
• [ ] Edge function inputs/outputs updated; examples added
• [ ] Email templates/notifications updated if applicable
• [ ] TOC updated and links verified
• [ ] Secrets redacted; placeholders used
• [ ] Added TODOs to docs/troubleshooting/open-issues.md for follow-ups

Tips

• Use Mermaid for small diagrams to increase clarity
• Keep examples minimal but correct; prefer code snippets from real files
• For larger changes, include a short “migration notes” section with commands

Related

• Conventions: docs/contributing/conventions.md
• TOC: docs/toc.md
• Open issues: docs/troubleshooting/open-issues.md