agent-docs-kit 2.1.0__py3-none-any.whl

living_docs_cli/assets/workflow-skills/living-docs-architecture/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: living-docs-architecture
+description: Create or update architecture MDX pages in a living-docs Fumadocs project. Use whenever current architecture, system shape, subsystem boundaries, data flow, runtime chain, contracts, ownership, or architecture diagrams need documentation or correction.
+---
+
+# living-docs-architecture
+
+Use this skill only inside a project that has `.living-docs/config.json`. If that file is missing, tell the user to run `living-docs init` first.
+
+Architecture pages describe current runtime truth. They should not become historical changelogs or future plans.
+
+## Source Priority
+
+1. `.living-docs/config.json` for docs location and project settings.
+2. Existing MDX pages under the configured `contentDir`.
+3. Source files, routes, schemas, config, tests, logs, traces, or rendered runtime surfaces that prove the current shape.
+4. User-provided context, marked as unverified when it has not been checked against the repo or runtime.
+
+## Workflow
+
+1. Read `.living-docs/config.json` and inspect the configured `contentDir`.
+2. Identify the target domain. Use `system` for cross-domain architecture.
+3. If the domain architecture page does not exist, create it:
+
+```bash
+node .living-docs/scripts/create-doc.mjs architecture <domain> <domain> "<Title>"
+```
+
+4. Edit the MDX page to reflect current runtime truth:
+   - entry points
+   - core modules/components
+   - data stores or external services
+   - contracts and ownership boundaries
+   - known constraints
+5. Include at least one diagram component:
+   - Use `<ArchMap />` for subsystem layers and ownership boundaries.
+   - Use `<FlowSteps />` for runtime request/job/event paths.
+   - Use `<StateFlow />` for lifecycle or state transitions.
+   - Use mermaid only for complex graphs, branches, sequence diagrams, or diagrams that do not fit the built-in components.
+6. Keep history out of architecture pages; history belongs in change records.
+7. Add or update frontmatter `terms`.
+8. Run:
+
+```bash
+node .living-docs/scripts/glossary.mjs
+node .living-docs/scripts/check.mjs
+```
+
+## Write Safety
+
+- Do not document aspirational behavior as current architecture.
+- If the current shape differs from an existing page, update the architecture page and consider whether a separate change record is needed.
+- If a diagram would be speculative, write the uncertainty explicitly or inspect more code before adding it.
+
+Report the architecture page path, key source files or runtime evidence used, and validation result.

living_docs_cli/assets/workflow-skills/living-docs-change/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: living-docs-change
+description: Record shipped changes in a living-docs Fumadocs project. Use after refactors, features, bug fixes, API or data-contract changes, architecture changes, migrations, deploy changes, or operational fixes that need an immutable paper trail.
+---
+
+# living-docs-change
+
+Use this skill only inside a project that has `.living-docs/config.json`. If that file is missing, tell the user to run `living-docs init` first.
+
+Change records are immutable shipped-history pages. They should explain what changed, why it changed, and how it was verified. They are not the place for unshipped plans.
+
+## Source Priority
+
+1. `.living-docs/config.json` for docs location and project settings.
+2. Git diff, commits, changed source files, migrations, config, tests, logs, or runtime checks that prove the shipped change.
+3. Existing architecture pages that may need to be updated to match the new current state.
+4. User-provided context, marked as unverified when it has not been checked against the repo or runtime.
+
+## Workflow
+
+1. Read `.living-docs/config.json`.
+2. Inspect the relevant source diff, tests, logs, or runtime surface before writing.
+3. Choose a domain and short topic slug.
+4. Create a change record:
+
+```bash
+node .living-docs/scripts/create-doc.mjs change <domain> <topic-slug> "<Title>"
+```
+
+Optional metadata:
+
+```bash
+LIVING_DOCS_SOURCE="commit/diff/runtime source" LIVING_DOCS_TESTS="test or verification summary" node .living-docs/scripts/create-doc.mjs change <domain> <topic-slug> "<Title>"
+```
+
+5. Fill the MDX page:
+   - what changed
+   - why it changed
+   - important trade-offs
+   - verification performed
+   - user-visible or system-visible behavior
+6. Include at least one diagram component:
+   - Use `<FlowSteps />` for before/change/after behavior.
+   - Use `<StateFlow />` when the change affects lifecycle states.
+   - Use `<ArchMap />` when the current architecture shape changed.
+   - Use mermaid only for complex graphs, branches, or sequence diagrams.
+7. Update the relevant architecture page if the current shape changed.
+8. Add/update frontmatter `terms`.
+9. Run:
+
+```bash
+node .living-docs/scripts/glossary.mjs
+node .living-docs/scripts/check.mjs
+```
+
+## Write Safety
+
+- Do not record a change as shipped if it is only proposed or partially implemented.
+- Do not rewrite old change records to change history; create a new record for a new shipped correction.
+- If the current architecture changed, update the relevant architecture page in the same pass.
+
+Report the change page, any architecture page touched, the evidence used, and validation result.

