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

living_docs_cli/assets/fumadocs-starter/components/mdx.tsx

@@ -0,0 +1,27 @@
+import defaultMdxComponents from 'fumadocs-ui/mdx';
+import type { MDXComponents } from 'mdx/types';
+import {
+  ArchMap,
+  ChangeMeta,
+  DocsHero,
+  FlowSteps,
+  SkillGrid,
+  StateFlow,
+  TermGrid,
+} from './living-docs';
+
+export function getMDXComponents(components?: MDXComponents) {
+  return {
+    ...defaultMdxComponents,
+    ArchMap,
+    ChangeMeta,
+    DocsHero,
+    FlowSteps,
+    SkillGrid,
+    StateFlow,
+    TermGrid,
+    ...components,
+  } satisfies MDXComponents;
+}
+
+export const useMDXComponents = getMDXComponents;

living_docs_cli/assets/fumadocs-starter/content/docs/architecture.mdx

@@ -0,0 +1,55 @@
+---
+title: "System Architecture"
+description: "Current cross-domain architecture."
+domain: "system"
+type: "architecture"
+status: "active"
+date: "__TODAY__"
+terms:
+  - name: "Domain"
+    description: "A documentation area that maps to a subsystem, product surface, or ownership boundary."
+  - name: "Change Record"
+    description: "An immutable page that records a shipped change, its motivation, and verification."
+---
+
+# System Architecture
+
+Use this page for cross-domain architecture. Keep it current; put history in change records.
+
+<ArchMap
+  tiers={[
+    {
+      title: 'Documentation source',
+      boxes: [
+        { title: 'MDX pages', body: 'Human and agent editable source files.', tone: 'blue' },
+        { title: 'Frontmatter', body: 'Structured metadata for domains, types, dates, and terms.' },
+      ],
+    },
+    {
+      title: 'Presentation',
+      boxes: [
+        { title: 'Fumadocs', body: 'Renders navigation, search-ready pages, and MDX components.', tone: 'green' },
+      ],
+    },
+    {
+      title: 'Agent workflow',
+      boxes: [
+        { title: 'living-docs skills', body: 'Create architecture, change, plan, glossary, and check workflows.', tone: 'violet' },
+      ],
+    },
+  ]}
+/>
+
+## Maintenance Rules
+
+- Update architecture pages after meaningful system changes.
+- Create change records for shipped behavior, contracts, or architecture changes.
+- Run the glossary generator when terms change.
+- Run the check gate before committing docs changes.
+
+<TermGrid
+  items={[
+    { name: 'Domain', description: 'A documentation area that maps to a subsystem, product surface, or ownership boundary.' },
+    { name: 'Change Record', description: 'An immutable page that records a shipped change, its motivation, and verification.' },
+  ]}
+/>

living_docs_cli/assets/fumadocs-starter/content/docs/components.mdx

