Documentation Structure and Page Placement

This page is the placement contract for this documentation site. Read it before you add a page.

It exists because of a specific failure mode, not because of a general preference for tidiness. This site is navigable: every page is reachable from a sidebar and the sidebar labels are written around reader intent. What it lacks is a rule for deciding where a new page goes. Without one, each new feature's documentation lands wherever it happened to fit on the day it was written, and a single reader question ends up spread across four pages that each answer a quarter of it.

The rules below are the cheapest available fix: they cost a contributor about two minutes per page and they prevent the split that is expensive to undo later.

Scope of this page

This is about where a page lives and what it is called. For how to get any change merged (fork, branch, Conventional Commits, CI), see Contributing. For test conventions, see Writing Tests.

Two Structures, and Which One You Are Choosing

A page has two independent homes, and contributors routinely conflate them:

Structure	What it is	Who it serves
The directory under docs/	The file path, and therefore the URL	Search engines, inbound links, and the next contributor looking for the file
The sidebar section in sidebars.ts	The reader's clickable path	A reader browsing the site

They deliberately do not match one to one. docs/guides/configuring-policies.md lives in the guides directory but appears under the Governance and Security sidebar section, and there is no "Guides" section in the nav at all. That is fine. The directory is chosen by subject matter; the sidebar position is chosen by the journey the reader is on.

When you add a page you must choose both, and they are separate decisions.

The Section Map

One line each, for the directories under docs/. Use this to place the file.

