@open-agent-toolkit/cli 0.3.26 → 0.3.27

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

@@ -1,76 +1,112 @@
 ---
 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.
 
-## Local workflow
+```markdown
+## Contents
 
-1. Install dependencies:
+- [Start here](getting-started.md) - The first safe result.
 
-   ```bash
-   {{INSTALL_CMD}}
-   ```
+### Contributor guides
 
-2. Run the live preview:
+- [Toolchain](contributing/index.md) - Local setup and authoring.
+```
 
-   ```bash
-   {{DEV_CMD}}
-   ```
+`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.
 
-3. Run Markdown {{LINT_PHRASE}} as configured for this docs app.
+## Add, move or rename a page
+
+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
+        pnpm docs:lint
+        ```
+    ````
+
+=== "Rendered"
+
+    === "Example"
+
+        > [!NOTE]
+        > Read the local map before editing.
 
-### Code blocks
+        | Check | Result |
+        | --- | --- |
+        | Reader links | Resolve |
 
-Syntax-highlighted fenced code blocks with a copy button included by default.
+        ```bash
+        pnpm docs:lint
+        ```
 
-### Full-text search
+Not configured: arbitrary custom components, executable notebooks, API playgrounds, diagram syntax validation 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.
 
-Built-in FlexSearch-powered static search for discovering content without browsing the full tree.
+## Diagrams and accessibility
 
-### 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
+      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

@@ -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/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-mkdocs/AGENTS.md

@@ -0,0 +1,46 @@
+# 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 **app directory**, after edits:
+
+```bash
+pnpm docs:format
+pnpm docs:format:check
+pnpm docs:lint
+{{NAV_SYNC_CMD}}
+{{NAV_SYNC_CHECK_CMD}}
+pnpm docs:build
+```
+
+Lint is {{LINT_STATUS}} and formatting is {{FORMAT_STATUS}}; a disabled echo does not validate. The existing test echo is not a check. 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,44 @@
+---
+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 **app directory**, in this order:
+
+```bash
+pnpm docs:format
+pnpm docs:format:check
+pnpm docs:lint
+{{NAV_SYNC_CMD}}
+{{NAV_SYNC_CHECK_CMD}}
+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 existing MkDocs `test` echo is not a validation check.

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.

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

@@ -1,29 +1,119 @@
+---
+title: Contributing
+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. |
+| `mkdocs.yml` outside `nav:`                          | Authored framework configuration.                                         |
+| `mkdocs.yml` `nav:`                                  | Committed derived sidebar; regenerate with nav sync.                      |
+| `site/`                                              | Generated site output; do not edit.                                       |
+| `requirements.txt`, `setup-docs.sh`, package scripts | Authored toolchain; changing pins needs an explicit tooling review.       |
+
+MkDocs 1.4.2 has no configurable rendering exclusion: non-reader pages leave nav/manifest but still render as routes. Do not promise private draft routes or add an exclusion plugin as an implicit repair.
+
+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.
 
 ## 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`.
+Fresh scaffolds set `use_directory_urls: false` in `mkdocs.yml`. Pages use `.html` URLs: `contributing.md` renders as `contributing.html`, and the local map `contributing/index.md` renders as `contributing/index.html`. Keep both source files and `.md`-suffixed authored links; MkDocs resolves them to the distinct rendered destinations. Changing this setting requires reviewing published URLs and inbound links.
+
+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. Optional Markdown inventories keep deterministic fallback when Contents is missing; MkDocs nav sync needs authored maps to construct navigation. The pinned MkDocs build can still render pages absent from its navigation.
+
+```markdown
+## Contents
+
+- [Start here](getting-started.md) - The first safe result.
+
+### Contributor guides
+
+- [Toolchain](contributing/index.md) - Local setup and authoring.
+```
+
+`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.
+
+## Add, move or rename a page
+
+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
 
-## Local workflow
+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.
 
-1. Install Python dependencies:
+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.
 
-   ```bash
-   pnpm docs:setup
-   ```
+=== "Syntax"
 
-2. Run the live preview:
+    ````text
+    === "Example"
 
-   ```bash
-   pnpm docs:dev
-   ```
+        > [!NOTE]
+        > Read the local map before editing.
 
-3. Run Markdown formatting and linting as configured for this docs app.
+        | Check | Result |
+        | --- | --- |
+        | Reader links | Resolve |
+
+        ```bash
+        pnpm docs:lint
+        ```
+    ````
+
+=== "Rendered"
+
+    === "Example"
+
+        > [!NOTE]
+        > Read the local map before editing.
+
+        | Check | Result |
+        | --- | --- |
+        | Reader links | Resolve |
+
+        ```bash
+        pnpm docs:lint
+        ```
+
+Not configured: arbitrary custom components, executable notebooks, API playgrounds, diagram syntax validation 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.
+
+## Diagrams and accessibility
+
+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.
+
+=== "Syntax"
+
+    ````text
+    === "Mermaid source"
+
+        ```mermaid
+        flowchart LR
+          A[Read local map] --> B[Make a focused edit]
+        ```
+    ````
+
+=== "Rendered"
+
+    ```mermaid
+    flowchart LR
+      A[Read local map] --> B[Make a focused edit]
+    ```
+
+Put diagram assets under `docs/assets/diagrams/` and link relative to the source page. Keep both SVG variants with the source; automatic light/dark image selection is not configured in this MkDocs scaffold. Inspect theme contrast manually; do not claim the Fumadocs image/basePath behavior here.
 
 ## Installed plugins
 
@@ -112,9 +202,3 @@ Supports tabbed content blocks for related workflows or platform variants.
 ### `toc`
 
 Adds table-of-contents anchors and permalinks for headings.
-
-## Agent guidance
-
-- Treat `index.md` plus its `## Contents` section as the local discovery source of truth.
-- Prefer linking to source files and commands explicitly when documenting behavior.
-- When adding a new plugin or extension, update this guide with what it does and how to use it.

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