@@ -0,0 +1,132 @@
+---
+title: "Components"
+description: "Reusable MDX components for architecture, flow, state, change, and glossary docs."
+type: "guide"
+---
+
+# Components
+
+Use these MDX components directly in living-docs pages. Prefer components for
+common documentation shapes, and use mermaid only when the diagram needs custom
+graph syntax such as sequence diagrams, complex branches, or ER diagrams.
+
+## Architecture Map
+
+Use `<ArchMap />` for layered system structure.
+
+```mdx
+<ArchMap
+  tiers={[
+    {
+      title: 'Entry points',
+      boxes: [
+        { title: 'Web app', body: 'User-facing route or shell.', tone: 'blue' },
+        { title: 'API', body: 'Server boundary and contract.', tone: 'green' },
+      ],
+    },
+    {
+      title: 'Core services',
+      boxes: [
+        { title: 'Domain service', body: 'Business rules and orchestration.' },
+      ],
+    },
+  ]}
+/>
+```
+
+<ArchMap
+  tiers={[
+    {
+      title: 'Entry points',
+      boxes: [
+        { title: 'Web app', body: 'User-facing route or shell.', tone: 'blue' },
+        { title: 'API', body: 'Server boundary and contract.', tone: 'green' },
+      ],
+    },
+    {
+      title: 'Core services',
+      boxes: [
+        { title: 'Domain service', body: 'Business rules and orchestration.' },
+      ],
+    },
+  ]}
+/>
+
+## Flow Steps
+
+Use `<FlowSteps />` for request paths, execution flows, or operational runbooks.
+
+```mdx
+<FlowSteps
+  title="Request flow"
+  steps={[
+    { title: 'Receive input', body: 'Validate payload and identify the domain.', tone: 'blue' },
+    { title: 'Run service', body: 'Execute the domain action and persist state.', tone: 'green' },
+    { title: 'Return result', body: 'Send user-visible status and telemetry.', tone: 'amber' },
+  ]}
+/>
+```
+
+<FlowSteps
+  title="Request flow"
+  steps={[
+    { title: 'Receive input', body: 'Validate payload and identify the domain.', tone: 'blue' },
+    { title: 'Run service', body: 'Execute the domain action and persist state.', tone: 'green' },
+    { title: 'Return result', body: 'Send user-visible status and telemetry.', tone: 'amber' },
+  ]}
+/>
+
+## State Flow
+
+Use `<StateFlow />` for lifecycle states and simple state machines.
+
+```mdx
+<StateFlow
+  title="Document lifecycle"
+  states={[
+    { name: 'draft', description: 'Plan or work in progress.', tone: 'amber' },
+    { name: 'active', description: 'Current runtime truth.', tone: 'green' },
+    { name: 'archived', description: 'Kept for history.' },
+  ]}
+/>
+```
+
+<StateFlow
+  title="Document lifecycle"
+  states={[
+    { name: 'draft', description: 'Plan or work in progress.', tone: 'amber' },
+    { name: 'active', description: 'Current runtime truth.', tone: 'green' },
+    { name: 'archived', description: 'Kept for history.' },
+  ]}
+/>
+
+## Change Metadata
+
+Use `<ChangeMeta />` at the top of change records.
+
+```mdx
+<ChangeMeta date="2026-06-17" source="commit or PR" tests="npm run build" />
+```
+
+<ChangeMeta date="2026-06-17" source="commit or PR" tests="npm run build" />
+
+## Terms
+
+Use `<TermGrid />` for page-local vocabulary. The generated glossary is still
+built from frontmatter `terms`, so keep the frontmatter updated too.
+
+```mdx
+<TermGrid
+  items={[
+    { name: 'Domain', description: 'A subsystem or business area.' },
+    { name: 'Change record', description: 'Immutable record of shipped behavior.' },
+  ]}
+/>
+```
+
+<TermGrid
+  items={[
+    { name: 'Domain', description: 'A subsystem or business area.' },
+    { name: 'Change record', description: 'Immutable record of shipped behavior.' },
+  ]}
+/>

living_docs_cli/assets/fumadocs-starter/content/docs/glossary.mdx

@@ -0,0 +1,16 @@
+---
+title: "Glossary"
+description: "Generated term index for living-docs"
+type: "glossary"
+---
+
+# Glossary
+
+Generated from MDX frontmatter `terms`.
+
+<TermGrid
+  items={[
+    { name: "Change Record", description: "An immutable page that records a shipped change, its motivation, and verification.", meta: "system · architecture.mdx" },
+    { name: "Domain", description: "A documentation area that maps to a subsystem, product surface, or ownership boundary.", meta: "system · architecture.mdx" },
+  ]}
+/>

living_docs_cli/assets/fumadocs-starter/content/docs/index.mdx

@@ -0,0 +1,72 @@
+---
+title: "Overview"
+description: "A living documentation system powered by Fumadocs and MDX."
+type: "guide"
+---
+
+<DocsHero
+  title="__PROJECT_NAME__ Documentation"
+  description="A skills-first documentation workspace for architecture, shipped changes, future plans, and shared vocabulary."
+  primaryLabel="Open architecture"
+  primaryHref="/docs/architecture"
+  secondaryLabel="View glossary"
+  secondaryHref="/docs/glossary"
+/>
+
+This documentation system is managed by living-docs. Use MDX as the source of truth and Fumadocs as the presentation layer.
+
+Reusable documentation components are available in [Components](/docs/components).
+
+## Structure
+
+- Architecture pages describe current system shape.
+- Change pages record what changed and why.
+- Plan pages capture future design directions.
+- The glossary is generated from frontmatter `terms`.
+
+## Skills
+
+Use these project-local skills from your agent:
+
+<SkillGrid
+  items={[
+    {
+      name: 'living-docs-write',
+      body: 'Route general documentation requests to the right architecture, change, plan, glossary, or validation workflow.',
+      tone: 'violet',
+    },
+    {
+      name: 'living-docs-architecture',
+      body: 'Capture the current system shape, contracts, runtime paths, and diagrams.',
+      tone: 'blue',
+    },
+    {
+      name: 'living-docs-change',
+      body: 'Record shipped behavior changes with source files, validation, and follow-up notes.',
+      tone: 'green',
+    },
+    {
+      name: 'living-docs-plan',
+      body: 'Draft future design directions before they become committed change records.',
+      tone: 'amber',
+    },
+    {
+      name: 'living-docs-glossary',
+      body: 'Regenerate shared vocabulary from frontmatter terms across the docs.',
+      tone: 'violet',
+    },
+    {
+      name: 'living-docs-check',
+      body: 'Validate MDX health, required diagrams, generated glossary, and managed docs metadata.',
+      tone: 'red',
+    },
+  ]}
+/>
+
+The skills use these project-local scripts:
+
+```bash
+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
+```