Directory	What it is for (the reader's question it answers)	Typical page type
api	"What exact HTTP call do I make, with which headers, parameters, response shape, and error codes?" for the Agent and Orchestrator surfaces	Hand-written endpoint reference over the generated OpenAPI pages
architecture	"How does the system fit together, and where does AxonFlow sit in my stack?" Components, ports, request paths, and the contracts you build against	Conceptual explainer plus diagrams; no install steps
compliance	"Which regulator obligation applies to me, and which AxonFlow control maps to each article or circular?"	Regulation-to-control mapping with dated primary sources
contributing	"How do I get a change into the repo and have it accepted?"	Process and convention runbook
deployment	"How do I stand this up, size it, upgrade it, and fix it in an environment I operate?"	Operator runbook plus operational matrices
development	"How do I run AxonFlow on my own machine and exercise or benchmark it?"	Local setup plus testing methodology
enterprise	"What does the licensed product add for my organization, and what will org-wide adoption require?"	Product scope explainer and rollout checklist
examples	"What does AxonFlow look like applied to a domain like mine, and where is the code?"	Code samples and domain solution sketches
features	"Does this capability exist, is it in my tier, and what does it do at runtime?"	Capability explainer plus tier and limit matrices
governance	"Once a policy has fired, what does the platform record, explain, gate, or charge for?"	Concept page that becomes reference in its back half
guides	"Which knob do I turn, and to what value?" for someone who already has AxonFlow running	Config reference tables and design-pattern essays
identity	"How does a human or a machine prove who they are to AxonFlow, and how do I wire my IdP?"	Standards explainer plus per-IdP runbooks
industry	"What goes wrong when agents act in my sector, and which controls address it first?"	Sector mapping essay; never holds authoritative config
integration	"How do I put AxonFlow in front of the framework, IDE, or runtime I already use?"	Per-tool onboarding guide with a governance-coverage callout
llm	"Which model providers can AxonFlow call for me, with which credentials, and how does it route and fail over?"	Per-provider setup reference and cross-provider matrices
mcp	"How do agents reach an external data system through a governed connector, and what is enforced at that boundary?"	Per-connector spec reference plus phase-model concept pages
monitoring	"What aggregate signal can I scrape, chart, or export to see volume, latency, block rate, and spend?"	Metric and endpoint reference tables, dashboard setup
orchestration	"Should AxonFlow run my multi-step workflow, or just gate the steps of one my own engine runs?"	Decision tables, step references, and a day-two ops playbook
policies	"How do I author, place, tune, test, and ship a governance rule, and what does each field mean?"	Concept pages, field-level schema reference, copy-paste templates
protected	"I am a named enterprise customer or an AxonFlow operator: how do I run the operator-only surfaces and my engagement's deployment?"	Operator API reference, per-customer runbooks, commercial notes
releases	"What changed in version X, am I affected, and what must I do before upgrading?"	Frozen, dated release notes. See the freeze rule below
sdk	"Which client library and integration mode do I use for my language, and what is the minimal governed call?"	Support matrices plus per-language first-call samples
security	"What does the runtime actually detect, when does it check, what is the default action, and how do I harden it?"	Detector mechanism explainers plus a hardening checklist
trust	"What is your security posture, which controls exist versus do not, and how do I report a vulnerability?"	Posture attestation, control-status matrix, disclosure policy
tutorials	"Walk me end to end, from a running stack to a working governed scenario I built myself"	Sequenced, timed, prerequisite-declaring walkthroughs

Two pages sit at the root on purpose: getting-started.md is the install front door, and telemetry.md answers "what leaves my environment by default, and how do I turn it off". Do not add more root-level pages.

Boundary Tests for the Confusable Pairs

Most misplacements happen between one of these pairs. Each row is the question that settles it.

Pair	The discriminator
deployment vs development	Does the audience own production traffic? Anything about upgrades, cloud stacks, capacity, or incident recovery is deployment, even though both use docker compose up -d
development vs contributing	development is how to run and test locally. contributing is the process and conventions for submitting a change
enterprise vs features	features answers "does this capability exist, and in which tier", one capability across all tiers. enterprise answers "what does the licensed org-scale product look like"
enterprise vs deployment	If it has an install, upgrade, or migration procedure, it is deployment, even for Enterprise-only images
compliance vs api vs enterprise	Regulation-first is compliance; endpoint-first is api; product-bundle-first is enterprise. The same module legitimately appears in all three cuts
architecture vs api	architecture explains the request path and the client contract. api specifies exact paths, parameters, and bodies
governance vs policies	If the page teaches you to write or tune a rule, it is policies. If it teaches you to read, prove, approve, or pay for a decision, it is governance
governance vs guides	guides pages are keyed to a configuration surface an operator sets. governance pages are keyed to a platform capability a reviewer consumes
guides vs tutorials	tutorials build one continuous scenario from zero. guides assume a running deployment and answer one operational question
examples vs tutorials	If it has an estimated time and a "what you will learn", it is a tutorial. examples are browsable, unordered, with no completion state
integration vs llm	Direction of the call. llm is providers AxonFlow calls outward for you. integration is callers coming inward from a framework or IDE
integration vs mcp	Which side of the runtime the system sits on. Upstream caller is integration; downstream resource is mcp
integration vs orchestration/wcp	A new framework onboarding page is integration. A new step-gate concern is orchestration/wcp
monitoring vs governance	A question containing "who" or "which request" is the audit trail (governance). A question containing "how many" or "what trend" is metrics (monitoring)
identity vs governance	identity ends when the caller is authenticated and role-mapped. governance begins with what that caller was allowed to do
industry vs compliance	A page about one named regulation is compliance. A page about a sector's workflows and the controls they need is industry
security vs trust	security is builder-facing and configuration-level. trust is reviewer-facing and claim-level
enterprise vs protected	protected is what cannot be public at all: operator-only admin endpoints, list pricing, named-customer material. It is excluded from the public build

One Topic, One Home

Pick the section by the reader's question, not by the implementing subsystem.

This is the single rule that prevents the split this page exists to stop. A feature is usually built across several subsystems, and the temptation is to document each subsystem's part where that subsystem's docs live. The reader does not have your architecture diagram. They have one question.

The Worked Counter-Example

A portal user has forgotten their password and wants it back. That is one question. Today its answer is spread across four pages, none of which is the obvious destination:

• docs/identity/sso.md
• docs/identity/enterprise-authentication.md
• docs/enterprise/roles.md
• docs/identity/concepts.md

Each of those placements is individually defensible. Password reset touches SSO, so it is mentioned on the SSO page. It touches the enterprise auth flow, so it is mentioned there. Recovery depends on who is allowed to trigger it, so it is mentioned under roles. It involves an identity concept, so the concepts page defines it. Every step was locally reasonable, and the result is that a reader has to find and assemble four pages to answer one question, and a contributor updating the behavior has four places to keep in sync and will miss one.

Applying the rule instead: the reader's question is "how do I recover access to my portal account". That question has one home. Everything else links to it in one sentence.

Do not fix this example in passing

The portal authentication topic is being consolidated in a deliberately sequenced follow-up. Do not consolidate it as a drive-by change in an unrelated PR, and do not restructure docs/identity/enterprise-authentication.md while that work is open.

Other Recorded Splits

One more is known and is not yet fixed. docs/protected/api/admin-api.md and docs/protected/api/admin-organization-api.md are two endpoint references for the same /api/v1/admin surface, with overlapping route tables. They now have distinct titles so neither is ambiguous in search, but distinct titles are a workaround for a split, not a fix. Consolidating them is a follow-up, and needs a redirect so the retired URL keeps working.

Applying It

Write down the reader's question as a sentence beginning "How do I" or "What is". Then find the single row in the section map whose description matches that sentence. That row is the home. If two rows match, use the boundary table. If the boundary table does not settle it, say so in your PR description and propose one, rather than splitting the content across both.

Extend an Existing Page, or Add a New One?

The default is extend. New pages are the mechanism by which a topic fragments, so the bar for adding one is deliberately higher than the bar for adding a section to a page that already exists.

Extend an existing page when the reader would already be on that page to do the task. If someone configuring Okta SCIM needs to know about a new attribute mapping, that belongs on the Okta page. They are already there. A separate "Okta Attribute Mapping" page makes them find a second page to finish one job.

Add a new page when it is a distinct task with its own entry point. The test is whether a reader would ever arrive at this content directly, from search or from a link, without first being on the parent page. A new connector, a new provider, a new IdP, and a new regulation each get their own page, because readers arrive at them cold.

The Search-Result Test

Before you commit to a new page, apply this test:

If this page's title appeared alone in a list of search results, with no section, no breadcrumb, and no surrounding text, would a reader know whether it answers their question?

A title that fails this test is usually a sign that the content is a section of another page rather than a page of its own. "Attribute Mapping" fails. "Okta SCIM Attribute Mapping" passes, and if that page is worth having, the title tells you it is.

Title Rules

Titles are the highest-leverage thing you control, because search results and the site's own search index show the title and nothing else.

1. Titles must be unique across the whole repository. Check before you write one:

   grep -rh "^title:" docs --include="*.md" | sort | uniq -c | sort -rn | awk '$1>1'

   That command must print nothing. If it prints a count, you have created an ambiguous title and must qualify it.

2. Titles must be self-describing out of context. The reader sees the title without its section.

3. Bare API Reference, Troubleshooting, and Overview are banned as titles. They are not wrong, they are unqualified. Every one of them needs the subject in front of it. The disambiguations already applied here are the model to follow:

   Was	Now	Why
   API Reference (identity/scim/endpoints.md)	SCIM API Reference	The SCIM provisioning surface and its token management
   API Reference (orchestration/api-reference.md)	Orchestration API Reference	Multi-agent planning and the Workflow Control Plane
   API Reference (api/overview.md)	AxonFlow API Overview	The map of the Agent and Orchestrator surfaces, not a reference itself
   Troubleshooting (identity/scim/troubleshooting.md)	SCIM Troubleshooting	Discovery, tokens, provisioning, group sync
   Troubleshooting (deployment/troubleshooting.md)	Deployment Troubleshooting	The self-hosted runtime operational runbook
   Admin Organization API (protected/admin-api.md)	Admin Organization API Guide	The auth model and operating pattern
   Admin Organization API (protected/api/admin-organization-api.md)	Admin Organization API Reference	The route-by-route reference

4. sidebar_label may be shorter than the title, and often should be. The sidebar supplies the context that search results do not, so sidebar_label: Overview under a category named "API Reference" is correct even though title: Overview would not be. Set sidebar_label when the full title would make the sidebar noisy.

5. A hardcoded label in sidebars.ts or sidebars.enterprise.ts must be unique within its sidebar. These override the frontmatter, so a title fix alone does not fix the nav.

6. Do not rename a file to fix a title. The title is metadata; the filename is the URL. Changing the URL breaks inbound links and discards accumulated search ranking. Fix the title, leave the path alone.

Nesting Rule

Maximum four levels on the reader's path: section, category, page, anchor.

That means at most one intermediate category between a top-level sidebar section and the page itself. Anchors within the page are the fourth level and are free.

Depth is expensive in a way that is easy to underestimate. Every extra level is a collapsed container a reader has to guess the contents of before clicking, and it pushes the page further from the sidebar's scan path. If a category needs a third level to stay organized, that is usually evidence the parent section is holding two different topics rather than evidence that more nesting is needed.

Two corollaries:

• A category containing a single page is noise. Replace it with the page. The API Connectors category, which wrapped only the HTTP connector page, was removed for this reason.
• A category whose label duplicates its only child is noise twice over. Same fix.

Known Depth Exceptions to Fix Later

The measured maximum on this site is four sidebar levels plus anchors, which is one category level beyond the rule. No branch is deeper than that. The following six branches are the entire set of exceptions. They are recorded here rather than silently tolerated, and none of them should be fixed by a drive-by change, because fixing them means moving pages and therefore breaking inbound links.

Branch	Pages	Note
Model & Connector Runtime > LLM Providers > Community Providers	6	The Community and Enterprise split is a real tier distinction, so flattening loses information
Model & Connector Runtime > LLM Providers > Enterprise Providers	2	Small enough to merge upward if the tier split is signalled on the pages instead
Model & Connector Runtime > MCP Connectors > Database Connectors	5	Connector grouping by kind; the parent category is large enough that flattening all of it would be worse
Model & Connector Runtime > MCP Connectors > Storage Connectors	3	As above
Model & Connector Runtime > MCP Connectors > Enterprise Connectors	7	As above
Governance & Security > Identity & Access > SCIM Provisioning	8	The largest exception; a candidate for promotion to its own top-level section rather than flattening

Do not add a seventh. If a new page needs a third category level, raise it in the PR instead.

Cross-Linking Over Duplication

Link to the authoritative page rather than restating it. If you must restate something so the current page stands on its own, keep it to one sentence plus a link. The moment a restatement grows to a paragraph it becomes a second copy that will drift, and drifted copies of governance and compliance behavior are worse than no copy.

Two sanctioned alternatives to duplicating content:

• Cross-list the page in a second sidebar branch. Docusaurus allows one page to appear at more than one place in the nav, and this site already does it for around 43 pages, mostly so that the curated Enterprise Readiness journey can reuse pages that also live in their subject sections. One file, one URL, two entry points, zero drift. This is the right tool when two audiences need the same page.
• Link out from a short mapping page. The industry section works this way on purpose: it maps a sector's problems to controls and links to the authoritative pages, and never holds the configuration itself.

Release Notes Are Frozen

Never edit a published page under docs/releases/. A release note is a record of what shipped on a date, not a description of current behavior. Editing one falsifies the record, and it also breaks a guard: scripts/validate_version_pins.py derives the site's expected current platform version from the highest-numbered page in that directory, and treats everything under it as a historical marker that must never be rewritten.

If current behavior has moved on from what a release page describes, document that on the relevant subject page and link forward. Leave the release page as it was. For when a release page is required at all, see the release notes policy in Contributing.

Formatting Rules That Are Enforced

• Admonition titles must be bracketed. This site runs Docusaurus 3, where the title goes in square brackets:

  :::warning[Rotate the key first]

  The version 2 form, :::warning Rotate the key first, renders the title as literal body text. It does not error, so it is easy to ship broken.

• ASCII hyphens only. No em dashes or en dashes anywhere in prose.

• Do not hardcode a current platform version unless it is a genuine historical or minimum-version marker. scripts/validate_version_pins.py checks the pin shapes it knows about; run it before pushing:

  python3 scripts/validate_version_pins.py

Checklist Before Opening a Docs PR

• The reader's question is written as one sentence, and it maps to exactly one section in the map above
• The duplicate-title command prints nothing
• The title passes the search-result test with no section or breadcrumb around it
• The page adds at most one category level under its top-level section
• Anything restated from another page is one sentence plus a link
• No file under docs/releases/ is modified
• Admonition titles are bracketed
• npm run build and npm run build:enterprise both succeed
• python3 scripts/validate_version_pins.py passes