agent-docs-kit 2.1.0__tar.gz → 2.2.1__tar.gz

{agent_docs_kit-2.1.0 → agent_docs_kit-2.2.1}/.claude-plugin/marketplace.json

@@ -1,16 +1,16 @@
 {
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "agent-docs-kit",
-  "version": "2.1.0",
-  "description": "Standalone marketplace for the living-docs Fumadocs/MDX documentation system workflow.",
+  "version": "2.2.1",
+  "description": "Standalone marketplace for the living-docs Fumadocs/MDX Project Atlas workflow.",
   "owner": {
     "name": "wuyuxiangX"
   },
   "plugins": [
     {
       "name": "agent-docs-kit",
-      "description": "Initialize and maintain a generic documentation system: Fumadocs + MDX, project-local templates/scripts, agent skills, managed context blocks, glossary generation, and validation.",
-      "version": "2.1.0",
+      "description": "Initialize and maintain a Project Atlas: Fumadocs + MDX, project-local templates/scripts, agent skills, managed context blocks, glossary generation, and validation.",
+      "version": "2.2.1",
       "author": {
         "name": "wuyuxiangX"
       },

{agent_docs_kit-2.1.0 → agent_docs_kit-2.2.1}/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-docs-kit",
-  "version": "2.1.0",
-  "description": "Bootstrap and maintain a generic Fumadocs + MDX documentation system with project-local scripts, agent skills, managed context blocks, glossary generation, and validation.",
+  "version": "2.2.1",
+  "description": "Bootstrap and maintain a Fumadocs + MDX Project Atlas with project-local scripts, agent skills, managed context blocks, glossary generation, and validation.",
   "author": {
     "name": "wuyuxiangX"
   },

{agent_docs_kit-2.1.0 → agent_docs_kit-2.2.1}/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 2.2.1
+
+- Replaced the integration prompt with a terminal multi-select UI: Up/Down or `j`/`k` moves, Space toggles, `a` selects all, and Enter confirms.
+- Improved the text fallback parser for compact numeric selections such as `12`, spaced selections such as `1 2`, and normalized terminal input.
+- Updated init next steps and generated agent context to prefer `uvx agent-docs-kit ...` commands so one-time `uvx` users do not hit `living-docs: command not found`.
+
+## 2.2.0
+
+- Added Project Atlas as the primary project-level architecture map.
+- Added `living-docs atlas` / `agent-docs-kit atlas` to generate an editable Atlas MDX draft from repository structure.
+- Added Atlas-oriented MDX components: `SystemMap`, `LayerMap`, `FlowMap`, and `RoadmapMap`.
+- Added Atlas starter content, template support, and validation rules for the new map components.
+- Updated architecture workflow guidance to prefer broad project maps over feature-by-feature docs sprawl.
+- Added `living-docs web` / `agent-docs-kit web` to install docs dependencies when needed and start the local Fumadocs site on an available port.
+- Added a generated docs app `postcss` override for the audited safe version used by Next.js.
+
 ## 2.1.0
 
 - Added interactive `living-docs init` prompts for target project, docs directory, agent integrations, style, and overwrite behavior.

{agent_docs_kit-2.1.0 → agent_docs_kit-2.2.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: agent-docs-kit
-Version: 2.1.0
-Summary: Bootstrap and maintain a Fumadocs-powered MDX documentation system with agent skills, reusable templates, and validation.
+Version: 2.2.1
+Summary: Bootstrap and maintain a Fumadocs-powered Project Atlas with agent skills, reusable templates, and validation.
 Project-URL: Homepage, https://github.com/wuyuxiangX/agent-docs-kit
 Project-URL: Repository, https://github.com/wuyuxiangX/agent-docs-kit
 Project-URL: Issues, https://github.com/wuyuxiangX/agent-docs-kit/issues
@@ -14,9 +14,15 @@ Description-Content-Type: text/markdown
 
 # agent-docs-kit
 
-Generic documentation system for agent-assisted projects.
+Project Atlas documentation system for agent-assisted projects.
 
-agent-docs-kit bootstraps a Fumadocs + MDX documentation app, project-local scaffolding scripts, reusable MDX templates, and agent skills for Codex, Claude Code, Copilot, Cursor, Gemini CLI, or a generic agent directory.
+agent-docs-kit bootstraps a Fumadocs + MDX Project Atlas, project-local
+scaffolding scripts, reusable MDX templates, and agent skills for Codex, Claude
+Code, Copilot, Cursor, Gemini CLI, or a generic agent directory.
+
+The main goal is a broad architecture map: modules, layers, core flows, and
+architecture direction. It is not a project-management platform and does not
+ask you to document every feature.
 
 agent-docs-kit is skills-first. It installs `SKILL.md` workflow skills into the
 target project instead of installing slash-command prompt files.
@@ -39,6 +45,7 @@ One-time usage:
 
 ```bash
 uvx agent-docs-kit init
+uvx agent-docs-kit web --open
 ```
 
 Persistent install:
@@ -58,14 +65,13 @@ by PyPI's project-name similarity checks. It still installs both CLI commands:
 ? Target project [.]:
 ? Docs directory [docs]:
 ? Agent integrations
-  1. codex - Codex (default)
-  2. claude - Claude Code
-  3. copilot - GitHub Copilot
-  4. cursor - Cursor
-  5. gemini - Gemini CLI
-  6. generic - Generic
-  Enter names or numbers separated by commas, or 'all'.
-  Selection [codex]:
+  Up/Down or j/k moves. Space selects. a selects all. Enter confirms.
+  > [x] Codex (codex)
+    [ ] Claude Code (claude)
+    [ ] GitHub Copilot (copilot)
+    [ ] Cursor (cursor)
+    [ ] Gemini CLI (gemini)
+    [ ] Generic (generic)
 ? Style [atlas]:
 ? Overwrite existing managed files if needed? [y/N]:
 ```
@@ -77,6 +83,9 @@ agent-docs-kit init . --integration codex
 agent-docs-kit init . --integration codex --integration claude --integration copilot
 agent-docs-kit init . --integration codex --integration cursor --integration gemini
 agent-docs-kit init . --integration codex --docs-dir docs --style atlas --yes
+agent-docs-kit web
+agent-docs-kit atlas --force
+agent-docs-kit skills
 ```
 
 The starter uses the `atlas` style by default:
@@ -135,6 +144,7 @@ separate global `living-docs` helper skill.
 .living-docs/
   config.json
   templates/
+    atlas.mdx
     architecture.mdx
     change.mdx
     plan.mdx
@@ -148,6 +158,7 @@ docs/
   app/
   components/
   content/docs/
+    atlas.mdx
   lib/
   package.json
   source.config.ts
@@ -173,10 +184,20 @@ Re-running init replaces only that block and preserves surrounding project instr
 
 ## Day-to-Day Workflow
 
+Start the local docs site from the project root:
+
+```bash
+agent-docs-kit web
+```
+
+The command installs docs dependencies when `node_modules` is missing, finds an
+available local port starting at `3333`, and prints the URL. Add `--open` to
+open the browser automatically.
+
 Use generated skills from your agent:
 
 - `living-docs-write` for routing a general docs request to the right workflow
-- `living-docs-architecture` for current architecture docs
+- `living-docs-architecture` for Project Atlas and current architecture docs
 - `living-docs-change` for shipped change records
 - `living-docs-plan` for future design plans
 - `living-docs-glossary` after terms change
@@ -185,17 +206,61 @@ Use generated skills from your agent:
 The skills call project-local scripts:
 
 ```bash
+agent-docs-kit skills
+agent-docs-kit web
+agent-docs-kit atlas --force
 node .living-docs/scripts/create-doc.mjs change api auth-flow "Auth Flow Update"
 node .living-docs/scripts/glossary.mjs
 node .living-docs/scripts/check.mjs
 ```
 
+Use `agent-docs-kit atlas --stdout` after init to preview an editable Project
+Atlas draft from repository structure. It writes `docs/content/docs/atlas.mdx`
+by default. New projects already include a starter `atlas.mdx`, so pass
+`--force` only when you want to replace that starter page.
+
 ## MDX Components
 
 living-docs ships reusable MDX components in the generated Fumadocs app. Use
 them directly in `.mdx` pages:
 
 ```mdx
+<SystemMap
+  title="System map"
+  nodes={[
+    { title: 'Web app', body: 'User-facing routes.', tone: 'blue' },
+    { title: 'API', body: 'Server boundary.', tone: 'green' },
+  ]}
+  links={[{ from: 'Web app', to: 'API', label: 'calls' }]}
+/>
+
+<LayerMap
+  title="Project layers"
+  layers={[
+    {
+      title: 'Surfaces',
+      body: 'User-visible or agent-visible entry points.',
+      tone: 'blue',
+      items: ['app/', 'api/', 'cli/'],
+    },
+  ]}
+/>
+
+<FlowMap
+  title="Primary runtime path"
+  flows={[
+    { title: 'Entry', body: 'Input and routing boundary.', tone: 'blue', steps: ['Request', 'Route'] },
+    { title: 'Execution', body: 'Core modules and state changes.', tone: 'green', steps: ['Validate', 'Persist'] },
+  ]}
+/>
+
+<RoadmapMap
+  items={[
+    { title: 'Current shape', body: 'What the repo and runtime prove today.', status: 'now', tone: 'green' },
+    { title: 'Next structural move', body: 'The next architecture-level change.', status: 'next', tone: 'blue' },
+  ]}
+/>
+
 <ArchMap
   tiers={[
     {
@@ -239,12 +304,11 @@ agent-docs-kit check
 ## Run the Docs Site
 
 ```bash
-cd docs
-npm install
-npm run dev -- --port 3333
+agent-docs-kit web
 ```
 
-Fumadocs reads MDX from `docs/content/docs`.
+Fumadocs reads MDX from `docs/content/docs`. If you prefer to run the generated
+app directly, use `cd docs && npm install && npm run dev -- --port 3333`.
 
 ## Publish to PyPI
 
@@ -264,8 +328,8 @@ One-time PyPI setup for a new package:
 After that, publish a release by tagging the commit:
 
 ```bash
-git tag -a v2.1.0 -m v2.1.0
-git push origin v2.1.0
+git tag -a v2.2.1 -m v2.2.1
+git push origin v2.2.1
 ```
 
 The workflow builds the Python package with `uv build` and uploads the
@@ -274,11 +338,13 @@ distribution files to PyPI.
 ## Authoring Contract
 
 - MDX is the source of truth.
+- The Project Atlas is the first project-level architecture surface.
 - Architecture pages describe current state.
 - Change pages are immutable records of shipped changes.
 - Plan pages describe future intent.
 - Glossary pages are generated from frontmatter `terms`.
-- Architecture and change pages should include `<ArchMap />` or mermaid diagrams.
+- Architecture and change pages should include an Atlas/architecture component or mermaid diagram.
+- Do not create feature-level pages by default; prefer a broad Atlas first.
 - Validation must pass before treating docs work as complete.
 
 ## CLI
@@ -287,6 +353,8 @@ distribution files to PyPI.
 agent-docs-kit init
 agent-docs-kit init [target] [--integration codex|claude|copilot|cursor|gemini|generic] [--docs-dir docs] [--force] [--yes]
 agent-docs-kit init . --style atlas --interactive
+agent-docs-kit web [target] [--port 3333] [--host 127.0.0.1] [--open] [--no-install]
+agent-docs-kit atlas [target] [--output docs/content/docs/atlas.mdx] [--force] [--stdout]
 agent-docs-kit check
 agent-docs-kit skills
 agent-docs-kit styles

{agent_docs_kit-2.1.0 → agent_docs_kit-2.2.1}/README.md

@@ -1,8 +1,14 @@
 # agent-docs-kit
 
-Generic documentation system for agent-assisted projects.
+Project Atlas documentation system for agent-assisted projects.
 
-agent-docs-kit bootstraps a Fumadocs + MDX documentation app, project-local scaffolding scripts, reusable MDX templates, and agent skills for Codex, Claude Code, Copilot, Cursor, Gemini CLI, or a generic agent directory.
+agent-docs-kit bootstraps a Fumadocs + MDX Project Atlas, project-local
+scaffolding scripts, reusable MDX templates, and agent skills for Codex, Claude
+Code, Copilot, Cursor, Gemini CLI, or a generic agent directory.
+
+The main goal is a broad architecture map: modules, layers, core flows, and
+architecture direction. It is not a project-management platform and does not
+ask you to document every feature.
 
 agent-docs-kit is skills-first. It installs `SKILL.md` workflow skills into the
 target project instead of installing slash-command prompt files.
@@ -25,6 +31,7 @@ One-time usage:
 
 ```bash
 uvx agent-docs-kit init
+uvx agent-docs-kit web --open
 ```
 
 Persistent install:
@@ -44,14 +51,13 @@ by PyPI's project-name similarity checks. It still installs both CLI commands:
 ? Target project [.]:
 ? Docs directory [docs]:
 ? Agent integrations
-  1. codex - Codex (default)
-  2. claude - Claude Code
-  3. copilot - GitHub Copilot
-  4. cursor - Cursor
-  5. gemini - Gemini CLI
-  6. generic - Generic
-  Enter names or numbers separated by commas, or 'all'.
-  Selection [codex]:
+  Up/Down or j/k moves. Space selects. a selects all. Enter confirms.
+  > [x] Codex (codex)
+    [ ] Claude Code (claude)
+    [ ] GitHub Copilot (copilot)
+    [ ] Cursor (cursor)
+    [ ] Gemini CLI (gemini)
+    [ ] Generic (generic)
 ? Style [atlas]:
 ? Overwrite existing managed files if needed? [y/N]:
 ```
@@ -63,6 +69,9 @@ agent-docs-kit init . --integration codex
 agent-docs-kit init . --integration codex --integration claude --integration copilot
 agent-docs-kit init . --integration codex --integration cursor --integration gemini
 agent-docs-kit init . --integration codex --docs-dir docs --style atlas --yes
+agent-docs-kit web
+agent-docs-kit atlas --force
+agent-docs-kit skills
 ```
 
 The starter uses the `atlas` style by default:
@@ -121,6 +130,7 @@ separate global `living-docs` helper skill.
 .living-docs/
   config.json
   templates/
+    atlas.mdx
     architecture.mdx
     change.mdx
     plan.mdx
@@ -134,6 +144,7 @@ docs/
   app/
   components/
   content/docs/
+    atlas.mdx
   lib/
   package.json
   source.config.ts
@@ -159,10 +170,20 @@ Re-running init replaces only that block and preserves surrounding project instr
 
 ## Day-to-Day Workflow
 
+Start the local docs site from the project root:
+
+```bash
+agent-docs-kit web
+```
+
+The command installs docs dependencies when `node_modules` is missing, finds an
+available local port starting at `3333`, and prints the URL. Add `--open` to
+open the browser automatically.
+
 Use generated skills from your agent:
 
 - `living-docs-write` for routing a general docs request to the right workflow
-- `living-docs-architecture` for current architecture docs
+- `living-docs-architecture` for Project Atlas and current architecture docs
 - `living-docs-change` for shipped change records
 - `living-docs-plan` for future design plans
 - `living-docs-glossary` after terms change
@@ -171,17 +192,61 @@ Use generated skills from your agent:
 The skills call project-local scripts:
 
 ```bash
+agent-docs-kit skills
+agent-docs-kit web
+agent-docs-kit atlas --force
 node .living-docs/scripts/create-doc.mjs change api auth-flow "Auth Flow Update"
 node .living-docs/scripts/glossary.mjs
 node .living-docs/scripts/check.mjs
 ```
 
+Use `agent-docs-kit atlas --stdout` after init to preview an editable Project
+Atlas draft from repository structure. It writes `docs/content/docs/atlas.mdx`
+by default. New projects already include a starter `atlas.mdx`, so pass
+`--force` only when you want to replace that starter page.
+
 ## MDX Components
 
 living-docs ships reusable MDX components in the generated Fumadocs app. Use
 them directly in `.mdx` pages:
 
 ```mdx
+<SystemMap
+  title="System map"
+  nodes={[
+    { title: 'Web app', body: 'User-facing routes.', tone: 'blue' },
+    { title: 'API', body: 'Server boundary.', tone: 'green' },
+  ]}
+  links={[{ from: 'Web app', to: 'API', label: 'calls' }]}
+/>
+
+<LayerMap
+  title="Project layers"
+  layers={[
+    {
+      title: 'Surfaces',
+      body: 'User-visible or agent-visible entry points.',
+      tone: 'blue',
+      items: ['app/', 'api/', 'cli/'],
+    },
+  ]}
+/>
+
+<FlowMap
+  title="Primary runtime path"
+  flows={[
+    { title: 'Entry', body: 'Input and routing boundary.', tone: 'blue', steps: ['Request', 'Route'] },
+    { title: 'Execution', body: 'Core modules and state changes.', tone: 'green', steps: ['Validate', 'Persist'] },
+  ]}
+/>
+
+<RoadmapMap
+  items={[
+    { title: 'Current shape', body: 'What the repo and runtime prove today.', status: 'now', tone: 'green' },
+    { title: 'Next structural move', body: 'The next architecture-level change.', status: 'next', tone: 'blue' },
+  ]}
+/>
+
 <ArchMap
   tiers={[
     {
@@ -225,12 +290,11 @@ agent-docs-kit check
 ## Run the Docs Site
 
 ```bash
-cd docs
-npm install
-npm run dev -- --port 3333
+agent-docs-kit web
 ```
 
-Fumadocs reads MDX from `docs/content/docs`.
+Fumadocs reads MDX from `docs/content/docs`. If you prefer to run the generated
+app directly, use `cd docs && npm install && npm run dev -- --port 3333`.
 
 ## Publish to PyPI
 
@@ -250,8 +314,8 @@ One-time PyPI setup for a new package:
 After that, publish a release by tagging the commit:
 
 ```bash
-git tag -a v2.1.0 -m v2.1.0
-git push origin v2.1.0
+git tag -a v2.2.1 -m v2.2.1
+git push origin v2.2.1
 ```
 
 The workflow builds the Python package with `uv build` and uploads the
@@ -260,11 +324,13 @@ distribution files to PyPI.
 ## Authoring Contract
 
 - MDX is the source of truth.
+- The Project Atlas is the first project-level architecture surface.
 - Architecture pages describe current state.
 - Change pages are immutable records of shipped changes.
 - Plan pages describe future intent.
 - Glossary pages are generated from frontmatter `terms`.
-- Architecture and change pages should include `<ArchMap />` or mermaid diagrams.
+- Architecture and change pages should include an Atlas/architecture component or mermaid diagram.
+- Do not create feature-level pages by default; prefer a broad Atlas first.
 - Validation must pass before treating docs work as complete.
 
 ## CLI
@@ -273,6 +339,8 @@ distribution files to PyPI.
 agent-docs-kit init
 agent-docs-kit init [target] [--integration codex|claude|copilot|cursor|gemini|generic] [--docs-dir docs] [--force] [--yes]
 agent-docs-kit init . --style atlas --interactive
+agent-docs-kit web [target] [--port 3333] [--host 127.0.0.1] [--open] [--no-install]
+agent-docs-kit atlas [target] [--output docs/content/docs/atlas.mdx] [--force] [--stdout]
 agent-docs-kit check
 agent-docs-kit skills
 agent-docs-kit styles

{agent_docs_kit-2.1.0 → agent_docs_kit-2.2.1}/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-docs-kit",
-  "version": "2.1.0",
-  "description": "Bootstrap a generic Fumadocs + MDX documentation system with project-local scripts, agent skills, managed context blocks, glossary generation, and validation.",
+  "version": "2.2.1",
+  "description": "Bootstrap a Fumadocs + MDX Project Atlas with project-local scripts, agent skills, managed context blocks, glossary generation, and validation.",
   "license": "MIT",
   "author": {
     "name": "wuyuxiangX"

{agent_docs_kit-2.1.0 → agent_docs_kit-2.2.1}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "agent-docs-kit"
-version = "2.1.0"
-description = "Bootstrap and maintain a Fumadocs-powered MDX documentation system with agent skills, reusable templates, and validation."
+version = "2.2.1"
+description = "Bootstrap and maintain a Fumadocs-powered Project Atlas with agent skills, reusable templates, and validation."
 requires-python = ">=3.10"
 dependencies = []
 authors = [