living_docs_cli/assets/fumadocs-starter/content/docs/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "__PROJECT_NAME__",
+  "pages": ["index", "architecture", "components", "glossary", "..."]
+}

living_docs_cli/assets/fumadocs-starter/lib/layout.shared.ts

@@ -0,0 +1,7 @@
+import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
+
+export const baseOptions: BaseLayoutProps = {
+  nav: {
+    title: '__PROJECT_NAME__ Docs',
+  },
+};

living_docs_cli/assets/fumadocs-starter/lib/source.ts

@@ -0,0 +1,7 @@
+import { docs } from '@/.source/server';
+import { loader } from 'fumadocs-core/source';
+
+export const source = loader({
+  baseUrl: '/docs',
+  source: docs.toFumadocsSource(),
+});

living_docs_cli/assets/fumadocs-starter/next-env.d.ts

@@ -0,0 +1,4 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// This file is generated for the living-docs starter and should not be edited.

living_docs_cli/assets/fumadocs-starter/next.config.mjs

@@ -0,0 +1,10 @@
+import { createMDX } from 'fumadocs-mdx/next';
+
+const withMDX = createMDX();
+
+/** @type {import('next').NextConfig} */
+const config = {
+  reactStrictMode: true,
+};
+
+export default withMDX(config);

living_docs_cli/assets/fumadocs-starter/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "__PROJECT_NAME__-docs",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "typecheck": "fumadocs-mdx && tsc --noEmit",
+    "docs:check": "node ../.living-docs/scripts/check.mjs",
+    "docs:glossary": "node ../.living-docs/scripts/glossary.mjs"
+  },
+  "dependencies": {
+    "fumadocs-core": "^16.10.3",
+    "fumadocs-mdx": "^15.0.12",
+    "fumadocs-ui": "^16.10.3",
+    "next": "^16.2.9",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "^6.0.3"
+  }
+}

living_docs_cli/assets/fumadocs-starter/source.config.ts

@@ -0,0 +1,34 @@
+import { defineConfig, defineDocs } from 'fumadocs-mdx/config';
+import { pageSchema, metaSchema } from 'fumadocs-core/source/schema';
+import { z } from 'zod';
+
+export const docs = defineDocs({
+  dir: 'content/docs',
+  docs: {
+    schema: pageSchema.extend({
+      domain: z.string().optional(),
+      type: z.enum(['guide', 'architecture', 'change', 'plan', 'glossary']).default('guide'),
+      status: z.enum(['draft', 'active', 'shipped', 'deprecated']).optional(),
+      date: z.string().optional(),
+      source: z.string().optional(),
+      tests: z.string().optional(),
+      terms: z
+        .array(
+          z.object({
+            name: z.string(),
+            description: z.string(),
+          }),
+        )
+        .default([]),
+    }),
+  },
+  meta: {
+    schema: metaSchema,
+  },
+});
+
+export default defineConfig({
+  mdxOptions: {
+    providerImportSource: '@/components/mdx',
+  },
+});

living_docs_cli/assets/fumadocs-starter/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "es2022"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".source/**/*.ts", ".next/types/**/*.ts", ".next/dev/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

