Skip to content

Docs Parity Rules

Docs parity means the documentation that Codex and humans rely on stays aligned with the current engineering state.

Anuva treats docs as part of the implementation, not as a separate cleanup activity.

flowchart TD
  change["Engineering change"] --> impact{"Docs impact?"}
  impact -->|none| note["Record no-docs-impact if useful"]
  impact -->|local| local["Update owning repository docs"]
  impact -->|shared| handbook["Update handbook docs or registries"]
  impact -->|product| productMain["Update product-main docs, issues,\nor project status"]
  impact -->|published| publisher["Update anuva-dev-docs\naggregation or status page"]

  local --> verify["Verify docs links and checks"]
  handbook --> verify
  productMain --> verify
  publisher --> verify
  note --> complete["Complete"]
  verify --> complete

What Must Stay In Parity

Change Type Required Docs Action
Repository ownership changes Update repository registry.
Capability ownership changes Update capability registry.
New repository onboarding Add registry entry, AGENTS guidance, workflow pointer, and publishing decision.
Shared workflow changes Update development process docs and affected templates or prompts.
Skill changes Update skill docs and shared skill catalog.
Product feature task progress Update product-main progress docs, GitHub issues, GitHub Project fields, and linked PR completion reports.
Publishing changes Update anuva-dev-docs, MkDocs nav where relevant, publishing scripts, status page generation, and publishing guidance.
Local implementation behavior changes Update local repository docs first.

Local Versus Handbook Docs

Use this rule:

  • Local repository docs explain implementation details.
  • Handbook docs explain Anuva-wide architecture, ownership, process, and routing.
  • Product-main docs explain product architecture, feature plans, repository impact, issue handoffs, and release readiness.
  • anuva-dev-docs publishes selected knowledge for discovery.

Do not copy full implementation docs into the handbook. Link, summarize, or register ownership instead.

Product-Main Versus Implementation Docs

Use this rule for Video Creator:

  • anuva-main-video-creator explains what the product needs, which repositories are affected, what GitHub issues were created, and how the feature is progressing.
  • anuvax-cms, anuva-python-server, and anuva-unity-video-creator explain how their own implementation works.
  • GitHub issues carry the repository-specific handoff context.
  • Pull requests carry completion reports back to the issue and project.

Example:

flowchart LR
  main["Product feature docs\nanuva-main-video-creator"] --> issue["GitHub issue\nrepository handoff"]
  issue --> repo["Implementation repo docs"]
  repo --> pr["PR completion report"]
  pr --> project["GitHub Project status"]
  project --> mainProgress["Product-main Progress.md"]

Publishing Parity

Each repository owns its source Markdown. anuva-dev-docs owns the generated aggregate site.

When repository docs change:

  • run the repository's local docs checks where available
  • ensure mkdocs.yml includes new, moved, or renamed pages
  • trigger or document the required anuva-dev-docs refresh
  • verify project-status.html still reflects the GitHub Project when project status changed

Repositories without MkDocs setup may be skipped by the publisher, but the skip should be visible in the build summary.

MkDocs Nav Rule

When adding, renaming, moving, or deleting handbook pages, update mkdocs.yml in the same change.

Navigation paths are relative to docs/.

Mermaid Rule

New architecture, process, workflow, registry, and lifecycle pages should include Mermaid when a diagram improves scanability.

Use:

  • flowchart for routing, dependencies, and process maps
  • sequenceDiagram for multi-party interactions
  • stateDiagram-v2 for lifecycles
  • erDiagram or classDiagram only when documenting data relationships

Docs Parity Checklist

Use this checklist before closing a change:

  • Did repository ownership change?
  • Did capability ownership change?
  • Did a workflow rule change?
  • Did Codex behavior guidance change?
  • Did a skill, template, or prompt need to change?
  • Did a new page require mkdocs.yml nav updates?
  • Did local implementation docs need updates?
  • Did product-main feature docs, progress docs, or GitHub task docs need updates?
  • Did GitHub issues, PR descriptions, or GitHub Project fields need updates?
  • Did anuva-dev-docs need to rebuild the aggregate site or project status page?
  • Were docs checks or link checks run where available?

Verification

For handbook docs-only changes:

git diff --check
mkdocs build --strict

If mkdocs is not installed, record that the strict build could not be run.