Skip to content

Documentation Lifecycle

The Anuva Development Process Policy defines the approved split between lightweight preview and strict verification. Phase 3 Gate 2 installed and accepted clean build 0.2.1-g3dd30bca40f1 on machine one. The commands below are now the active Product Main contract. docs ensure, docs wait, and docs validate-indexes remain available for rollback compatibility.

Active Phase 3 contract

Use:

anuva docs preview --repository current --file <paths...>
anuva docs verify --repository current --file <paths...>

docs preview starts or health-checks an owned process, relies on live reload, and returns exact URLs without a timestamp or strict build. Content, branch, and HEAD changes do not restart that process. Command, working-directory, port, configuration, health, and trusted process-identity changes remain restart or refusal reasons.

docs verify validates meaningful navigation, local links, orphans, sections, and indexes; runs one strict build; and compares all requested pages without requiring --since or a process restart. A matching external listener may be used for that invocation only and is never adopted or terminated.

The accepted installation reports current=0.2.1-g3dd30bca40f1 and previous=0.2.0-gc8776c067168. The checksum-manifested legacy-source target also remains installed as the first-install recovery artifact.

Two documentation surfaces

Surface Meaning Update behavior
Machine-specific MkDocs site Live preview of one repository branch and source generation, including uncommitted edits Full-rebuild mkdocs serve; owned and generation-tracked by the Anuva CLI
anuva.girishd.com Canonical aggregate of reviewed repository docs Manually rebuilt and pushed only when requested

Cloudflare Access with email OTP protects the canonical site. Apply an equivalent Access policy to every machine-specific Web and docs hostname because a published Tunnel hostname is otherwise Internet reachable.

Follow Cloudflare Tunnel and Access Setup for the one-time Access, tunnel, route, certificate, and per-machine connector configuration.

Repository ports

The current mkdocs.yml files define:

Repository Port Machine 1 hostname Machine 2 hostname
Product Main 4001 main1.girishd.com main2.girishd.com
Bento 4005 bento1.girishd.com bento2.girishd.com
CMS 4002 web1.girishd.com web2.girishd.com
Python 4013 python1.girishd.com python2.girishd.com
Unity 4004 unity1.girishd.com unity2.girishd.com

The CLI should bind MkDocs to 127.0.0.1 with -a even though the checked-in configs currently use 0.0.0.0; cloudflared runs on the same machine and does not require a LAN listener.

Skill contract for Markdown changes

Every skill that creates or modifies docs/**/*.md must:

  1. Run anuva docs preview --repository current --file <anticipated-paths...> before the first edit. It must start or reuse a healthy CLI-owned process and return the exact review URLs without a strict build or timestamp.
  2. Make a coherent documentation update.
  3. Keep user-facing sections reachable through a meaningful index.md or an explicit mkdocs.yml navigation entry. Asset, generated, archive, and organizational-only directories do not require boilerplate indexes.
  4. Run one anuva docs verify --repository current --file <all-changed-paths...> invocation after the logical update. It validates structure, performs one strict build, and compares every requested live page with that build.
  5. Run anuva docs links --repository current --file <all-changed-paths...> and include the returned HTTPS page URLs in the next Codex response, including an approval pause.

anuva docs status distinguishes owned-healthy, owned-config-stale, owned-unhealthy, stale-registry, external-listener, port-conflict, and stopped states. docs preview never trusts or terminates an unowned listener. Resolve an external or conflicting process deliberately before retrying.

Example mapping:

docs/changes/2026-07-14-render-progress/ImplementationPlan.md
-> https://web1.girishd.com/changes/2026-07-14-render-progress/ImplementationPlan/

The CLI derives URLs from machine configuration and MkDocs settings; skills must not hard-code machine1. Files outside docs_dir, including AGENTS.md, README.md, and repository-local skill files, receive local file links instead.

Manual canonical publication

The future command is:

anuva docs publish --push --confirm

Without --push, it builds the aggregate locally. Publication is never an implicit step of a change workflow. See the CLI implementation plan for the PowerShell-port parity requirements.

References: MkDocs CLI, Cloudflare published applications.