living_docs_cli/assets/project/.living-docs/scripts/check.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+const root = process.cwd();
+const configPath = join(root, '.living-docs', 'config.json');
+const errors = [];
+
+function walk(dir) {
+  const results = [];
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name);
+    const stat = statSync(path);
+    if (stat.isDirectory()) results.push(...walk(path));
+    if (stat.isFile() && path.endsWith('.mdx')) results.push(path);
+  }
+  return results;
+}
+
+function frontmatter(text) {
+  if (!text.startsWith('---\n')) return '';
+  const end = text.indexOf('\n---', 4);
+  return end === -1 ? '' : text.slice(4, end);
+}
+
+function scalar(fm, key) {
+  const match = fm.match(new RegExp(`^${key}:\\s*["']?([^"'\\n]+)["']?\\s*$`, 'm'));
+  return match?.[1]?.trim() || '';
+}
+
+function hasDiagram(text) {
+  return ['<ArchMap', '<FlowSteps', '<StateFlow', '```mermaid'].some((marker) => text.includes(marker));
+}
+
+if (!existsSync(configPath)) {
+  errors.push('missing .living-docs/config.json');
+} else {
+  const config = JSON.parse(readFileSync(configPath, 'utf8'));
+  const contentDir = join(root, config.contentDir || 'docs/content/docs');
+  if (!existsSync(contentDir)) {
+    errors.push(`missing content directory: ${relative(root, contentDir)}`);
+  } else {
+    const files = walk(contentDir);
+    if (files.length === 0) errors.push('no MDX files found');
+    for (const file of files) {
+      const rel = relative(root, file);
+      const text = readFileSync(file, 'utf8');
+      const fm = frontmatter(text);
+      const type = scalar(fm, 'type');
+      if (!scalar(fm, 'title')) errors.push(`${rel}: missing title`);
+      if (rel.includes('/changes/') && type !== 'change') errors.push(`${rel}: changes pages must set type: change`);
+      if (rel.includes('/plans/') && type !== 'plan') errors.push(`${rel}: plan pages must set type: plan`);
+      if ((type === 'architecture' || type === 'change') && !hasDiagram(text)) {
+        errors.push(`${rel}: architecture/change docs need <ArchMap />, <FlowSteps />, <StateFlow />, or mermaid`);
+      }
+      if ((type === 'architecture' || type === 'change' || type === 'plan') && !fm.includes('terms:') && !text.includes('<TermGrid')) {
+        errors.push(`${rel}: managed docs should define terms or render <TermGrid />`);
+      }
+    }
+    if (!existsSync(join(contentDir, 'glossary.mdx'))) {
+      errors.push('missing glossary.mdx; run node .living-docs/scripts/glossary.mjs');
+    }
+  }
+}
+
+if (errors.length) {
+  console.error(`living-docs check failed (${errors.length} issue(s))`);
+  for (const error of errors) console.error(`  - ${error}`);
+  process.exit(1);
+}
+
+console.log('living-docs check passed');

living_docs_cli/assets/project/.living-docs/scripts/create-doc.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = process.cwd();
+const configPath = join(root, '.living-docs', 'config.json');
+
+function fail(message) {
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+if (!existsSync(configPath)) {
+  fail('missing .living-docs/config.json; run living-docs init first');
+}
+
+const config = JSON.parse(readFileSync(configPath, 'utf8'));
+const contentDir = join(root, config.contentDir || 'docs/content/docs');
+const templatesDir = join(root, '.living-docs', 'templates');
+
+function slugify(input) {
+  return input
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'doc';
+}
+
+function titleize(input) {
+  return input
+    .replace(/[-_]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+function render(template, values) {
+  let out = template;
+  for (const [key, value] of Object.entries(values)) {
+    out = out.replaceAll(`__${key}__`, value);
+  }
+  return out;
+}
+
+function writeNew(path, content) {
+  if (existsSync(path)) {
+    fail(`refusing to overwrite existing file: ${path}`);
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content);
+}
+
+const [kind, domainArg, topicArg, ...titleParts] = process.argv.slice(2);
+if (!kind || !['architecture', 'change', 'plan'].includes(kind)) {
+  fail('usage: create-doc.mjs <architecture|change|plan> <domain> [topic-slug] [title]');
+}
+if (!domainArg) {
+  fail('domain is required');
+}
+
+const domain = slugify(domainArg);
+const today = new Date().toISOString().slice(0, 10);
+const topic = topicArg ? slugify(topicArg) : domain;
+const title = titleParts.length ? titleParts.join(' ') : titleize(topic);
+const source = process.env.LIVING_DOCS_SOURCE || 'TODO';
+const tests = process.env.LIVING_DOCS_TESTS || 'TODO';
+
+let templateName = `${kind}.mdx`;
+let outPath;
+if (kind === 'architecture') {
+  outPath = join(contentDir, domain, 'architecture.mdx');
+} else if (kind === 'change') {
+  outPath = join(contentDir, domain, 'changes', `${today}-${topic}.mdx`);
+} else {
+  outPath = join(contentDir, domain, 'plans', `${topic}.mdx`);
+}
+
+const template = readFileSync(join(templatesDir, templateName), 'utf8');
+writeNew(outPath, render(template, {
+  TITLE: title,
+  DOMAIN: domain,
+  DATE: today,
+  SOURCE: source,
+  TESTS: tests,
+}));
+
+console.log(outPath);