This page defines how ProxAI documentation should evolve. It is maintainer-facing and complements AGENTS.md.
| Section | Owns | Should not own |
|---|---|---|
using/ | Task walkthroughs for running, configuring, routing, observing, and troubleshooting. | Source-level implementation detail or exhaustive field lookup. |
protocol/ | Wire behavior, request paths, protocol concepts, streaming expectations, and interaction examples. | Internal Rust module ownership unless needed for context. |
developer/ | Implementation boundaries, module maps, conversion internals, streaming internals, and contributor workflow. | Casual user onboarding or SEO-facing product copy. |
reference/ | Stable lookup values, defaults, exact fields, behavior contracts, glossary, and tables. | Step-by-step tutorials or speculative future features. |
Every en/ page should have the same relative path under zh/. Structure should stay aligned even when wording is not literal translation.
Pages under developer/ should include robots: noindex so casual search traffic lands on user-facing docs first.
Reference pages should prefer exact values, compact tables, and behavior contracts over narrative walkthroughs.
Prefer MDX components for cards, lookup tables, timelines, module maps, and protocol matrices instead of raw Markdown tables.
Do not reintroduce legacy root pages. Current public docs live under using/, protocol/, developer/, and reference/.
Never commit captures, logs, prompts, API keys, Authorization headers, or private upstream payloads.
| Change | Docs to check |
|---|---|
| Runtime config field | using/configuration, reference/configuration, reference/defaults-and-limits, config.example.toml, README files. |
| Protocol conversion behavior | protocol/, developer/protocol-conversion, reference/protocols, reference/status-and-stop-reasons. |
| Streaming behavior | protocol/streaming-behavior, developer/streaming-internals, reference/behavior-contracts. |
| Error response behavior | using/troubleshooting, reference/error-responses, developer/error-handling-internals, behavior contracts. |
| Release/deployment docs | using/install-and-upgrade, site/README.md, Netlify config if site publishing changes. |
Run the site check before publishing docs:
just site checkThis builds the Starlight site and runs the docs checker for bilingual pairs, sidebar slugs, internal links, anchors, stale paths, table leftovers, developer noindex, hub coverage, and heading quality.