Skip to content
ConversionIQ Docs

Documentation Standards (ConversionIQ)

These standards are mandatory for all work on the ConversionIQ MVP. This repository is the single source of truth for platform structure, pages, components, and business logic references.

1) Sitemap-first rule (strict)

Section titled “1) Sitemap-first rule (strict)”
  • The documentation structure must mirror the current sitemap 1:1.
  • Every sitemap node must have a corresponding Markdown file under docs/routes/....
  • The canonical sitemap hub is Routes (Sitemap Hub).
  • Sitemap (ConversionIQ) is a top-level navigation aid only. If the two ever drift, Routes (Sitemap Hub) wins.
  • If a route changes (added/removed/renamed), update:
    • the sitemap docs (route indexes),
    • the affected route files,
    • any inbound/outbound links.

2) Controlled development rule (strict)

Section titled “2) Controlled development rule (strict)”
  • UI or logic changes require doc updates in the corresponding:
    • page document(s) under docs/routes/..., and/or
    • component document(s) under docs/components/....
  • If the change affects a canonical contract outside the page/component layer, update the relevant docs under:
    • docs/api/...
    • docs/workflows/...
    • docs/prompts/...
    • docs/ops/...
    • docs/rebuild/...
  • Pages must not define business logic directly.
    • Page docs may describe what happens at a high level.
    • Canonical rules live in domain docs under docs/domains/....
    • Page docs must link to relevant domain docs for “source of truth” logic.

3) Required structure for page docs

Section titled “3) Required structure for page docs”

Every page doc must include these sections (even if some are TBD initially):

  • Purpose (business goal)
  • User roles & permissions
  • Layout structure
  • Components used
  • States (empty / loading / error / complete)
  • Business logic (high-level + links to domain docs)
  • API dependencies
  • Workflow dependencies
  • Prompt / AI behavior dependencies (if applicable)
  • Enterprise constraints
  • Edge cases
  • Security & compliance considerations
  • Analytics events (if applicable)

Use the template: Page Doc Template.

4) Required structure for component docs

Section titled “4) Required structure for component docs”

Reusable components must have their own docs with:

  • Purpose / responsibility
  • Props / inputs / outputs
  • Variants (if any)
  • States (loading/disabled/empty/error)
  • Accessibility requirements
  • Security & privacy considerations (if applicable)
  • Analytics hooks (if applicable)
  • Dependencies (API, domain docs, shared UI)
  • Workflow or prompt dependencies (if applicable)

Use the template: Component Doc Template.

5) Naming & linking conventions

Section titled “5) Naming & linking conventions”
  • Routes: keep file names predictable and grep-friendly.
    • Use folders per top-level route: docs/routes/<route>/...
    • Use README.md inside each route folder as the route index.
  • Links:
    • Every route index (README.md) links to all child subpages.
    • Every subpage links back to its parent index.
    • Pages link to component docs, domain docs, and any relevant API/workflow/prompt docs.

6) Source of truth boundaries

Section titled “6) Source of truth boundaries”
  • docs/architecture/**: platform-wide structure, layers, cross-cutting concerns.
  • docs/domains/**: canonical business rules & models (workspaces, KBs, channels, apps).
  • docs/routes/**: UX and page composition (layout, components, states, flows).
  • docs/components/**: reusable building blocks.
  • docs/api/**: canonical API, persistence, and integration contracts.
  • docs/prompts/**: canonical product prompt and AI behavior contracts.
  • docs/workflows/**: canonical cross-route and cross-system flows.
  • docs/ops/**: canonical environment, deployment, CI/CD, and operational runbooks.
  • docs/rebuild/**: canonical recovery and regeneration playbooks.
  • docs/ai-governance/**: canonical human-readable specs for AI roles, workflows, and asset governance.

7) Canonical contract location (anti-drift)

Section titled “7) Canonical contract location (anti-drift)”

To prevent “contract drift” between reviewers, implementers, and docs:

  • Canonical domain contracts live in this repository under docs/domains/**.
  • Do not maintain competing copies of domain contract docs (e.g., auth.md, workspaces.md, knowledge-bases.md) in other repositories.
  • If a separate repository must exist for operational reasons, it must be treated as either:
    • a read-only mirror of docs/domains/** with an explicit sync rule, or
    • a link-only index that points to the canonical files in this repo (preferred).

Governance requirement:

  • Any mirrored copy must clearly state it is a mirror and identify the canonical source path.

8) Rebuildability requirement

Section titled “8) Rebuildability requirement”

The documentation hub must be sufficient to reconstruct the platform if the current implementation is lost.

At minimum, the canonical docs must define or link:

  • architecture and runtime boundaries
  • domain rules and data contracts
  • routes, components, states, and workflows
  • APIs, persistence, and external integrations
  • prompts, AI behaviors, agent roles, rules, and skills
  • environment, deployment, and recovery procedures

If a project-critical behavior exists only in code, local tooling, or tribal knowledge, the docs are incomplete.

9) AI asset governance

Section titled “9) AI asset governance”
  • Human-readable canonical specs for AI agents, rules, skills, and rebuild workflows live in docs/ai-governance/**.
  • Live .cursor/** assets in the app repo must be treated as mirrors or generated artifacts of those docs, not the only source of truth.
  • No project-critical agent, rule, skill, or recovery workflow may exist only in an unversioned local .cursor directory.
  • If machine-specific configuration is required (for example ~/.cursor/mcp.json), the docs must explain:
    • why it exists outside the repo
    • which fields are project-critical
    • how to recreate and validate it

10) Non-canonical and exploratory content

Section titled “10) Non-canonical and exploratory content”
  • Exploratory notes, mental models, and scratch materials must be clearly marked as non-canonical.
  • They must not conflict with the canonical contracts in the main docs tree.
  • If exploratory content becomes authoritative, promote it into the canonical tree and update links accordingly.