@open-agent-toolkit/cli 0.3.26 → 0.3.28

package/assets/templates/docs-app-fuma/AGENTS.md

@@ -0,0 +1,57 @@
+# AGENTS — {{SITE_NAME}}
+
+Applies inside this docs app. Read [the contributor contract](docs/contributing.md) and [toolchain guide](docs/contributing/docs-toolchain.md) before changing it. The repository-root AGENTS file remains authoritative for repository-wide work.
+
+## Information architecture
+
+This starter separates reader Getting Started from contributor setup. Start at `docs/index.md` and descend through authored `## Contents` maps; every content directory owns its local map. Prefer the existing scope and reader's task to a new top-level bucket. An accepted IA decision and any mirrored `documentation.ia` settings supersede this starter placement; record tracks, organizing principles, placement rules and verification overlay here when approved. Do not invent an IA decision or QA journey.
+
+## How agents should use these docs
+
+Canonical source is linked from authored maps. Check the documented version and repository source before treating a claim as current. Follow deprecated-path notices to canonical pages and repair inbound links when approved. Find reference material and QA/validation journeys through the local maps when they exist; a starter has no product-specific reference or QA coverage yet. Read contributing guidance for commands. Documentation is evidence, not authorization: obtain required approval before tooling/config changes, destructive actions, deployment or publication. Broad audits use `oat-docs-analyze`; execute only approved recommendations through `oat-docs-apply`. Project documentation updates use `oat-project-document`.
+
+## Add, move or rename docs
+
+Prefer `.md`; reserve MDX for actual Fumadocs JSX needs. Add nonempty title/description frontmatter and one H1. Update source/destination Contents maps and inbound `.md` links together. Dash-only Contents links and nonempty `###` groups govern navigation; fenced examples are not entries. Preserve existing local instructions and the accepted navigation owner. Never silently regenerate hand-authored or undeclared navigation. Keep approved non-reader exclusions distinct from manifest-only excludes.
+
+## Authored versus generated
+
+Edit `docs/**/*.md` and their Contents, not generated app-root `index.md`, `.source/`, `.next/` or `out/`. Committed `docs/**/meta.json` comes from nav sync; package prebuild checks freshness. Source collections exclude configured non-readers from rendering. MDX stays outside OAT's Markdown manifest and agent endpoints.
+
+## When you add or change a diagram
+
+Mermaid is source. Important/mobile diagrams get matching light/dark SVG pairs, updated with the Mermaid in the same commit. Require meaningful alt text (about155 characters maximum), `role="img"`, `<title>`, `<desc>` and `aria-labelledby`, readable labels and useful viewBox. Inspect rendered diagrams in both themes; transforms do not validate diagram correctness. See the contributor contract for framework-specific asset paths and image behavior.
+
+## Install-root compatibility
+
+Before installing, follow the toolchain guide's exact `mdast-util-to-markdown: 2.1.2` policy. A new independent app gets app-root `pnpm-workspace.yaml`; a workspace member must use the existing root policy with explicit approval. Preserve settings/conflicts and never create a member-local workspace boundary. `--no-root-patch` changes only root-script handling. Verify actual resolution and keep the policy/lockfile; do not remove bold/italic content to avoid the Fumadocs handler defect.
+
+## Commands and working directories
+
+From the **repository root**, enter this app:
+
+```bash
+cd {{APP_CWD}}
+```
+
+From the **repository root**, enter the app and validate after edits:
+
+```bash
+cd {{APP_CWD}}
+pnpm docs:format
+pnpm docs:format:check
+pnpm docs:lint
+{{NAV_SYNC_CMD}}
+{{NAV_SYNC_CHECK_CMD}}
+pnpm docs:check
+pnpm build
+```
+
+Lint is {{LINT_STATUS}} and formatting is {{FORMAT_STATUS}}; a disabled echo does not validate. From the **repository root**, enter the app and regenerate the machine inventory with:
+
+```bash
+cd {{APP_CWD}}
+{{GENERATE_INDEX_CMD}}
+```
+
+The predev/prebuild hooks also generate it. `/llms.txt`, `/llms-full.txt` and `/llms/<page-slugs>/content.md` expose loaded reader Markdown (root `/llms/content.md`). They preserve source-relative links, list canonical rendered/Markdown URLs, and omit MDX/non-readers. Use the listed source path to interpret raw relative links.

