ADR 0009 — afia-docs as the documentation repo

Status: proposed
Date: 2026-09-20

Context

Humans and agents now read the same pack under workspace-root ai-agent/ (ADR 0005, ADR 0008). That tree has no site, no git remote, and no way for a later afia-api checkout to vendor it.

Store legal pages already live as static HTML on afia-web. The pack checker hardcodes AGENT = ROOT / "ai-agent" and sibling product AGENTS.md files. Moving markdown without a plan fails that gate.

Decision

Documentation will live in a repo named afia-docs. The Docusaurus site and GitLab Pages job stay on main. Product repos mount only the markdown tree: they submodule the content branch at docs/ (Product, Tech, Decisions, Agent). They do not vendor package.json, CI, or other site files.

Each page has three fields:

Field	Values
Audience	human, agent, both
Kind	guide, reference, decision, brief, machine-index
Owner	a work-package id, a product repo, or pack

The site is one Docusaurus docs plugin with four sidebars. Not four plugin instances.

Sidebar	Kind
Product	Hand-authored user guides. Roles and situations. No HTTP paths. English, French, and Arabic.
Tech	Pack maps, api-map, and docs/tech/{api,app,exchange}
Decisions	ADRs
Agent	Feature catalog, work-package index, and task briefs

Until cutover, ai-agent/ stays the source of truth for Tech, Decisions, and Agent. A sync script copies that markdown and rewrites relative links. Product pages live only in afia-docs/docs/product. Agents keep the ADR 0005 load order.

Cutover is a later change. It rewrites the six TSVs, check-agent-pack.py, every AGENTS.md, and the layout sentences in ADR 0005 and ADR 0008 in one wave. After that, the consumer mount is still docs/.

These stay out of the site:

• manifest/*.tsv (machine-index)
• memory/ and .audit/ (session)
• scripts/*.py (tooling)
• afia-web/*.html (store URLs)
• AFIA-resources/design.txt (Stitch id list)

EndpointUri stays the HTTP path source (ADR 0005). Tech specs stay three markdown trees before code (ADR 0008). Do not invent Stitch screens.

Consequences

• First build must keep python3 ai-agent/scripts/check-agent-pack.py at PASS.
• afia-web legal filenames stay the store URLs. The site may link to them. It does not replace them.
• A consumer-root AGENTS.md stays in each product repo after split. The docs repo does not own Cursor load-order stubs.
• Adding a work package still means three tech-spec files and three TSV rows until cutover rewrites those paths.
• Product is the only translated tree. Locales are en, fr, and ar. Arabic is RTL. A missing French or Arabic Product file fails npm run build. Tech, Decisions, and Agent stay English under every locale prefix.