@@ -1,28 +1,10 @@
-# Getting Started
-
-Use this guide to set up your local environment and preview {{SITE_NAME}}.
-
-## Prerequisites
-
-- Node.js 22+
-- pnpm 10+
-- Python 3.11+ for MkDocs tooling
+---
+title: Getting Started
+description: 'Reach the first safe reader result with {{SITE_NAME}}.'
+---
 
-## Install documentation tooling
-
-```bash
-pnpm docs:setup
-```
-
-## Run the docs locally
-
-```bash
-pnpm docs:dev
-```
+# Getting Started
 
-## Editing workflow
+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.
 
-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-mkdocs/docs/index.md

@@ -1,8 +1,13 @@
+---
+title: '{{SITE_NAME}}'
+description: '{{SITE_DESCRIPTION}}'
+---
+
 # {{SITE_NAME}}
 
 Use this site as the central documentation hub for the repository. It is organized to support both human readers and AI agents, with every directory exposing an `index.md` entrypoint.
 
 ## Contents
 
-- [Getting Started](getting-started.md) - Set up the local docs toolchain and preview the site.
-- [Contributing](contributing.md) - Authoring conventions, plugin inventory, 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-mkdocs/mkdocs.yml

@@ -1,5 +1,6 @@
 site_name: {{SITE_NAME}}
 docs_dir: './docs'
+use_directory_urls: false
 
 site_description: {{SITE_NAME}}
 

package/dist/commands/docs/init/docs-commands.d.ts

@@ -4,5 +4,6 @@ export interface DocsCommands {
     dev: string;
     build: string;
 }
+export declare function shellQuote(value: string): string;
 export declare function buildDocsCommands(repoShape: DocsRepoShape, targetDir: string, appName: string): DocsCommands;
 //# sourceMappingURL=docs-commands.d.ts.map

package/dist/commands/docs/init/docs-commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-commands.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/docs-commands.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAMD,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,aAAa,EACxB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,YAAY,CAsBd"}
+{"version":3,"file":"docs-commands.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/docs-commands.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIhD;AAMD,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,aAAa,EACxB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,YAAY,CAsBd"}

package/dist/commands/docs/init/docs-commands.js

@@ -1,4 +1,9 @@
 import { normalize } from 'node:path';
+export function shellQuote(value) {
+    return /^[a-zA-Z0-9_./-]+$/.test(value)
+        ? value
+        : `'${value.replaceAll("'", "'\\''")}'`;
+}
 function isRootTarget(targetDir) {
     return targetDir.trim() === '' || normalize(targetDir) === '.';
 }
@@ -18,8 +23,8 @@ export function buildDocsCommands(repoShape, targetDir, appName) {
         };
     }
     return {
-        install: `cd ${targetDir} && pnpm install`,
-        dev: `cd ${targetDir} && pnpm dev`,
-        build: `cd ${targetDir} && pnpm build`,
+        install: `cd ${shellQuote(targetDir)} && pnpm install`,
+        dev: `cd ${shellQuote(targetDir)} && pnpm dev`,
+        build: `cd ${shellQuote(targetDir)} && pnpm build`,
     };
 }

package/dist/commands/docs/init/scaffold.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/scaffold.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAMjE,OAAO,KAAK,EAEV,aAAa,EACb,uBAAuB,EAExB,MAAM,mBAAmB,CAAC;AAsF3B,MAAM,WAAW,sBAAuB,SAAQ,uBAAuB;IACrE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mBAAmB,EAAE,sBAAsB,CAAC;CAC7C;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5C;AAED,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAEtC,MAAM,WAAW,2BAA2B;IAC1C,iBAAiB,EAAE,MAAM,YAAY,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACjE,0BAA0B,EAAE,CAC1B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,KACZ,YAAY,CAAC,OAAO,CAAC,CAAC;CAC5B;AAUD,eAAO,MAAM,aAAa,YAAY,CAAC;AAEvC,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOxE;AAgDD,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAaxB;AAmND;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,aAAa,EACxB,SAAS,EAAE,MAAM,GAChB,sBAAsB,CAwBxB;AA6CD,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,EAC/B,SAAS,GAAE,OAAO,CAAC,2BAA2B,CAAM,GACnD,OAAO,CAAC,qBAAqB,CAAC,CAwDhC"}
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/scaffold.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAMjE,OAAO,KAAK,EAEV,aAAa,EACb,uBAAuB,EAExB,MAAM,mBAAmB,CAAC;AAoG3B,MAAM,WAAW,sBAAuB,SAAQ,uBAAuB;IACrE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mBAAmB,EAAE,sBAAsB,CAAC;CAC7C;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5C;AAED,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAEtC,MAAM,WAAW,2BAA2B;IAC1C,iBAAiB,EAAE,MAAM,YAAY,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACjE,0BAA0B,EAAE,CAC1B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,KACZ,YAAY,CAAC,OAAO,CAAC,CAAC;CAC5B;AAUD,eAAO,MAAM,aAAa,YAAY,CAAC;AAEvC,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOxE;AAgDD,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAaxB;AA0ND;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,aAAa,EACxB,SAAS,EAAE,MAAM,GAChB,sBAAsB,CAwBxB;AA6CD,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,EAC/B,SAAS,GAAE,OAAO,CAAC,2BAA2B,CAAM,GACnD,OAAO,CAAC,qBAAqB,CAAC,CAyDhC"}