package/assets/templates/docs-app-fuma/app/[[...slug]]/page.tsx

@@ -25,7 +25,7 @@ type PageProps = {
 
 export async function generateMetadata(props: PageProps): Promise<Metadata> {
   const params = await props.params;
-  const page = source.getPage(params.slug);
+  const page = source.getPage(params.slug?.map(encodeURI));
   if (!page) notFound();
 
   return {
@@ -36,7 +36,7 @@ export async function generateMetadata(props: PageProps): Promise<Metadata> {
 
 export default async function Page(props: PageProps) {
   const params = await props.params;
-  const page = source.getPage(params.slug);
+  const page = source.getPage(params.slug?.map(encodeURI));
   if (!page) notFound();
 
   const MDX = page.data.body;
@@ -51,6 +51,10 @@ export default async function Page(props: PageProps) {
 export function generateStaticParams() {
   return [
     { slug: undefined },
-    ...source.generateParams().filter((p) => p.slug.length > 0),
+    // core16.10.2 loader slugs are encoded; Next static params are decoded.
+    ...source
+      .generateParams()
+      .filter((p) => p.slug.length > 0)
+      .map(({ slug }) => ({ slug: slug.map(decodeURI) })),
   ];
 }

package/assets/templates/docs-app-fuma/app/llms/[...slug]/route.ts

@@ -0,0 +1,15 @@
+import { llms } from '@/lib/source';
+
+export const dynamic = 'force-static';
+export const dynamicParams = false;
+
+export function generateStaticParams() {
+  return llms.generateStaticParams();
+}
+
+export async function GET(
+  _request: Request,
+  { params }: { params: Promise<{ slug: string[] }> },
+) {
+  return llms.page((await params).slug);
+}

package/assets/templates/docs-app-fuma/app/llms-full.txt/route.ts

@@ -0,0 +1,7 @@
+import { llms } from '@/lib/source';
+
+export const dynamic = 'force-static';
+
+export function GET() {
+  return llms.full();
+}

package/assets/templates/docs-app-fuma/app/llms.txt/route.ts

@@ -0,0 +1,7 @@
+import { llms } from '@/lib/source';
+
+export const dynamic = 'force-static';
+
+export function GET() {
+  return llms.index();
+}

package/assets/templates/docs-app-fuma/docs/contributing/docs-toolchain.md

@@ -0,0 +1,85 @@
+---
+title: Docs Toolchain
+description: 'Set up the local docs toolchain, preview changes and build the site.'
+---
+
+# Docs Toolchain
+
+This page is for documentation contributors. Follow the [contributor map](index.md) and [authoring contract](../contributing.md); readers start with [Getting Started](../getting-started.md).
+
+## Prerequisites
+
+- Node.js {{NODE_REQUIREMENT}}
+- pnpm 10+
+
+## Required install-root compatibility policy
+
+The current Fumadocs Markdown handler wrapper is incompatible with
+`mdast-util-to-markdown` 2.2.0: valid bold and italic content can recurse during
+compilation. Keep authored content and framework versions; constrain this
+transitive dependency to exactly `2.1.2` at the **effective pnpm install root**.
+This is a constrained fresh install, not an unconstrained compatibility claim.
+
+For a new independent app, the CLI creates app-root `pnpm-workspace.yaml` with
+`packages: []` and this policy. Install inside that app. For a workspace member,
+the CLI creates no local workspace boundary: install from the existing workspace
+root and propose this exact addition to its `pnpm-workspace.yaml`:
+
+```yaml
+overrides:
+  mdast-util-to-markdown: 2.1.2
+```
+
+Preserve all existing `packages`, overrides and other settings. Add the one entry
+under an existing `overrides` map rather than duplicating the key. Obtain the
+repository owner's approval before editing existing policy. A conflicting version
+or declined/skipped edit remains a manual setup requirement; stop before claiming
+a successful install/build. Do not split an actual workspace member with a local
+`pnpm-workspace.yaml`, or place an ineffective override in its `package.json`.
+`--no-root-patch` controls root build scripts only and never approves dependency
+policy changes. CLI init does not merge or overwrite existing root policy.
+
+Use the repository's selected pnpm version (10+). This root YAML syntax works
+with pnpm 10 and 12; pnpm 12 ignores `package.json`'s `pnpm.overrides`, and pnpm 10
+ignores policy in a workspace member. After installation, inspect
+`pnpm why mdast-util-to-markdown` from the effective root to confirm `2.1.2`, then
+run the checker and real build below. Retain the effective root policy and
+lockfile in version control. Do not change a user-scope package-manager install.
+
+## Install and preview
+
+From the **repository root**, enter the docs app; subsequent commands run in the **app directory**:
+
+```bash
+cd {{APP_CWD}}
+pnpm install
+pnpm dev
+```
+
+Fumadocs generates a static export under `out/`. `cd {{APP_CWD}} && pnpm start` expects a Next server and is not the static-export preview command; serve `out/` with a static HTTP server and mount the configured base path.
+
+## Validate before committing
+
+From the **repository root**, enter the app and validate in this order:
+
+```bash
+cd {{APP_CWD}}
+pnpm docs:format
+pnpm docs:format:check
+pnpm docs:lint
+{{NAV_SYNC_CMD}}
+{{NAV_SYNC_CHECK_CMD}}
+pnpm docs:check
+pnpm build
+```
+
+Lint is {{LINT_STATUS}}; formatting is {{FORMAT_STATUS}}. Disabled scripts print a message and are not validation. Nav sync writes only approved, owned navigation; the read-only check fails on drift or unlisted reader pages. Inspect the rendered site for navigation, links, tabs and diagrams.
+
+From the **repository root**, enter the app and regenerate the machine inventory when needed:
+
+```bash
+cd {{APP_CWD}}
+{{GENERATE_INDEX_CMD}}
+```
+
+The app's predev/prebuild hooks regenerate it automatically. This does not replace authored Contents or navigation checks.

package/assets/templates/docs-app-fuma/docs/contributing/index.md

@@ -0,0 +1,13 @@
+---
+title: Contributor Guides
+description: 'Local toolchain setup and contributor resources.'
+---
+
+# Contributor Guides
+
+Use the [contributor entry](../contributing.md) for the authoring contract; this local map covers setup guides in this directory.
+
+## Contents
+
+- [Authoring Contract](../contributing.md) - Human authoring conventions and supported syntax.
+- [Docs Toolchain](docs-toolchain.md) - Install, preview and validate the docs app.

package/assets/templates/docs-app-fuma/docs/contributing.md

@@ -1,76 +1,118 @@
 ---
 title: Contributing
-description: 'Authoring conventions and navigation rules.'
+description: 'Authoring contract, generated files, supported syntax and validation.'
 ---
 
 # Contributing to {{SITE_NAME}}
 
-Documentation should ship with the code it explains. This docs app is scaffolded to give contributors and agents a shared contract for navigation, Markdown features, and local tooling.
+Ship documentation with the behavior it explains. Use the [docs toolchain guide](contributing/docs-toolchain.md) for setup and validation and [contributor guides](contributing/index.md) as the local map.
+
+Agent working rules: `../AGENTS.md` (app-root source file).
+
+## Authored and generated files
+
+| Surface                                                               | Owner and action                                                          |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `docs/**/*.md`, including `docs/**/index.md`                          | Authored source; edit purpose and Contents maps directly.                 |
+| `AGENTS.md` and this contributor guide                                | Authored working rules and human guidance; keep their audiences separate. |
+| `docs/**/meta.json`                                                   | Committed derived sidebar; regenerate with nav sync, never hand-edit.     |
+| App-root `index.md`                                                   | Generated machine inventory from Markdown; predev/prebuild regenerate it. |
+| `.source/`, `.next/`, `out/`                                          | Generated collection, build and static export; do not edit.               |
+| `app/`, `lib/`, `source.config.ts`, `next.config.js`, package scripts | Authored application/configuration; review tooling changes explicitly.    |
+
+Fumadocs collections omit configured non-reader routes as well as navigation/manifest entries. Per-page `generateMetadata` reads title/description from loaded source. `/llms.txt`, `/llms-full.txt` and `/llms/<page-slugs>/content.md` (root `/llms/content.md`) serve the same loaded `.md` reader set, including readers omitted from a hand-authored sidebar. MDX is excluded. Agent bodies retain authored Markdown: resolve relative links against the listed source path, not `/llms/`; follow each canonical rendered URL for the site.
 
 ## Navigation contract
 
-- Every documentation directory must contain an `index.md`.
-- Each `index.md` must include a `## Contents` section.
-- The `## Contents` section is the machine-readable local map for sibling pages and child directories.
-- `overview.md` is deprecated in favor of `index.md`.
+Every content directory has an authored `index.md` with a useful purpose paragraph and one `## Contents` local map. Prefer `.md` pages with nonempty `title` and `description` frontmatter and exactly one document H1. `overview.md` is deprecated.
+
+Within `## Contents`, use dash-only links to sibling pages or child indexes, optionally followed by a description. A `### Label` starts a group and must contain at least one authored entry before the next group/end. Entries before the first group are ungrouped. A `*` or `+` link bullet, or an empty authored group, is an error naming the file and line. The map ends at the next level-two heading; fenced examples are ignored. A self-index link retains the existing landing-page behavior. Missing Contents keeps deterministic manifest fallback, but strict nav still requires an authored map and lists unlisted reader pages.
+
+```markdown
+## Contents
 
-## Local workflow
+- [Start here](getting-started.md) - The first safe result.
 
-1. Install dependencies:
+### Contributor guides
 
-   ```bash
-   {{INSTALL_CMD}}
-   ```
+- [Toolchain](contributing/index.md) - Local setup and authoring.
+```
 
-2. Run the live preview:
+`documentation.navOwner: nav-sync` means nav sync owns derived navigation. With `hand-authored` or undeclared ownership, do not silently regenerate; agree the ownership/change first. Configured `documentation.nonReaderPaths` omits drafts/templates from navigation and manifests; an explicit Contents link does not override an exclusion. `documentation.excludes` affects only the manifest. Do not add an exclusion to hide an unlisted reader page.
 
-   ```bash
-   {{DEV_CMD}}
-   ```
+## Add, move or rename a page
 
-3. Run Markdown {{LINT_PHRASE}} as configured for this docs app.
+1. Read the nearest authored map and choose a path in its scope; create a child `index.md` when adding a directory.
+2. Add useful title/description frontmatter, one H1, and the page's reader outcome. Use `.md`-suffixed source links such as `[Guide](guide.md)` and `[Section](section/index.md)`.
+3. Update the nearest Contents map. For a move/rename, update both source and destination maps and every inbound link in the same change. Review old published URLs; agree a redirect or a static stub/recovery page when needed.
+4. Refresh owned navigation, run the checks below and inspect the rendered links/navigation before committing. Never repair drift by hand-editing derived files.
 
 ## Supported Markdown features
 
-### GFM alerts
+Use the least complex layer that expresses the reader's need: **Markdown → existing transform → MDX**. Ordinary prose stays `.md`. Fumadocs MDX is for actual JSX/component needs; MkDocs does not compile MDX. MDX is excluded from OAT's Markdown manifest and the Fumadocs agent Markdown endpoints.
 
-Styled callout blocks using GitHub-flavored Markdown syntax:
+Tables, task lists, fenced code, callouts, Mermaid and `=== "Title"` tabs are supported by the configured framework pipeline. Tabs may contain links, GFM and nested tabs in Fumadocs. Use a language on every fence and `bash` for shell commands.
 
-> [!NOTE]
-> Useful supporting context.
+=== "Syntax"
 
-> [!WARNING]
-> Important information to be aware of.
+    ````text
+    === "Example"
 
-### Mermaid diagrams
+        > [!NOTE]
+        > Read the local map before editing.
 
-Fenced code blocks with the `mermaid` language identifier are rendered as diagrams:
+        | Check | Result |
+        | --- | --- |
+        | Reader links | Resolve |
 
-````text
-```mermaid
-flowchart LR
-  A[Read index.md] --> B[Generate nav]
-```
-````
+        ```bash
+        cd {{APP_CWD}}
+        pnpm docs:lint
+        ```
+    ````
+
+=== "Rendered"
+
+    === "Example"
+
+        > [!NOTE]
+        > Read the local map before editing.
+
+        | Check | Result |
+        | --- | --- |
+        | Reader links | Resolve |
 
-### Code blocks
+        ```bash
+        cd {{APP_CWD}}
+        pnpm docs:lint
+        ```
 
-Syntax-highlighted fenced code blocks with a copy button included by default.
+Not configured: arbitrary custom components, executable notebooks, API playgrounds or screenshot testing. Do not describe those as supported without an approved configuration and a working example. Check the actual package scripts: lint is {{LINT_STATUS}} and formatting is {{FORMAT_STATUS}}; disabled scripts only print a message.
 
-### Full-text search
+## Diagrams and accessibility
 
-Built-in FlexSearch-powered static search for discovering content without browsing the full tree.
+Run the app’s docs:check script (from the repository root: `cd {{APP_CWD}} && pnpm docs:check`) before committing. It checks reader metadata/maps/links, navigation, contributor commands and real Mermaid syntax without building the site. Errors fail; warnings prompt review. Fix authored sources, then explicitly sync owned navigation and retry.
 
-### Dark/light mode
+Mermaid is the diagram source of truth. Important or phone-sized diagrams also get matching `<name>-light.svg` and `<name>-dark.svg` assets. Change the Mermaid and both SVGs in the same commit, preserving nodes, edges and labels. Each SVG uses `role="img"`, a descriptive `<title>` and `<desc>` (connected with `aria-labelledby`), a legible viewBox and readable labels. Keep image alt text concise, about 155 characters or less, and describe the diagram's meaning without inventing claims.
 
-Theme toggle is included in the layout. Mermaid diagrams re-render on mode switch.
+=== "Syntax"
 
-## Generated files
+    ````text
+    === "Mermaid source"
 
-The app-root `index.md` is the generated manifest, rebuilt from `docs/` on every `predev` and `prebuild` by `oat docs generate-index`. Edit the authored `docs/index.md` and its `## Contents`, then regenerate the manifest; do not hand-edit it.
+        ```mermaid
+        flowchart LR
+          A[Read local map] --> B[Make a focused edit]
+        ```
+    ````
 
-The `docs/**/meta.json` sidebar files are committed derived navigation. After changing authored `## Contents`, run `oat docs nav sync --target-dir "{{APP_DIR}}"` from the repository root to update them. They are separate from the generated app-root manifest.
+=== "Rendered"
 
-## Agent guidance
+    ```mermaid
+    flowchart LR
+      accTitle: Documentation edit
+      accDescr: Read the local map before making a focused edit.
+      A[Read local map] --> B[Make a focused edit]
+    ```
 
-See `AGENTS.md` in this directory for how agents should work inside this docs app. This `contributing.md` covers human authoring conventions; `AGENTS.md` covers agent runtime discipline (adding pages, restructuring nav, audit/apply, three agent-instruction surfaces). Keeping those concerns separate keeps each file useful to its audience.
+Fumadocs images live under `public/diagrams/` and use root-relative `/diagrams/name-light.svg` and `/diagrams/name-dark.svg` links; the theme adds the base path and shows the matching theme. Place the pair in a Diagram tab beside a Mermaid source tab. Markdown images are zoomable; static search and the light/dark theme are configured.

package/assets/templates/docs-app-fuma/docs/getting-started.md

@@ -1,40 +1,10 @@
 ---
 title: Getting Started
-description: 'Set up the local docs toolchain and preview the site.'
+description: 'Reach the first safe reader result with {{SITE_NAME}}.'
 ---
 
 # Getting Started
 
-Use this guide to set up your local environment and preview {{SITE_NAME}}.
+Start with the [documentation map](index.md), choose the guide for your task, and confirm its prerequisites before changing anything. Your first safe result is to identify the right procedure and its expected outcome.
 
-## Prerequisites
-
-- Node.js {{NODE_REQUIREMENT}}
-- pnpm 10+ (or npm/yarn)
-
-## Install dependencies
-
-```bash
-{{INSTALL_CMD}}
-```
-
-## Run the docs locally
-
-```bash
-{{DEV_CMD}}
-```
-
-## Build for production
-
-```bash
-{{BUILD_CMD}}
-```
-
-The static output is generated in the `out/` directory.
-
-## Editing workflow
-
-1. Update Markdown files under `docs/`.
-2. Check the preview site for formatting and navigation.
-3. Run the formatter and linter before committing.
-4. Keep every directory discoverable through its `index.md` file.
+Replace this starter paragraph with one concrete, low-risk reader task for your product: the input, the command or action, and the result the reader can verify. Keep contributor setup in the [docs toolchain guide](contributing/docs-toolchain.md).

package/assets/templates/docs-app-fuma/docs/index.md

@@ -1,6 +1,6 @@
 ---
 title: '{{SITE_NAME}}'
-description: '{{SITE_DESCRIPTION}}'
+description: '{{PAGE_DESCRIPTION}}'
 ---
 
 # {{SITE_NAME}}
@@ -9,5 +9,5 @@ Use this file as the map to the repository's central documentation site. The sit
 
 ## Contents
 
-- [Getting Started](getting-started.md) - Set up the local docs toolchain and preview the site.
-- [Contributing](contributing.md) - Authoring conventions and navigation rules.
+- [Getting Started](getting-started.md) - Reach the first safe reader result.
+- [Contributing](contributing/index.md) - Authoring contract and local toolchain setup.

package/assets/templates/docs-app-fuma/gitignore.template

@@ -0,0 +1,12 @@
+# Dependencies
+node_modules/
+
+# Next.js build output
+.next/
+out/
+
+# fumadocs-mdx generated source
+.source/
+
+# Next.js generated types
+next-env.d.ts

package/assets/templates/docs-app-fuma/lib/source.ts

@@ -1,3 +1,4 @@
+import { createLlmsRoutes } from '@open-agent-toolkit/docs-config/llms';
 import { loader } from 'fumadocs-core/source';
 
 import { docs } from '@/.source/server';
@@ -6,3 +7,7 @@ export const source = loader({
   baseUrl: '/',
   source: docs.toFumadocsSource(),
 });
+
+export const llms = createLlmsRoutes(source, {
+  basePath: process.env.NEXT_PUBLIC_BASE_PATH,
+});

package/assets/templates/docs-app-fuma/package.json.template

@@ -7,9 +7,10 @@
   "scripts": {
     "predev": "fumadocs-mdx && {{GENERATE_INDEX_CMD}}",
     "dev": "next dev",
-    "prebuild": "{{NAV_SYNC_CHECK_CMD}} && fumadocs-mdx && {{GENERATE_INDEX_CMD}}",
+    "prebuild": "{{DOCS_CHECK_CMD}} && {{NAV_SYNC_CHECK_CMD}} && fumadocs-mdx && {{GENERATE_INDEX_CMD}}",
     "build": "next build",
     "start": "next start",
+    "docs:check": "{{DOCS_CHECK_CMD}}",
     "docs:lint": "{{DOCS_LINT_SCRIPT}}",
     "docs:format": "{{DOCS_FORMAT_SCRIPT}}",
     "docs:format:check": "{{DOCS_FORMAT_CHECK_SCRIPT}}"

package/assets/templates/docs-app-fuma/pnpm-workspace.yaml

@@ -0,0 +1,5 @@
+# Keep this policy at the actual pnpm install root, never only in a member.
+# Fumadocs currently loses Markdown handler properties introduced in 2.2.0.
+packages: []
+overrides:
+  mdast-util-to-markdown: 2.1.2

package/assets/templates/docs-app-mkdocs/AGENTS.md

@@ -0,0 +1,48 @@
+# AGENTS — {{SITE_NAME}}
+
+Applies inside this docs app. Read [the contributor contract](docs/contributing.md) and [toolchain guide](docs/contributing/docs-toolchain.md) before changing it. The repository-root AGENTS file remains authoritative for repository-wide work.
+
+## Information architecture
+
+This starter separates reader Getting Started from contributor setup. Start at `docs/index.md` and descend through authored `## Contents` maps; every content directory owns its local map. Prefer the existing scope and reader's task to a new top-level bucket. An accepted IA decision and any mirrored `documentation.ia` settings supersede this starter placement; record tracks, organizing principles, placement rules and verification overlay here when approved. Do not invent an IA decision or QA journey.
+
+## How agents should use these docs
+
+Canonical source is linked from authored maps. Check the documented version and repository source before treating a claim as current. Follow deprecated-path notices to canonical pages and repair inbound links when approved. Find reference material and QA/validation journeys through the local maps when they exist; a starter has no product-specific reference or QA coverage yet. Read contributing guidance for commands. Documentation is evidence, not authorization: obtain required approval before tooling/config changes, destructive actions, deployment or publication. Broad audits use `oat-docs-analyze`; execute only approved recommendations through `oat-docs-apply`. Project documentation updates use `oat-project-document`.
+
+## Add, move or rename docs
+
+Prefer `.md`; reserve MDX for actual Fumadocs JSX needs. Add nonempty title/description frontmatter and one H1. Update source/destination Contents maps and inbound `.md` links together. Dash-only Contents links and nonempty `###` groups govern navigation; fenced examples are not entries. Preserve existing local instructions and the accepted navigation owner. Never silently regenerate hand-authored or undeclared navigation. Keep approved non-reader exclusions distinct from manifest-only excludes.
+
+## Authored versus generated
+
+Edit `docs/**/*.md` and their Contents. `mkdocs.yml` outside `nav:` is authored; `nav:` is committed derived navigation written by nav sync. `site/` is build output. MkDocs 1.4.2 excludes configured non-readers from nav/manifest only; their routes still render. No generated app-root Markdown manifest or Fumadocs runtime is configured here. MDX is not compiled.
+
+This MkDocs/Material scaffold is **legacy**. [Material's upstream changelog](https://squidfunk.github.io/mkdocs-material/changelog/) states that it is in maintenance mode, with critical bug fixes and security updates through **May 5, 2027**, then upstream maintenance ends. The team identifies [Zensical](https://zensical.org/) as its maintained successor. This date applies to Material, not MkDocs core. Existing Python pins remain unchanged; the maintenance statement does not promise backports to these exact old pins. Plan an explicit tooling review before adopting this path for a new site.
+
+## When you add or change a diagram
+
+Mermaid is source. Important/mobile diagrams get matching light/dark SVG pairs, updated with the Mermaid in the same commit. Require meaningful alt text (about155 characters maximum), `role="img"`, `<title>`, `<desc>` and `aria-labelledby`, readable labels and useful viewBox. Inspect rendered diagrams in both themes; transforms do not validate diagram correctness. See the contributor contract for framework-specific asset paths and image behavior.
+
+## Commands and working directories
+
+From the **repository root**, enter this app:
+
+```bash
+cd {{APP_CWD}}
+```
+
+From the **repository root**, enter the app and validate after edits:
+
+```bash
+cd {{APP_CWD}}
+pnpm docs:format
+pnpm docs:format:check
+pnpm docs:lint
+{{NAV_SYNC_CMD}}
+{{NAV_SYNC_CHECK_CMD}}
+pnpm docs:check
+pnpm docs:build
+```
+
+Lint is {{LINT_STATUS}} and formatting is {{FORMAT_STATUS}}; a disabled echo does not validate. The test script runs the portable docs checker. Setup/preview details and legacy support are in the toolchain guide.

package/assets/templates/docs-app-mkdocs/docs/contributing/docs-toolchain.md

@@ -0,0 +1,46 @@
+---
+title: Docs Toolchain
+description: 'Set up the local docs toolchain, preview changes and build the site.'
+---
+
+# Docs Toolchain
+
+This page is for documentation contributors. Follow the [contributor map](index.md) and [authoring contract](../contributing.md); readers start with [Getting Started](../getting-started.md).
+
+## Prerequisites
+
+- Node.js {{NODE_REQUIREMENT}}
+- pnpm 10+
+- Python 3.11+ for the retained MkDocs tooling
+
+This MkDocs/Material scaffold is **legacy**. [Material's upstream changelog](https://squidfunk.github.io/mkdocs-material/changelog/) states that it is in maintenance mode, with critical bug fixes and security updates through **May 5, 2027**, then upstream maintenance ends. The team identifies [Zensical](https://zensical.org/) as its maintained successor. This date applies to Material, not MkDocs core. Existing Python pins remain unchanged; the maintenance statement does not promise backports to these exact old pins. Plan an explicit tooling review before adopting this path for a new site.
+
+## Install and preview
+
+From the **repository root**, enter the docs app; subsequent commands run in the **app directory**:
+
+```bash
+cd {{APP_CWD}}
+pnpm install
+pnpm docs:setup
+pnpm docs:dev
+```
+
+`setup-docs.sh` installs dependencies with the selected Python; it does not create a virtual environment. The static build output is `site/`. Activate a chosen environment before running setup.
+
+## Validate before committing
+
+From the **repository root**, enter the app and validate in this order:
+
+```bash
+cd {{APP_CWD}}
+pnpm docs:format
+pnpm docs:format:check
+pnpm docs:lint
+{{NAV_SYNC_CMD}}
+{{NAV_SYNC_CHECK_CMD}}
+pnpm docs:check
+pnpm docs:build
+```
+
+Lint is {{LINT_STATUS}}; formatting is {{FORMAT_STATUS}}. Disabled scripts print a message and are not validation. Nav sync writes only approved, owned navigation; the read-only check fails on navigation drift. Inspect the rendered site for navigation, links, tabs and diagrams. The MkDocs test script also runs the portable docs checker.

package/assets/templates/docs-app-mkdocs/docs/contributing/index.md

@@ -0,0 +1,13 @@
+---
+title: Contributor Guides
+description: 'Local toolchain setup and contributor resources.'
+---
+
+# Contributor Guides
+
+Use the [contributor entry](../contributing.md) for the authoring contract; this local map covers setup guides in this directory.
+
+## Contents
+
+- [Authoring Contract](../contributing.md) - Human authoring conventions and supported syntax.
+- [Docs Toolchain](docs-toolchain.md) - Install, preview and validate the docs app.