living_docs_cli/assets/workflow-skills/living-docs-check/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: living-docs-check
+description: Validate a living-docs Fumadocs project. Use before committing docs changes, after generated docs or glossary files change, or whenever the user asks whether the documentation system, MDX content, glossary, or living-docs setup is healthy.
+---
+
+# living-docs-check
+
+Use this skill only inside a project that has `.living-docs/config.json`. If that file is missing, report that this is not initialized as a living-docs project.
+
+## Validation Order
+
+Run the local validation gate first because it is always project-local:
+
+```bash
+node .living-docs/scripts/check.mjs
+```
+
+If the global CLI is installed, also run:
+
+```bash
+living-docs check
+```
+
+For docs-app changes, run the Fumadocs/TypeScript checks when dependencies are installed:
+
+```bash
+cd docs
+npm run typecheck
+npm run build
+```
+
+Fix failures only if the user asked for fixes or the failure is caused by documentation changes you just made. Report the exact failing files, skipped checks with reasons, and final result.

living_docs_cli/assets/workflow-skills/living-docs-glossary/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: living-docs-glossary
+description: Regenerate and review the glossary in a living-docs Fumadocs project. Use whenever MDX frontmatter terms were added, changed, duplicated, renamed, or need consistency cleanup before docs are committed.
+---
+
+# living-docs-glossary
+
+Use this skill only inside a project that has `.living-docs/config.json`. If that file is missing, tell the user to run `living-docs init` first.
+
+## Workflow
+
+1. Read `.living-docs/config.json`.
+2. Inspect frontmatter `terms` in the relevant MDX files.
+3. Normalize duplicate terms only when they clearly mean the same project concept.
+4. Run:
+
+```bash
+node .living-docs/scripts/glossary.mjs
+node .living-docs/scripts/check.mjs
+```
+
+5. If the generated glossary looks wrong, fix source page frontmatter rather than hand-editing `glossary.mdx`.
+
+## Write Safety
+
+- Do not hand-edit the generated glossary except to replace it by rerunning the script.
+- Do not merge two terms when they may represent different project concepts.
+- Preserve the language and naming style already used in nearby docs unless the user asks for a rename.
+
+Report the generated glossary path, any source frontmatter changed, and validation result.

