yaaf-docs-maintenance

name	yaaf-docs-maintenance
description	Use when updating yaaf user documentation, README files, Lua API docs, tool reference docs, MCP docs, examples, build/run instructions, CLI option docs, or runtime behavior docs. Keeps README.md, docs/, docs/modules/, docs/tools/, libyaaf/mcp/README.md, and MCP_PLAN.md aligned with implementation and tests.
argument-hint	What behavior or documentation changed?

Yaaf Docs Maintenance

Use this skill when changing or reviewing user-facing documentation for yaaf, especially after edits to CLI behavior, Lua runtime modules, MCP support, shipped commands, build outputs, examples, environment variables, or fixture servers.

Documentation Map

Keep each document focused on its job:

• Root README: concise project overview, build command, documentation links, and quick smoke tests.
• Docs index: table of contents for user-facing docs and MkDocs home page.
• Usage: build output, executable assumptions, environment variables, core CLI commands, embeddings, and proxy setup.
• Lua Runtime: direct script runs, command discovery, and short module overview.
• Lua API Reference: per-module runtime API reference, with one page per public Lua module.
• Tool Reference: built-in tool list, input schemas, MCP tool naming pointer, and custom tool authoring guide.
• MCP Tools: user-facing MCP config, transports, variable substitution, tool names, runtime behavior, schema support, and fixtures.
• Examples: example overview, with one page per runnable example or scenario.
• MCP support README: implementation-level MCP support matrix.
• MCP plan: architecture, rollout notes, and historical implementation plan.
• Fixture README: hello-world MCP fixture setup and test-only fixture knobs.

Source Of Truth

Before editing docs, inspect the implementation or tests for the behavior being documented.

CLI and runtime sources:

• CLI entry point
• Lua runtime
• Native Lua modules
• Shipped Lua commands
• Shipped agents
• Shipped tools

MCP sources:

• Native MCP client
• Native MCP API
• MCP support README
• MCP tests
• Mocked MCP protocol tests
• Integration MCP client tests

Build and validation sources:

• Root CMake
• App CMake
• Test CMake
• Repository workflow

Procedure

1. Identify the behavior that changed: CLI command, option, environment variable, build output, Lua module API, shipped command/tool/agent, MCP behavior, fixture behavior, or validation command.
2. Read the matching source files and tests before writing docs. Do not document aspirational behavior as current behavior.
3. Update the narrowest user-facing docs first, then update index links and the root README only when discoverability changes.
4. Keep implementation-level details in implementation docs. For MCP internals, prefer MCP support README; for user workflows, prefer MCP Tools and Examples.
5. If a change affects Lua modules, update the matching page under Lua API Reference, add a new module page when a public module appears, and keep Lua Runtime as the shorter overview.
6. If a change affects built-in tools, tool result shape, tool registration, or custom tool authoring, update Tool Reference and link to the relevant Lua API page instead of duplicating registry details everywhere.
7. If a command example changes, search the docs for stale copies of the old invocation and update related example pages together.
8. If a feature is intentionally unsupported, say so plainly and avoid documenting partial or flaky behavior as supported.
9. Validate docs changes with git diff --check. For documentation generated from, or tightly coupled to, C++ behavior, also build the affected target or run the focused tests that prove the documented behavior.

Documentation Rules

• Prefer short, copyable examples over long prose.
• Keep root README slim; move detailed usage into docs/.
• Use yaaf.exe in user examples when the build output directory is assumed to be on PATH.
• Mention the exact assumption for examples: repository root, executable directory, or build output directory on PATH.
• Keep environment variable precedence accurate: process environment first, then nearest parent .env where implemented.
• Keep MCP config path selection explicit only: --mcp <path> or YAAF_MCP_FILE; yaaf must not auto-discover editor-owned MCP config files outside .yaaf/mcp.json.
• Do not document ${input:...} as supported; yaaf rejects it. Use ${env:NAME} or envFile examples instead.
• Keep fixture-only environment variables out of normal user configuration docs. Document them only as test or fixture overrides.
• Document modules by public API name rather than implementation layer; users should not need to know whether a module is native C++ or shipped Lua.
• For built-in runtime modules, mention that they are built in during the first sentence of the module page, then focus on behavior and API.
• Keep Lua module docs aligned with functions actually returned by the module tables.
• Keep each public module on its own page under docs/modules/; avoid recreating a long single-page module reference.
• Keep Tool Reference focused on developer workflow: built-in tool names, schemas, custom tool shape, registration, and links to complete examples.
• When adding, renaming, or removing a built-in tool, update Tool Reference, the matching module page if one exists, and mkdocs.yml when a new public page is added.
• When adding, renaming, or removing a module page, update mkdocs.yml, Lua API Reference, Docs index when discoverability changes, and Root README only for top-level documentation entry changes.
• Keep each runnable example or scenario on its own page under docs/examples/; keep Examples as a short index.
• When adding, renaming, or removing an example page, update mkdocs.yml, Examples, Docs index when discoverability changes, and Root README only for top-level documentation entry changes.
• Avoid duplicating full command references in multiple places. Put full module/API details in Lua API Reference, tool authoring guidance in Tool Reference, and copyable task examples in Examples.

Validation Checklist

For docs-only changes:

git diff --check
.\.venv\Scripts\python.exe -m mkdocs build --strict

If the repository virtual environment is unavailable, use python -m mkdocs build --strict after installing requirements-docs.txt.

For build/run documentation changes:

cmake --build build --config Debug --target yaaf

For CLI, Lua, or MCP behavior documentation that changed alongside code:

cmake --build build --config Debug --target libyaaf_tests
.\build\tests\Debug\libyaaf_tests.exe

For MCP-specific behavior changes, also follow the MCP protocol support skill (yaaf-mcp-protocol-support).