living_docs_cli/assets/workflow-skills/living-docs-plan/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: living-docs-plan
+description: Create or update future plans, blueprints, design direction, implementation plans, or proposal MDX pages in a living-docs Fumadocs project. Use when documenting intended work before it ships or when the user wants a plan separated from current architecture and shipped change records.
+---
+
+# living-docs-plan
+
+Use this skill only inside a project that has `.living-docs/config.json`. If that file is missing, tell the user to run `living-docs init` first.
+
+Plan pages describe future intent. They should be explicit about scope, assumptions, validation, and open questions.
+
+## Source Priority
+
+1. `.living-docs/config.json` for docs location and project settings.
+2. Existing architecture and change pages under the configured `contentDir`.
+3. Source files, APIs, schemas, config, tests, or runtime surfaces that constrain the proposed work.
+4. User-provided goals and constraints.
+
+## Workflow
+
+1. Read `.living-docs/config.json`.
+2. Choose the target domain and topic slug.
+3. Create a plan page:
+
+```bash
+node .living-docs/scripts/create-doc.mjs plan <domain> <topic-slug> "<Title>"
+```
+
+4. Fill the plan with:
+   - goal
+   - scope and non-goals
+   - proposed architecture or flow
+   - validation plan
+   - open questions
+5. Use built-in components when a diagram clarifies the plan:
+   - `<ArchMap />` for target architecture.
+   - `<FlowSteps />` for proposed execution flow.
+   - `<StateFlow />` for lifecycle or state transitions.
+   - mermaid for complex graphs, branches, or sequence diagrams.
+6. Keep shipped facts out of plan pages; when the plan ships, create a change record and update architecture.
+7. Add/update frontmatter `terms`.
+8. Run:
+
+```bash
+node .living-docs/scripts/glossary.mjs
+node .living-docs/scripts/check.mjs
+```
+
+## Write Safety
+
+- Do not present a plan as current architecture or shipped behavior.
+- Keep speculative details clearly labeled as assumptions or open questions.
+- If a plan depends on unknown runtime behavior, add a validation task instead of guessing.
+
+Report the plan page path, major assumptions, open questions, and validation result.

living_docs_cli/assets/workflow-skills/living-docs-write/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: living-docs-write
+description: General entrypoint for creating or updating living-docs MDX documentation in a project initialized with living-docs. Use whenever the user asks to write docs, update docs, explain current architecture, record a shipped change, draft a future plan, refresh glossary terms, validate docs health, or maintain the generated Fumadocs documentation system.
+---
+
+# living-docs-write
+
+Use this skill only inside a project that has `.living-docs/config.json`. If that file is missing, tell the user to run `living-docs init` before writing living-docs content.
+
+This is the portable entrypoint for agents that do not have native slash or skill invocation. For Codex, Claude Code, and similar skill-aware agents, route to the named living-docs skill directly when it is available. For Cursor, Gemini CLI, Copilot, or generic agents, read the matching `SKILL.md` file from the installed workflow directory before editing docs.
+
+## Routine
+
+1. Read `.living-docs/config.json`.
+2. Inspect existing docs under the configured `contentDir`.
+3. Choose the specific workflow:
+   - Architecture/current system shape: use `living-docs-architecture`.
+   - Shipped behavior or implementation change: use `living-docs-change`.
+   - Future direction or blueprint: use `living-docs-plan`.
+   - Terms changed: use `living-docs-glossary`.
+   - Validation only: use `living-docs-check`.
+4. Keep MDX as the source of truth. Do not edit generated HTML output.
+5. Prefer built-in MDX components for common diagrams:
+   - `<ArchMap />` for architecture layers.
+   - `<FlowSteps />` for runtime or behavior flows.
+   - `<StateFlow />` for state transitions.
+   - `<TermGrid />` for page-local vocabulary.
+6. Match the language and tone of the existing docs unless the user asks otherwise.
+
+## Write Safety
+
+- Do not invent architecture or verification details. Inspect source files, diffs, tests, logs, or the runtime surface first.
+- Do not overwrite an existing MDX page unless the user asked to update that page or the selected workflow clearly targets it.
+- Keep historical facts in change records, current facts in architecture pages, and future intent in plan pages.
+- If the request mixes shipped facts and future intent, create or update separate change and plan pages instead of blending them.
+
+## Finish Gate
+
+Run one of:
+
+```bash
+node .living-docs/scripts/check.mjs
+living-docs check
+```
+
+Report the changed MDX files and the validation result.