@x12i/xops-docs 0.1.0

package/README.md

@@ -0,0 +1,29 @@
+# `@x12i/xops-docs`
+
+xops docs **knowledge SDK** — install as a **devDependency** only. It bundles
+the xops catalog, use cases, and Markdown packs for humans and agents.
+
+```bash
+npm i -D @x12i/xops-docs
+```
+
+```ts
+import { xopsDocs } from "@x12i/xops-docs";
+
+xopsDocs.listBooks();
+xopsDocs.getBookMarkdown("01-install-and-daily", "developers");
+xopsDocs.getUseCaseMarkdown("run-a-safe-release");
+xopsDocs.manifest(); // agent-manifest for discovery
+```
+
+CLI:
+
+```bash
+xops-docs list-books
+xops-docs list-use-cases
+xops-docs book 00-platform-overview developers
+xops-docs use-case orient-xops
+```
+
+The embedded content is generated from `xops-docs/` by the platform build
+(`npm run build`); do not edit `src/generated/`.

package/bin/xops-docs.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import("../dist/cli.js");

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import { xopsDocs } from "./index.js";
+const [cmd, id, audience] = process.argv.slice(2);
+function usage() {
+    console.error(`Usage:
+  xops-docs use-case <id>          Print assembled use-case markdown
+  xops-docs book <id> <audience>   Print book markdown
+  xops-docs list-use-cases         List use case ids
+  xops-docs list-books             List book ids
+`);
+}
+if (!cmd || cmd === "help" || cmd === "--help") {
+    usage();
+    process.exit(cmd ? 0 : 1);
+}
+if (cmd === "list-use-cases") {
+    for (const uc of xopsDocs.listUseCases()) {
+        console.log(`${uc.id}\t${uc.title}`);
+    }
+    process.exit(0);
+}
+if (cmd === "list-books") {
+    for (const b of xopsDocs.listBooks()) {
+        console.log(`${b.id}\t${b.title}\t${b.audiences.join(",")}`);
+    }
+    process.exit(0);
+}
+if (cmd === "use-case") {
+    if (!id) {
+        usage();
+        process.exit(1);
+    }
+    const md = xopsDocs.getUseCaseMarkdown(id);
+    if (!md) {
+        console.error(`Unknown use case: ${id}`);
+        process.exit(1);
+    }
+    process.stdout.write(md);
+    process.exit(0);
+}
+if (cmd === "book") {
+    if (!id || !audience) {
+        usage();
+        process.exit(1);
+    }
+    const md = xopsDocs.getBookMarkdown(id, audience);
+    if (!md) {
+        console.error(`Unknown book/audience: ${id} ${audience}`);
+        process.exit(1);
+    }
+    process.stdout.write(md);
+    process.exit(0);
+}
+usage();
+process.exit(1);

package/dist/generated/bundle.d.ts

@@ -0,0 +1,345 @@
+export declare const catalog: {
+    readonly roles: readonly [{
+        readonly id: "developers";
+        readonly label: "Developers";
+        readonly tagline: "Run xops every day";
+        readonly description: "Humans and coding agents who install, release, ask, and operate Node.js repositories through xops.";
+    }, {
+        readonly id: "builders";
+        readonly label: "Operators";
+        readonly tagline: "Set up PATH, CI, and the operating contract";
+        readonly description: "People who bootstrap the CLI, wire CI/agent hosts, and keep doctor/ops status green.";
+    }];
+    readonly families: readonly [{
+        readonly id: "xops";
+        readonly name: "xops";
+        readonly tagline: "The operating layer for Node.js repositories.";
+        readonly description: "Detects repo state, routes work to native owners, plans risky actions, executes approved workflows, and reports what happened — via CLI, SDK, and MCP.";
+        readonly color: "#1a2f45";
+    }];
+    readonly books: readonly [{
+        readonly id: "00-platform-overview";
+        readonly familyId: "xops";
+        readonly audiences: readonly ["developers", "builders"];
+        readonly status: "available";
+        readonly kicker: "CASE FILE · XOPS-00";
+        readonly title: "Platform Overview";
+        readonly subtitle: "Mental model and surfaces";
+        readonly blurb: "What xops is, the operating contract, three interfaces, and which book to open next.";
+        readonly tags: readonly ["platform", "start-here"];
+        readonly color: "#1a2f45";
+        readonly dir: "00-platform-overview";
+    }, {
+        readonly id: "01-install-and-daily";
+        readonly familyId: "xops";
+        readonly audiences: readonly ["developers"];
+        readonly status: "available";
+        readonly kicker: "CASE FILE · XOPS-01";
+        readonly title: "Install and Daily CLI";
+        readonly subtitle: "Get xops on PATH and use it every day";
+        readonly blurb: "Global install, doctor, workspace install-once, and the daily command surface.";
+        readonly tags: readonly ["install", "cli", "workspaces"];
+        readonly color: "#b14a2c";
+        readonly dir: "01-install-and-daily";
+    }, {
+        readonly id: "02-release-and-publish";
+        readonly familyId: "xops";
+        readonly audiences: readonly ["developers"];
+        readonly status: "available";
+        readonly kicker: "CASE FILE · XOPS-02";
+        readonly title: "Release and Publish";
+        readonly subtitle: "The original wedge";
+        readonly blurb: "Discovery, dependency order, safety, publish, push, and undo for humans and agents.";
+        readonly tags: readonly ["release", "publish", "safety"];
+        readonly color: "#1f6e5c";
+        readonly dir: "02-release-and-publish";
+    }, {
+        readonly id: "03-cli-sdk-mcp";
+        readonly familyId: "xops";
+        readonly audiences: readonly ["developers"];
+        readonly status: "available";
+        readonly kicker: "CASE FILE · XOPS-03";
+        readonly title: "CLI, SDK, and MCP";
+        readonly subtitle: "One contract, three interfaces";
+        readonly blurb: "Ask, typed SDK results, MCP tools/resources, and plan-first approvals for agents.";
+        readonly tags: readonly ["sdk", "mcp", "ask", "agents"];
+        readonly color: "#a5710f";
+        readonly dir: "03-cli-sdk-mcp";
+    }, {
+        readonly id: "04-ops-and-tools";
+        readonly familyId: "xops";
+        readonly audiences: readonly ["builders"];
+        readonly status: "available";
+        readonly kicker: "CASE FILE · XOPS-04";
+        readonly title: "Ops and Tools";
+        readonly subtitle: "Catalog, recommendations, playbooks";
+        readonly blurb: "ops status, recommendations, seamless tools, and operational playbooks.";
+        readonly tags: readonly ["ops", "tools", "playbooks"];
+        readonly color: "#2c5f7a";
+        readonly dir: "04-ops-and-tools";
+        readonly buildersPrimary: true;
+    }, {
+        readonly id: "05-agents-and-safety";
+        readonly familyId: "xops";
+        readonly audiences: readonly ["developers"];
+        readonly status: "available";
+        readonly kicker: "CASE FILE · XOPS-05";
+        readonly title: "Agents and Safety";
+        readonly subtitle: "Agent packs, gitignore, publish safety";
+        readonly blurb: "AI context packs, safety gates, and how agents should call xops without scraping terminals.";
+        readonly tags: readonly ["agents", "safety", "ai-pack"];
+        readonly color: "#4a3f6b";
+        readonly dir: "05-agents-and-safety";
+    }];
+};
+export declare const useCases: {
+    readonly useCases: readonly [{
+        readonly id: "orient-xops";
+        readonly title: "Orient on xops";
+        readonly goal: "Understand the operating layer, three interfaces, and which book to open next.";
+        readonly audiences: readonly ["developers", "builders"];
+        readonly tags: readonly ["platform", "start-here"];
+        readonly path: readonly [{
+            readonly bookId: "00-platform-overview";
+            readonly audience: "developers";
+            readonly chapters: readonly ["the-mental-model", "one-contract-three-interfaces", "what-xops-owns", "hard-product-rules", "which-book-next"];
+        }];
+        readonly alsoSee: readonly ["00-platform-overview"];
+    }, {
+        readonly id: "install-and-doctor";
+        readonly title: "Install xops and run doctor";
+        readonly goal: "Get @x12i/xops on PATH, confirm shims, and clear doctor checks.";
+        readonly audiences: readonly ["developers", "builders"];
+        readonly tags: readonly ["install", "doctor"];
+        readonly path: readonly [{
+            readonly bookId: "01-install-and-daily";
+            readonly audience: "developers";
+            readonly chapters: readonly ["install-the-cli", "confirm-on-path", "run-doctor", "workspace-install-once"];
+        }];
+        readonly alsoSee: readonly ["01-install-and-daily", "04-ops-and-tools"];
+    }, {
+        readonly id: "run-a-safe-release";
+        readonly title: "Run a safe release";
+        readonly goal: "Plan, approve, publish, and undo a monorepo or single-package release.";
+        readonly audiences: readonly ["developers"];
+        readonly tags: readonly ["release", "publish"];
+        readonly path: readonly [{
+            readonly bookId: "02-release-and-publish";
+            readonly audience: "developers";
+            readonly chapters: readonly ["discovery-and-order", "safety-gates", "publish-and-push", "undo-and-recovery"];
+        }];
+        readonly alsoSee: readonly ["02-release-and-publish", "05-agents-and-safety"];
+    }, {
+        readonly id: "wire-sdk-or-mcp";
+        readonly title: "Wire the SDK or MCP";
+        readonly goal: "Call the same operating layer from TypeScript or an MCP host with plan-first approvals.";
+        readonly audiences: readonly ["developers"];
+        readonly tags: readonly ["sdk", "mcp", "agents"];
+        readonly path: readonly [{
+            readonly bookId: "03-cli-sdk-mcp";
+            readonly audience: "developers";
+            readonly chapters: readonly ["ask-and-passthrough", "typed-sdk-results", "mcp-tools-and-resources", "plan-first-approvals"];
+        }];
+        readonly alsoSee: readonly ["03-cli-sdk-mcp", "05-agents-and-safety"];
+    }, {
+        readonly id: "operate-the-tool-catalog";
+        readonly title: "Operate the tool catalog";
+        readonly goal: "Read ops status, apply recommendations, and run playbooks without inventing a second ops stack.";
+        readonly audiences: readonly ["builders"];
+        readonly tags: readonly ["ops", "tools", "playbooks"];
+        readonly path: readonly [{
+            readonly bookId: "04-ops-and-tools";
+            readonly audience: "builders";
+            readonly chapters: readonly ["ops-status", "recommendations", "seamless-tools", "playbooks"];
+        }];
+        readonly alsoSee: readonly ["04-ops-and-tools", "00-platform-overview"];
+    }, {
+        readonly id: "brief-a-coding-agent";
+        readonly title: "Brief a coding agent";
+        readonly goal: "Generate AI context packs and teach an agent to use xops safely.";
+        readonly audiences: readonly ["developers"];
+        readonly tags: readonly ["agents", "ai-pack", "safety"];
+        readonly path: readonly [{
+            readonly bookId: "05-agents-and-safety";
+            readonly audience: "developers";
+            readonly chapters: readonly ["ai-packs", "agent-call-shape", "publish-and-secret-safety", "knowledge-sdk"];
+        }];
+        readonly alsoSee: readonly ["05-agents-and-safety", "03-cli-sdk-mcp"];
+    }];
+};
+export declare const site: {
+    readonly product: "xops";
+    readonly brand: "xops · docs";
+    readonly brandAccent: "docs";
+    readonly siteUrl: "https://docs.xops.x12i.com";
+    readonly knowledgePackage: "@x12i/xops-docs";
+    readonly footer: "XOPS FIELD GUIDES · OPERATING LAYER";
+    readonly accent: "oklch(42% 0.09 250)";
+    readonly accentAlt: "oklch(52% 0.11 35)";
+    readonly productUrl: "https://github.com/x12i/npm";
+    readonly nav: readonly [{
+        readonly label: "Getting started";
+        readonly href: "/getting-started";
+    }, {
+        readonly label: "Use cases";
+        readonly href: "/use-cases";
+    }, {
+        readonly label: "Catalog";
+        readonly href: "/catalog";
+    }];
+    readonly footerLinks: readonly [{
+        readonly label: "Docs home";
+        readonly href: "/docs";
+    }, {
+        readonly label: "Getting started";
+        readonly href: "/getting-started";
+    }, {
+        readonly label: "Use cases";
+        readonly href: "/use-cases";
+    }, {
+        readonly label: "Catalog";
+        readonly href: "/catalog";
+    }, {
+        readonly label: "Agents/SDK";
+        readonly href: "/agents";
+    }];
+};
+export declare const manifest: {
+    readonly version: 1;
+    readonly product: "xops";
+    readonly site: "https://docs.xops.x12i.com";
+    readonly knowledgePackage: "@x12i/xops-docs";
+    readonly roles: readonly ["developers", "builders"];
+    readonly books: readonly [{
+        readonly id: "00-platform-overview";
+        readonly audiences: readonly ["developers", "builders"];
+        readonly md: {
+            readonly developers: "downloads/books/00-platform-overview/developers.md";
+            readonly builders: "downloads/books/00-platform-overview/builders.md";
+        };
+        readonly pdf: {
+            readonly developers: null;
+            readonly builders: null;
+        };
+        readonly chapters: {
+            readonly developers: "downloads/books/00-platform-overview/developers.chapters.json";
+            readonly builders: "downloads/books/00-platform-overview/builders.chapters.json";
+        };
+    }, {
+        readonly id: "01-install-and-daily";
+        readonly audiences: readonly ["developers"];
+        readonly md: {
+            readonly developers: "downloads/books/01-install-and-daily/developers.md";
+        };
+        readonly pdf: {
+            readonly developers: null;
+        };
+        readonly chapters: {
+            readonly developers: "downloads/books/01-install-and-daily/developers.chapters.json";
+        };
+    }, {
+        readonly id: "02-release-and-publish";
+        readonly audiences: readonly ["developers"];
+        readonly md: {
+            readonly developers: "downloads/books/02-release-and-publish/developers.md";
+        };
+        readonly pdf: {
+            readonly developers: null;
+        };
+        readonly chapters: {
+            readonly developers: "downloads/books/02-release-and-publish/developers.chapters.json";
+        };
+    }, {
+        readonly id: "03-cli-sdk-mcp";
+        readonly audiences: readonly ["developers"];
+        readonly md: {
+            readonly developers: "downloads/books/03-cli-sdk-mcp/developers.md";
+        };
+        readonly pdf: {
+            readonly developers: null;
+        };
+        readonly chapters: {
+            readonly developers: "downloads/books/03-cli-sdk-mcp/developers.chapters.json";
+        };
+    }, {
+        readonly id: "04-ops-and-tools";
+        readonly audiences: readonly ["builders"];
+        readonly md: {
+            readonly builders: "downloads/books/04-ops-and-tools/builders.md";
+        };
+        readonly pdf: {
+            readonly builders: null;
+        };
+        readonly chapters: {
+            readonly builders: "downloads/books/04-ops-and-tools/builders.chapters.json";
+        };
+    }, {
+        readonly id: "05-agents-and-safety";
+        readonly audiences: readonly ["developers"];
+        readonly md: {
+            readonly developers: "downloads/books/05-agents-and-safety/developers.md";
+        };
+        readonly pdf: {
+            readonly developers: null;
+        };
+        readonly chapters: {
+            readonly developers: "downloads/books/05-agents-and-safety/developers.chapters.json";
+        };
+    }];
+    readonly useCases: readonly [{
+        readonly id: "orient-xops";
+        readonly title: "Orient on xops";
+        readonly md: "downloads/use-cases/orient-xops.md";
+        readonly path: readonly [{
+            readonly bookId: "00-platform-overview";
+            readonly audience: "developers";
+            readonly chapters: readonly ["the-mental-model", "one-contract-three-interfaces", "what-xops-owns", "hard-product-rules", "which-book-next"];
+        }];
+    }, {
+        readonly id: "install-and-doctor";
+        readonly title: "Install xops and run doctor";
+        readonly md: "downloads/use-cases/install-and-doctor.md";
+        readonly path: readonly [{
+            readonly bookId: "01-install-and-daily";
+            readonly audience: "developers";
+            readonly chapters: readonly ["install-the-cli", "confirm-on-path", "run-doctor", "workspace-install-once"];
+        }];
+    }, {
+        readonly id: "run-a-safe-release";
+        readonly title: "Run a safe release";
+        readonly md: "downloads/use-cases/run-a-safe-release.md";
+        readonly path: readonly [{
+            readonly bookId: "02-release-and-publish";
+            readonly audience: "developers";
+            readonly chapters: readonly ["discovery-and-order", "safety-gates", "publish-and-push", "undo-and-recovery"];
+        }];
+    }, {
+        readonly id: "wire-sdk-or-mcp";
+        readonly title: "Wire the SDK or MCP";
+        readonly md: "downloads/use-cases/wire-sdk-or-mcp.md";
+        readonly path: readonly [{
+            readonly bookId: "03-cli-sdk-mcp";
+            readonly audience: "developers";
+            readonly chapters: readonly ["ask-and-passthrough", "typed-sdk-results", "mcp-tools-and-resources", "plan-first-approvals"];
+        }];
+    }, {
+        readonly id: "operate-the-tool-catalog";
+        readonly title: "Operate the tool catalog";
+        readonly md: "downloads/use-cases/operate-the-tool-catalog.md";
+        readonly path: readonly [{
+            readonly bookId: "04-ops-and-tools";
+            readonly audience: "builders";
+            readonly chapters: readonly ["ops-status", "recommendations", "seamless-tools", "playbooks"];
+        }];
+    }, {
+        readonly id: "brief-a-coding-agent";
+        readonly title: "Brief a coding agent";
+        readonly md: "downloads/use-cases/brief-a-coding-agent.md";
+        readonly path: readonly [{
+            readonly bookId: "05-agents-and-safety";
+            readonly audience: "developers";
+            readonly chapters: readonly ["ai-packs", "agent-call-shape", "publish-and-secret-safety", "knowledge-sdk"];
+        }];
+    }];
+};
+export declare const files: Record<string, string>;

package/dist/generated/bundle.js

@@ -0,0 +1,605 @@
+/* Auto-generated by scripts/build-knowledge.mjs — do not edit */
+export const catalog = {
+    "roles": [
+        {
+            "id": "developers",
+            "label": "Developers",
+            "tagline": "Run xops every day",
+            "description": "Humans and coding agents who install, release, ask, and operate Node.js repositories through xops."
+        },
+        {
+            "id": "builders",
+            "label": "Operators",
+            "tagline": "Set up PATH, CI, and the operating contract",
+            "description": "People who bootstrap the CLI, wire CI/agent hosts, and keep doctor/ops status green."
+        }
+    ],
+    "families": [
+        {
+            "id": "xops",
+            "name": "xops",
+            "tagline": "The operating layer for Node.js repositories.",
+            "description": "Detects repo state, routes work to native owners, plans risky actions, executes approved workflows, and reports what happened — via CLI, SDK, and MCP.",
+            "color": "#1a2f45"
+        }
+    ],
+    "books": [
+        {
+            "id": "00-platform-overview",
+            "familyId": "xops",
+            "audiences": [
+                "developers",
+                "builders"
+            ],
+            "status": "available",
+            "kicker": "CASE FILE · XOPS-00",
+            "title": "Platform Overview",
+            "subtitle": "Mental model and surfaces",
+            "blurb": "What xops is, the operating contract, three interfaces, and which book to open next.",
+            "tags": [
+                "platform",
+                "start-here"
+            ],
+            "color": "#1a2f45",
+            "dir": "00-platform-overview"
+        },
+        {
+            "id": "01-install-and-daily",
+            "familyId": "xops",
+            "audiences": [
+                "developers"
+            ],
+            "status": "available",
+            "kicker": "CASE FILE · XOPS-01",
+            "title": "Install and Daily CLI",
+            "subtitle": "Get xops on PATH and use it every day",
+            "blurb": "Global install, doctor, workspace install-once, and the daily command surface.",
+            "tags": [
+                "install",
+                "cli",
+                "workspaces"
+            ],
+            "color": "#b14a2c",
+            "dir": "01-install-and-daily"
+        },
+        {
+            "id": "02-release-and-publish",
+            "familyId": "xops",
+            "audiences": [
+                "developers"
+            ],
+            "status": "available",
+            "kicker": "CASE FILE · XOPS-02",
+            "title": "Release and Publish",
+            "subtitle": "The original wedge",
+            "blurb": "Discovery, dependency order, safety, publish, push, and undo for humans and agents.",
+            "tags": [
+                "release",
+                "publish",
+                "safety"
+            ],
+            "color": "#1f6e5c",
+            "dir": "02-release-and-publish"
+        },
+        {
+            "id": "03-cli-sdk-mcp",
+            "familyId": "xops",
+            "audiences": [
+                "developers"
+            ],
+            "status": "available",
+            "kicker": "CASE FILE · XOPS-03",
+            "title": "CLI, SDK, and MCP",
+            "subtitle": "One contract, three interfaces",
+            "blurb": "Ask, typed SDK results, MCP tools/resources, and plan-first approvals for agents.",
+            "tags": [
+                "sdk",
+                "mcp",
+                "ask",
+                "agents"
+            ],
+            "color": "#a5710f",
+            "dir": "03-cli-sdk-mcp"
+        },
+        {
+            "id": "04-ops-and-tools",
+            "familyId": "xops",
+            "audiences": [
+                "builders"
+            ],
+            "status": "available",
+            "kicker": "CASE FILE · XOPS-04",
+            "title": "Ops and Tools",
+            "subtitle": "Catalog, recommendations, playbooks",
+            "blurb": "ops status, recommendations, seamless tools, and operational playbooks.",
+            "tags": [
+                "ops",
+                "tools",
+                "playbooks"
+            ],
+            "color": "#2c5f7a",
+            "dir": "04-ops-and-tools",
+            "buildersPrimary": true
+        },
+        {
+            "id": "05-agents-and-safety",
+            "familyId": "xops",
+            "audiences": [
+                "developers"
+            ],
+            "status": "available",
+            "kicker": "CASE FILE · XOPS-05",
+            "title": "Agents and Safety",
+            "subtitle": "Agent packs, gitignore, publish safety",
+            "blurb": "AI context packs, safety gates, and how agents should call xops without scraping terminals.",
+            "tags": [
+                "agents",
+                "safety",
+                "ai-pack"
+            ],
+            "color": "#4a3f6b",
+            "dir": "05-agents-and-safety"
+        }
+    ]
+};
+export const useCases = {
+    "useCases": [
+        {
+            "id": "orient-xops",
+            "title": "Orient on xops",
+            "goal": "Understand the operating layer, three interfaces, and which book to open next.",
+            "audiences": [
+                "developers",
+                "builders"
+            ],
+            "tags": [
+                "platform",
+                "start-here"
+            ],
+            "path": [
+                {
+                    "bookId": "00-platform-overview",
+                    "audience": "developers",
+                    "chapters": [
+                        "the-mental-model",
+                        "one-contract-three-interfaces",
+                        "what-xops-owns",
+                        "hard-product-rules",
+                        "which-book-next"
+                    ]
+                }
+            ],
+            "alsoSee": [
+                "00-platform-overview"
+            ]
+        },
+        {
+            "id": "install-and-doctor",
+            "title": "Install xops and run doctor",
+            "goal": "Get @x12i/xops on PATH, confirm shims, and clear doctor checks.",
+            "audiences": [
+                "developers",
+                "builders"
+            ],
+            "tags": [
+                "install",
+                "doctor"
+            ],
+            "path": [
+                {
+                    "bookId": "01-install-and-daily",
+                    "audience": "developers",
+                    "chapters": [
+                        "install-the-cli",
+                        "confirm-on-path",
+                        "run-doctor",
+                        "workspace-install-once"
+                    ]
+                }
+            ],
+            "alsoSee": [
+                "01-install-and-daily",
+                "04-ops-and-tools"
+            ]
+        },
+        {
+            "id": "run-a-safe-release",
+            "title": "Run a safe release",
+            "goal": "Plan, approve, publish, and undo a monorepo or single-package release.",
+            "audiences": [
+                "developers"
+            ],
+            "tags": [
+                "release",
+                "publish"
+            ],
+            "path": [
+                {
+                    "bookId": "02-release-and-publish",
+                    "audience": "developers",
+                    "chapters": [
+                        "discovery-and-order",
+                        "safety-gates",
+                        "publish-and-push",
+                        "undo-and-recovery"
+                    ]
+                }
+            ],
+            "alsoSee": [
+                "02-release-and-publish",
+                "05-agents-and-safety"
+            ]
+        },
+        {
+            "id": "wire-sdk-or-mcp",
+            "title": "Wire the SDK or MCP",
+            "goal": "Call the same operating layer from TypeScript or an MCP host with plan-first approvals.",
+            "audiences": [
+                "developers"
+            ],
+            "tags": [
+                "sdk",
+                "mcp",
+                "agents"
+            ],
+            "path": [
+                {
+                    "bookId": "03-cli-sdk-mcp",
+                    "audience": "developers",
+                    "chapters": [
+                        "ask-and-passthrough",
+                        "typed-sdk-results",
+                        "mcp-tools-and-resources",
+                        "plan-first-approvals"
+                    ]
+                }
+            ],
+            "alsoSee": [
+                "03-cli-sdk-mcp",
+                "05-agents-and-safety"
+            ]
+        },
+        {
+            "id": "operate-the-tool-catalog",
+            "title": "Operate the tool catalog",
+            "goal": "Read ops status, apply recommendations, and run playbooks without inventing a second ops stack.",
+            "audiences": [
+                "builders"
+            ],
+            "tags": [
+                "ops",
+                "tools",
+                "playbooks"
+            ],
+            "path": [
+                {
+                    "bookId": "04-ops-and-tools",
+                    "audience": "builders",
+                    "chapters": [
+                        "ops-status",
+                        "recommendations",
+                        "seamless-tools",
+                        "playbooks"
+                    ]
+                }
+            ],
+            "alsoSee": [
+                "04-ops-and-tools",
+                "00-platform-overview"
+            ]
+        },
+        {
+            "id": "brief-a-coding-agent",
+            "title": "Brief a coding agent",
+            "goal": "Generate AI context packs and teach an agent to use xops safely.",
+            "audiences": [
+                "developers"
+            ],
+            "tags": [
+                "agents",
+                "ai-pack",
+                "safety"
+            ],
+            "path": [
+                {
+                    "bookId": "05-agents-and-safety",
+                    "audience": "developers",
+                    "chapters": [
+                        "ai-packs",
+                        "agent-call-shape",
+                        "publish-and-secret-safety",
+                        "knowledge-sdk"
+                    ]
+                }
+            ],
+            "alsoSee": [
+                "05-agents-and-safety",
+                "03-cli-sdk-mcp"
+            ]
+        }
+    ]
+};
+export const site = {
+    "product": "xops",
+    "brand": "xops · docs",
+    "brandAccent": "docs",
+    "siteUrl": "https://docs.xops.x12i.com",
+    "knowledgePackage": "@x12i/xops-docs",
+    "footer": "XOPS FIELD GUIDES · OPERATING LAYER",
+    "accent": "oklch(42% 0.09 250)",
+    "accentAlt": "oklch(52% 0.11 35)",
+    "productUrl": "https://github.com/x12i/npm",
+    "nav": [
+        {
+            "label": "Getting started",
+            "href": "/getting-started"
+        },
+        {
+            "label": "Use cases",
+            "href": "/use-cases"
+        },
+        {
+            "label": "Catalog",
+            "href": "/catalog"
+        }
+    ],
+    "footerLinks": [
+        {
+            "label": "Docs home",
+            "href": "/docs"
+        },
+        {
+            "label": "Getting started",
+            "href": "/getting-started"
+        },
+        {
+            "label": "Use cases",
+            "href": "/use-cases"
+        },
+        {
+            "label": "Catalog",
+            "href": "/catalog"
+        },
+        {
+            "label": "Agents/SDK",
+            "href": "/agents"
+        }
+    ]
+};
+export const manifest = {
+    "version": 1,
+    "product": "xops",
+    "site": "https://docs.xops.x12i.com",
+    "knowledgePackage": "@x12i/xops-docs",
+    "roles": [
+        "developers",
+        "builders"
+    ],
+    "books": [
+        {
+            "id": "00-platform-overview",
+            "audiences": [
+                "developers",
+                "builders"
+            ],
+            "md": {
+                "developers": "downloads/books/00-platform-overview/developers.md",
+                "builders": "downloads/books/00-platform-overview/builders.md"
+            },
+            "pdf": {
+                "developers": null,
+                "builders": null
+            },
+            "chapters": {
+                "developers": "downloads/books/00-platform-overview/developers.chapters.json",
+                "builders": "downloads/books/00-platform-overview/builders.chapters.json"
+            }
+        },
+        {
+            "id": "01-install-and-daily",
+            "audiences": [
+                "developers"
+            ],
+            "md": {
+                "developers": "downloads/books/01-install-and-daily/developers.md"
+            },
+            "pdf": {
+                "developers": null
+            },
+            "chapters": {
+                "developers": "downloads/books/01-install-and-daily/developers.chapters.json"
+            }
+        },
+        {
+            "id": "02-release-and-publish",
+            "audiences": [
+                "developers"
+            ],
+            "md": {
+                "developers": "downloads/books/02-release-and-publish/developers.md"
+            },
+            "pdf": {
+                "developers": null
+            },
+            "chapters": {
+                "developers": "downloads/books/02-release-and-publish/developers.chapters.json"
+            }
+        },
+        {
+            "id": "03-cli-sdk-mcp",
+            "audiences": [
+                "developers"
+            ],
+            "md": {
+                "developers": "downloads/books/03-cli-sdk-mcp/developers.md"
+            },
+            "pdf": {
+                "developers": null
+            },
+            "chapters": {
+                "developers": "downloads/books/03-cli-sdk-mcp/developers.chapters.json"
+            }
+        },
+        {
+            "id": "04-ops-and-tools",
+            "audiences": [
+                "builders"
+            ],
+            "md": {
+                "builders": "downloads/books/04-ops-and-tools/builders.md"
+            },
+            "pdf": {
+                "builders": null
+            },
+            "chapters": {
+                "builders": "downloads/books/04-ops-and-tools/builders.chapters.json"
+            }
+        },
+        {
+            "id": "05-agents-and-safety",
+            "audiences": [
+                "developers"
+            ],
+            "md": {
+                "developers": "downloads/books/05-agents-and-safety/developers.md"
+            },
+            "pdf": {
+                "developers": null
+            },
+            "chapters": {
+                "developers": "downloads/books/05-agents-and-safety/developers.chapters.json"
+            }
+        }
+    ],
+    "useCases": [
+        {
+            "id": "orient-xops",
+            "title": "Orient on xops",
+            "md": "downloads/use-cases/orient-xops.md",
+            "path": [
+                {
+                    "bookId": "00-platform-overview",
+                    "audience": "developers",
+                    "chapters": [
+                        "the-mental-model",
+                        "one-contract-three-interfaces",
+                        "what-xops-owns",
+                        "hard-product-rules",
+                        "which-book-next"
+                    ]
+                }
+            ]
+        },
+        {
+            "id": "install-and-doctor",
+            "title": "Install xops and run doctor",
+            "md": "downloads/use-cases/install-and-doctor.md",
+            "path": [
+                {
+                    "bookId": "01-install-and-daily",
+                    "audience": "developers",
+                    "chapters": [
+                        "install-the-cli",
+                        "confirm-on-path",
+                        "run-doctor",
+                        "workspace-install-once"
+                    ]
+                }
+            ]
+        },
+        {
+            "id": "run-a-safe-release",
+            "title": "Run a safe release",
+            "md": "downloads/use-cases/run-a-safe-release.md",
+            "path": [
+                {
+                    "bookId": "02-release-and-publish",
+                    "audience": "developers",
+                    "chapters": [
+                        "discovery-and-order",
+                        "safety-gates",
+                        "publish-and-push",
+                        "undo-and-recovery"
+                    ]
+                }
+            ]
+        },
+        {
+            "id": "wire-sdk-or-mcp",
+            "title": "Wire the SDK or MCP",
+            "md": "downloads/use-cases/wire-sdk-or-mcp.md",
+            "path": [
+                {
+                    "bookId": "03-cli-sdk-mcp",
+                    "audience": "developers",
+                    "chapters": [
+                        "ask-and-passthrough",
+                        "typed-sdk-results",
+                        "mcp-tools-and-resources",
+                        "plan-first-approvals"
+                    ]
+                }
+            ]
+        },
+        {
+            "id": "operate-the-tool-catalog",
+            "title": "Operate the tool catalog",
+            "md": "downloads/use-cases/operate-the-tool-catalog.md",
+            "path": [
+                {
+                    "bookId": "04-ops-and-tools",
+                    "audience": "builders",
+                    "chapters": [
+                        "ops-status",
+                        "recommendations",
+                        "seamless-tools",
+                        "playbooks"
+                    ]
+                }
+            ]
+        },
+        {
+            "id": "brief-a-coding-agent",
+            "title": "Brief a coding agent",
+            "md": "downloads/use-cases/brief-a-coding-agent.md",
+            "path": [
+                {
+                    "bookId": "05-agents-and-safety",
+                    "audience": "developers",
+                    "chapters": [
+                        "ai-packs",
+                        "agent-call-shape",
+                        "publish-and-secret-safety",
+                        "knowledge-sdk"
+                    ]
+                }
+            ]
+        }
+    ]
+};
+export const files = {
+    "downloads/books/00-platform-overview/builders.chapters.json": "[\n  {\n    \"slug\": \"preamble\",\n    \"title\": \"Introduction\",\n    \"level\": 2,\n    \"order\": 0\n  },\n  {\n    \"slug\": \"the-mental-model\",\n    \"title\": \"The mental model\",\n    \"level\": 2,\n    \"order\": 1\n  },\n  {\n    \"slug\": \"one-contract-three-interfaces\",\n    \"title\": \"One contract, three interfaces\",\n    \"level\": 2,\n    \"order\": 2\n  },\n  {\n    \"slug\": \"what-operators-own-day-to-day\",\n    \"title\": \"What operators own day to day\",\n    \"level\": 2,\n    \"order\": 3\n  },\n  {\n    \"slug\": \"hard-product-rules\",\n    \"title\": \"Hard product rules\",\n    \"level\": 2,\n    \"order\": 4\n  },\n  {\n    \"slug\": \"which-book-next\",\n    \"title\": \"Which book next\",\n    \"level\": 2,\n    \"order\": 5\n  }\n]",
+    "downloads/books/00-platform-overview/builders.md": "# xops Platform Overview — Operators\n\n**Audience:** People who bootstrap PATH, CI, and the operating contract.  \n**Twin:** [Developers version](../developers/BOOK.md)  \n**Package:** `@x12i/xops` · **Hard rules:** [HARD-RULES.md](../../HARD-RULES.md)\n\n---\n\n## The mental model\n\nOperators keep the **operating surface** healthy so developers and agents can trust it.\n\nThat means: the CLI is installed under the correct scoped name (`@x12i/xops`), shims are on `PATH`, `xops doctor` is green, workspace install policy is understood, and the tools catalog reflects what the repo can actually run.\n\n---\n\n## One contract, three interfaces\n\nHumans use the CLI. CI and platforms use the SDK. Coding agents use MCP. You do not run a separate “agent ops stack” — you expose the same xops contract with the right profile and approval policy.\n\n---\n\n## What operators own day to day\n\n| Concern | Command / surface |\n|---|---|\n| Install health | `xops doctor` |\n| Repo operability | `xops ops status` |\n| Missing capabilities | `xops recommendations` |\n| Repeated workflows | `xops playbooks …` |\n| Agent hosts | `xops mcp` / `xops agent mcp` profiles |\n\n---\n\n## Hard product rules\n\nSame invariants as developers — especially: seamless tools only when catalog-marked; never force privileged installs; publish gates stay on. See [HARD-RULES.md](../../HARD-RULES.md).\n\n---\n\n## Which book next\n\n| Goal | Open |\n|---|---|\n| Install + PATH | [Install and Daily CLI](../../01-install-and-daily/developers/BOOK.md) |\n| Catalog / playbooks | [Ops and Tools](../../04-ops-and-tools/builders/BOOK.md) |\n| Agent safety | [Agents and Safety](../../05-agents-and-safety/developers/BOOK.md) |\n",
+    "downloads/books/00-platform-overview/developers.chapters.json": "[\n  {\n    \"slug\": \"preamble\",\n    \"title\": \"Introduction\",\n    \"level\": 2,\n    \"order\": 0\n  },\n  {\n    \"slug\": \"the-mental-model\",\n    \"title\": \"The mental model\",\n    \"level\": 2,\n    \"order\": 1\n  },\n  {\n    \"slug\": \"one-contract-three-interfaces\",\n    \"title\": \"One contract, three interfaces\",\n    \"level\": 2,\n    \"order\": 2\n  },\n  {\n    \"slug\": \"what-xops-owns\",\n    \"title\": \"What xops owns\",\n    \"level\": 2,\n    \"order\": 3\n  },\n  {\n    \"slug\": \"hard-product-rules\",\n    \"title\": \"Hard product rules\",\n    \"level\": 2,\n    \"order\": 4\n  },\n  {\n    \"slug\": \"which-book-next\",\n    \"title\": \"Which book next\",\n    \"level\": 2,\n    \"order\": 5\n  }\n]",
+    "downloads/books/00-platform-overview/developers.md": "# xops Platform Overview — Developers\n\n**Audience:** Engineers and coding agents who run xops every day.  \n**Twin:** [Operators version](../builders/BOOK.md)  \n**Package:** `@x12i/xops` · **Hard rules:** [HARD-RULES.md](../../HARD-RULES.md)\n\n---\n\n## The mental model\n\n`npm` and `git` are not the problem. The problem is everything around them.\n\nxops is the **operating layer** for Node.js repositories. It detects repository state, routes work to the right native owner, plans risky actions, executes approved workflows, and reports what happened.\n\n> Native tools own their domains.  \n> xops owns the workflow between them.\n\nxops does not replace npm, git, scanners, task runners, or code agents. It makes them usable as one safe operating surface.\n\n---\n\n## One contract, three interfaces\n\n| Interface | Caller | Shape |\n|---|---|---|\n| CLI | Humans | Readable prompts, recovery hints, summarized reports |\n| SDK | Scripts, CI, platforms | Typed `XopsRunResult`-style objects |\n| MCP | IDE / autonomous agents | Tools + resources; plan-first approvals |\n\n```bash\nxops doctor\nxops ask \"is this package publishable?\"\nxops mcp --stdio\n```\n\n```ts\nimport { runValidate, runRelease } from \"@x12i/xops\";\n```\n\nSame engine. Different presentation and safeguards per caller.\n\n---\n\n## What xops owns\n\n- Discovery of packages, workspaces, and dependency order\n- Install / validate / build health (including optional native binding remediations)\n- Release, publish, push, and undo with safety gates\n- Ask / passthrough over npm and git\n- Ops status, recommendations, seamless tool bootstrap\n- Operational playbooks (`kill-port`, `dev-stack`, `publish-chain`, …)\n- Agent context packs and MCP tool surfaces\n\nWhat it does **not** own: being a second package manager, unrestricted shell as primary interface, or inventing domain tools that already exist.\n\n---\n\n## Hard product rules\n\nSee [HARD-RULES.md](../../HARD-RULES.md). Short list: native owners stay native; plan before risk; workspace install once at root; never pin platform bindings into consumer manifests; secrets stay out of packs.\n\n---\n\n## Which book next\n\n| Goal | Open |\n|---|---|\n| Get on PATH / doctor | [Install and Daily CLI](../../01-install-and-daily/developers/BOOK.md) |\n| Publish safely | [Release and Publish](../../02-release-and-publish/developers/BOOK.md) |\n| Automate / agents | [CLI, SDK, and MCP](../../03-cli-sdk-mcp/developers/BOOK.md) |\n| Tool catalog / playbooks | [Ops and Tools](../../04-ops-and-tools/builders/BOOK.md) (Operators) |\n| AI packs + safety | [Agents and Safety](../../05-agents-and-safety/developers/BOOK.md) |\n",
+    "downloads/books/01-install-and-daily/developers.chapters.json": "[\n  {\n    \"slug\": \"preamble\",\n    \"title\": \"Introduction\",\n    \"level\": 2,\n    \"order\": 0\n  },\n  {\n    \"slug\": \"install-the-cli\",\n    \"title\": \"Install the CLI\",\n    \"level\": 2,\n    \"order\": 1\n  },\n  {\n    \"slug\": \"confirm-on-path\",\n    \"title\": \"Confirm on PATH\",\n    \"level\": 2,\n    \"order\": 2\n  },\n  {\n    \"slug\": \"run-doctor\",\n    \"title\": \"Run doctor\",\n    \"level\": 2,\n    \"order\": 3\n  },\n  {\n    \"slug\": \"workspace-install-once\",\n    \"title\": \"Workspace install once\",\n    \"level\": 2,\n    \"order\": 4\n  },\n  {\n    \"slug\": \"daily-command-surface\",\n    \"title\": \"Daily command surface\",\n    \"level\": 2,\n    \"order\": 5\n  }\n]",
+    "downloads/books/01-install-and-daily/developers.md": "# Install and Daily CLI — Developers\n\n**Audience:** Anyone putting xops on a machine and using it as the daily command.  \n**Package:** `@x12i/xops` · **CLI:** `xops` (aliases: `xnpm`, `xgit`, …)\n\n---\n\n## Install the CLI\n\nThe product command is `xops`. The **npm package name** is `@x12i/xops`.\n\n```bash\n# Windows\nnpm install -g @x12i/xops\n\n# macOS / Linux\nsudo npm install -g @x12i/xops\n```\n\nDo **not** confuse `xops install` (run the CLI against a repo) with `npm install -g @x12i/xops` (install the CLI itself).\n\nUntil PATH is fixed, `npx @x12i/xops doctor` still works.\n\n---\n\n## Confirm on PATH\n\nAfter install, npm should create launchers for `xops` and its aliases.\n\n```bash\nnpm list -g @x12i/xops\nnpm prefix -g\nwhich xops   # or: Get-Command xops on PowerShell\n```\n\nIf the shim is missing, reinstall the scoped package. If the shim exists but the shell cannot find it, fix `PATH` / npm prefix (doctor can help).\n\n---\n\n## Run doctor\n\n```bash\nxops doctor\nnpx @x12i/xops doctor\n```\n\nDoctor checks Node, npm, git, PATH, npm prefix, and common Windows / Git Bash issues. Prefer it before any other troubleshooting.\n\n---\n\n## Workspace install once\n\nIn npm workspaces monorepos, the **supported** path is a single install at the workspace root:\n\n```bash\n# from workspace / git root\nxops install\n```\n\n`xops --here` / cwd-in-package scopes *xops discovery*, not a second npm install strategy. Prefer one root `package-lock.json`; nested member locks are hygiene debt.\n\nEmergency leaf bypass (`npm i --no-workspaces`) can unblock Windows arborist failures, but is not the supported parallel-tree strategy — reconcile back to a single root tree.\n\n---\n\n## Daily command surface\n\nExamples of the daily loop:\n\n```bash\nxops validate\nxops validate --build\nxops ask \"what packages changed?\"\nxops run build          # passthrough\nxops status             # git passthrough\nxops release --dry-run\n```\n\nUse `xops ask` for plain English; use native subcommands when you already know the verb. Set `XOPS_AUTO_INSTALL_TOOLS=0` to disable seamless tool auto-install.\n",
+    "downloads/books/02-release-and-publish/developers.chapters.json": "[\n  {\n    \"slug\": \"preamble\",\n    \"title\": \"Introduction\",\n    \"level\": 2,\n    \"order\": 0\n  },\n  {\n    \"slug\": \"discovery-and-order\",\n    \"title\": \"Discovery and order\",\n    \"level\": 2,\n    \"order\": 1\n  },\n  {\n    \"slug\": \"safety-gates\",\n    \"title\": \"Safety gates\",\n    \"level\": 2,\n    \"order\": 2\n  },\n  {\n    \"slug\": \"publish-and-push\",\n    \"title\": \"Publish and push\",\n    \"level\": 2,\n    \"order\": 3\n  },\n  {\n    \"slug\": \"undo-and-recovery\",\n    \"title\": \"Undo and recovery\",\n    \"level\": 2,\n    \"order\": 4\n  }\n]",
+    "downloads/books/02-release-and-publish/developers.md": "# Release and Publish — Developers\n\n**Audience:** Humans and agents shipping packages with xops.  \n**Related:** [Agents and Safety](../../05-agents-and-safety/developers/BOOK.md)\n\n---\n\n## Discovery and order\n\nxops discovers packages in the repo (single package, packages root, or workspaces), builds a dependency-aware publish order, and plans the release before mutating anything.\n\n```bash\nxops release --dry-run\nxops map\n```\n\nAgents and CI should prefer structured / JSON outputs and dry-run plans over scraping terminal prose.\n\n---\n\n## Safety gates\n\nBefore publish, xops applies safety checks that include (among others):\n\n- gitignore rules for `.env*` (and related patterns)\n- pack validation so secrets and junk do not ship in the tarball\n- registry / version consistency expectations for the planned packages\n\nIf a gate fails, fix the reported issue — do not bypass with force flags unless you explicitly understand the risk.\n\n---\n\n## Publish and push\n\nTypical human path:\n\n```bash\nxops release\n# or more explicit publish/push flows from the CLI once the plan is approved\n```\n\nTypical agent path: call the SDK / MCP release tools with an explicit approval profile. Risky operations return `approval-required` instead of blocking forever or publishing silently.\n\n---\n\n## Undo and recovery\n\nWhen a release step needs reversal, use the product undo path rather than ad-hoc git surgery:\n\n```bash\nxops undo\n```\n\nFor install/tree corruption, prefer root reinstall hygiene (`node_modules` + lock policy) and `xops validate` / `xops validate --build` after recovery. `xops clean` clears xops state — it is not a full `node_modules` wipe unless documented otherwise.\n",
+    "downloads/books/03-cli-sdk-mcp/developers.chapters.json": "[\n  {\n    \"slug\": \"preamble\",\n    \"title\": \"Introduction\",\n    \"level\": 2,\n    \"order\": 0\n  },\n  {\n    \"slug\": \"ask-and-passthrough\",\n    \"title\": \"Ask and passthrough\",\n    \"level\": 2,\n    \"order\": 1\n  },\n  {\n    \"slug\": \"typed-sdk-results\",\n    \"title\": \"Typed SDK results\",\n    \"level\": 2,\n    \"order\": 2\n  },\n  {\n    \"slug\": \"mcp-tools-and-resources\",\n    \"title\": \"MCP tools and resources\",\n    \"level\": 2,\n    \"order\": 3\n  },\n  {\n    \"slug\": \"plan-first-approvals\",\n    \"title\": \"Plan-first approvals\",\n    \"level\": 2,\n    \"order\": 4\n  }\n]",
+    "downloads/books/03-cli-sdk-mcp/developers.md": "# CLI, SDK, and MCP — Developers\n\n**Audience:** Integrators wiring xops into scripts, CI, and agent hosts.  \n**Package exports:** `@x12i/xops`, `@x12i/xops/mcp`, `@x12i/xops/playbooks`\n\n---\n\n## Ask and passthrough\n\n`xops ask` resolves plain-English requests to automation, npm/pnpm, or git. Native project package-manager and git subcommands also pass through (for example `xops run build`, `xops status`).\n\n```bash\nxops ask \"show parallel branches\"\nxops ask \"is this package publishable?\"\n```\n\nPrefer ask when the caller does not know the exact verb; prefer explicit commands when the verb is known.\n\n---\n\n## Typed SDK results\n\n```ts\nimport {\n  detectRepository,\n  runCheck,\n  runAskPlan,\n  runValidate,\n  runRelease,\n  runAiPack,\n  listPlaybooks,\n  planPlaybook,\n  runPlaybook,\n} from \"@x12i/xops\";\n```\n\nSDK functions return structured results with issues, tool runs, recommendations, reports, repository context, duration, and stable status values. Agents should consume JSON — not scrape CLI text.\n\n---\n\n## MCP tools and resources\n\n```bash\nxops mcp --stdio\nxops mcp start --stdio\nxops agent mcp --stdio\nxops agent mcp --http --port 7331 --profile readonly\nxops mcp --list-tools\nxops mcp --list-resources\n```\n\nTools cover `xops.repo.*`, `xops.pkg.*`, `xops.deps.*`, `xops.security.*`, `xops.release.*`, `xops.ai.*`, `xops.net.*`, `xops.system.*`, `xops.node.*`, `xops.tools.*`, `xops.reports.*`, `xops.playbooks.*`, and `xops.plan.*`.\n\nResources include `xops://repo/context`, `xops://tools/catalog`, `xops://playbooks/catalog`, `xops://reports/latest`, and related URIs.\n\nMCP does **not** expose unrestricted shell as its primary interface.\n\n---\n\n## Plan-first approvals\n\nRisky MCP operations (mutations, publish/release, tool installation, network exposure scans) return structured `approval-required` or `authorization-required` unless the caller supplies explicit approval inputs and a profile that allows the action.\n\nSystem-native tools such as Nmap or Trivy are not silently installed; MCP returns missing-tool / setup guidance the same way the CLI agent mode does.\n",
+    "downloads/books/04-ops-and-tools/builders.chapters.json": "[\n  {\n    \"slug\": \"preamble\",\n    \"title\": \"Introduction\",\n    \"level\": 2,\n    \"order\": 0\n  },\n  {\n    \"slug\": \"ops-status\",\n    \"title\": \"Ops status\",\n    \"level\": 2,\n    \"order\": 1\n  },\n  {\n    \"slug\": \"recommendations\",\n    \"title\": \"Recommendations\",\n    \"level\": 2,\n    \"order\": 2\n  },\n  {\n    \"slug\": \"seamless-tools\",\n    \"title\": \"Seamless tools\",\n    \"level\": 2,\n    \"order\": 3\n  },\n  {\n    \"slug\": \"playbooks\",\n    \"title\": \"Playbooks\",\n    \"level\": 2,\n    \"order\": 4\n  }\n]",
+    "downloads/books/04-ops-and-tools/builders.md": "# Ops and Tools — Operators\n\n**Audience:** People who keep the operating contract honest across tools and hosts.  \n**Related:** [Platform Overview](../../00-platform-overview/builders/BOOK.md)\n\n---\n\n## Ops status\n\n```bash\nxops ops status\n```\n\nOps status reports what is operable in the current repository: which supported tools are present, which capabilities are available, and where the operating surface is incomplete.\n\nTreat this as the inventory view before recommending changes.\n\n---\n\n## Recommendations\n\n```bash\nxops recommendations\nxops recommendations apply\n```\n\nRecommendations are evidence-based. xops should not invent tools the repo does not need. Apply only after reviewing the plan — especially for non-seamless setup that needs approval.\n\n---\n\n## Seamless tools\n\nWhen a missing tool is catalog-marked as seamless (user-space install, no password, no account login, no secret prompt, no privileged write), xops may bootstrap it behind the scenes during ask / ops flows.\n\n```bash\n# disable seamless auto-install\nexport XOPS_AUTO_INSTALL_TOOLS=0\n```\n\nNon-seamless tools always require explicit approval or operator setup.\n\n---\n\n## Playbooks\n\nOperational playbooks cover repeated repository actions with parameters, planning, risk metadata, and run reports.\n\n```bash\nxops playbooks list\nxops playbooks status --json\nxops playbooks init kill-port\nxops playbooks plan kill-port --port 3000 --json\nxops playbooks run kill-port --port 3000 --dry-run\nxops playbooks run dev-stack --stack jobs --port 3000\nxops playbooks run publish-chain --package @scope/app\n```\n\nBuilt-in catalog includes `kill-port`, `dev-stack`, `publish-chain`, and `publish-all`. Prefer playbooks over ad-hoc shell scripts when the action is already modeled.\n",
+    "downloads/books/05-agents-and-safety/developers.chapters.json": "[\n  {\n    \"slug\": \"preamble\",\n    \"title\": \"Introduction\",\n    \"level\": 2,\n    \"order\": 0\n  },\n  {\n    \"slug\": \"ai-packs\",\n    \"title\": \"AI packs\",\n    \"level\": 2,\n    \"order\": 1\n  },\n  {\n    \"slug\": \"agent-call-shape\",\n    \"title\": \"Agent call shape\",\n    \"level\": 2,\n    \"order\": 2\n  },\n  {\n    \"slug\": \"publish-and-secret-safety\",\n    \"title\": \"Publish and secret safety\",\n    \"level\": 2,\n    \"order\": 3\n  },\n  {\n    \"slug\": \"knowledge-sdk\",\n    \"title\": \"Knowledge SDK\",\n    \"level\": 2,\n    \"order\": 4\n  }\n]",
+    "downloads/books/05-agents-and-safety/developers.md": "# Agents and Safety — Developers\n\n**Audience:** Humans briefing agents, and agents consuming xops safely.  \n**Knowledge package:** `@x12i/xops-docs` (devDependency only)\n\n---\n\n## AI packs\n\n```bash\nxops ai pack\n# or SDK: runAiPack(...)\n```\n\nAI packs assemble repository context for coding agents. Prefer the structured pack over dumping the whole monorepo into a prompt. Pair packs with this knowledge SDK for product how-to, and with MCP/SDK for runtime actions.\n\n---\n\n## Agent call shape\n\nAgents should:\n\n1. Read `agent-manifest.json` or call `@x12i/xops-docs` helpers for documentation.\n2. Call `@x12i/xops` SDK or MCP tools for work (validate, release plan, playbooks).\n3. Honor `approval-required` — never invent a silent publish path.\n4. Prefer JSON / structured results and stable exit codes.\n\nHumans get prose and recovery hints. Agents get deterministic plans and low-noise output.\n\n---\n\n## Publish and secret safety\n\nxops appends required gitignore rules for `.env` patterns and fails publish if `.env*` would ship in the tarball. Docs and agent packs must never print secret values.\n\nAlready-tracked secrets are not magically untracked — use hooks/CI if you need commit-time enforcement beyond pack checks.\n\n---\n\n## Knowledge SDK\n\n```bash\nnpm i -D @x12i/xops-docs\n```\n\n```ts\nimport { xopsDocs } from \"@x12i/xops-docs\";\n\nxopsDocs.listUseCases({ audience: \"developers\", tag: \"release\" });\nxopsDocs.getUseCaseMarkdown(\"run-a-safe-release\");\nxopsDocs.getBookMarkdown(\"00-platform-overview\", \"developers\");\nxopsDocs.manifest();\n```\n\nInstall as a **devDependency** only. Runtime operate uses `@x12i/xops` / MCP — not the docs package.\n",
+    "downloads/use-cases/brief-a-coding-agent.md": "# Brief a coding agent\n\n> **Use case id:** `brief-a-coding-agent`\n> **Goal:** Generate AI context packs and teach an agent to use xops safely.\n> **Audiences:** developers\n> **Tags:** agents, ai-pack, safety\n\n## Reading path\n\n1. **Agents and Safety** (developers) → chapters: `ai-packs`, `agent-call-shape`, `publish-and-secret-safety`, `knowledge-sdk`\n\n## From: Agents and Safety — AI packs\n\n```bash\nxops ai pack\n# or SDK: runAiPack(...)\n```\n\nAI packs assemble repository context for coding agents. Prefer the structured pack over dumping the whole monorepo into a prompt. Pair packs with this knowledge SDK for product how-to, and with MCP/SDK for runtime actions.\n\n---\n\n## From: Agents and Safety — Agent call shape\n\nAgents should:\n\n1. Read `agent-manifest.json` or call `@x12i/xops-docs` helpers for documentation.\n2. Call `@x12i/xops` SDK or MCP tools for work (validate, release plan, playbooks).\n3. Honor `approval-required` — never invent a silent publish path.\n4. Prefer JSON / structured results and stable exit codes.\n\nHumans get prose and recovery hints. Agents get deterministic plans and low-noise output.\n\n---\n\n## From: Agents and Safety — Publish and secret safety\n\nxops appends required gitignore rules for `.env` patterns and fails publish if `.env*` would ship in the tarball. Docs and agent packs must never print secret values.\n\nAlready-tracked secrets are not magically untracked — use hooks/CI if you need commit-time enforcement beyond pack checks.\n\n---\n\n## From: Agents and Safety — Knowledge SDK\n\n```bash\nnpm i -D @x12i/xops-docs\n```\n\n```ts\nimport { xopsDocs } from \"@x12i/xops-docs\";\n\nxopsDocs.listUseCases({ audience: \"developers\", tag: \"release\" });\nxopsDocs.getUseCaseMarkdown(\"run-a-safe-release\");\nxopsDocs.getBookMarkdown(\"00-platform-overview\", \"developers\");\nxopsDocs.manifest();\n```\n\nInstall as a **devDependency** only. Runtime operate uses `@x12i/xops` / MCP — not the docs package.\n\n## Also see\n\n- **Agents and Safety** (`05-agents-and-safety`) — AI context packs, safety gates, and how agents should call xops without scraping terminals.\n- **CLI, SDK, and MCP** (`03-cli-sdk-mcp`) — Ask, typed SDK results, MCP tools/resources, and plan-first approvals for agents.\n\n---\n\n_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._\n",
+    "downloads/use-cases/install-and-doctor.md": "# Install xops and run doctor\n\n> **Use case id:** `install-and-doctor`\n> **Goal:** Get @x12i/xops on PATH, confirm shims, and clear doctor checks.\n> **Audiences:** developers, builders\n> **Tags:** install, doctor\n\n## Reading path\n\n1. **Install and Daily CLI** (developers) → chapters: `install-the-cli`, `confirm-on-path`, `run-doctor`, `workspace-install-once`\n\n## From: Install and Daily CLI — Install the CLI\n\nThe product command is `xops`. The **npm package name** is `@x12i/xops`.\n\n```bash\n# Windows\nnpm install -g @x12i/xops\n\n# macOS / Linux\nsudo npm install -g @x12i/xops\n```\n\nDo **not** confuse `xops install` (run the CLI against a repo) with `npm install -g @x12i/xops` (install the CLI itself).\n\nUntil PATH is fixed, `npx @x12i/xops doctor` still works.\n\n---\n\n## From: Install and Daily CLI — Confirm on PATH\n\nAfter install, npm should create launchers for `xops` and its aliases.\n\n```bash\nnpm list -g @x12i/xops\nnpm prefix -g\nwhich xops   # or: Get-Command xops on PowerShell\n```\n\nIf the shim is missing, reinstall the scoped package. If the shim exists but the shell cannot find it, fix `PATH` / npm prefix (doctor can help).\n\n---\n\n## From: Install and Daily CLI — Run doctor\n\n```bash\nxops doctor\nnpx @x12i/xops doctor\n```\n\nDoctor checks Node, npm, git, PATH, npm prefix, and common Windows / Git Bash issues. Prefer it before any other troubleshooting.\n\n---\n\n## From: Install and Daily CLI — Workspace install once\n\nIn npm workspaces monorepos, the **supported** path is a single install at the workspace root:\n\n```bash\n# from workspace / git root\nxops install\n```\n\n`xops --here` / cwd-in-package scopes *xops discovery*, not a second npm install strategy. Prefer one root `package-lock.json`; nested member locks are hygiene debt.\n\nEmergency leaf bypass (`npm i --no-workspaces`) can unblock Windows arborist failures, but is not the supported parallel-tree strategy — reconcile back to a single root tree.\n\n---\n\n## Also see\n\n- **Install and Daily CLI** (`01-install-and-daily`) — Global install, doctor, workspace install-once, and the daily command surface.\n- **Ops and Tools** (`04-ops-and-tools`) — ops status, recommendations, seamless tools, and operational playbooks.\n\n---\n\n_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._\n",
+    "downloads/use-cases/operate-the-tool-catalog.md": "# Operate the tool catalog\n\n> **Use case id:** `operate-the-tool-catalog`\n> **Goal:** Read ops status, apply recommendations, and run playbooks without inventing a second ops stack.\n> **Audiences:** builders\n> **Tags:** ops, tools, playbooks\n\n## Reading path\n\n1. **Ops and Tools** (builders) → chapters: `ops-status`, `recommendations`, `seamless-tools`, `playbooks`\n\n## From: Ops and Tools — Ops status\n\n```bash\nxops ops status\n```\n\nOps status reports what is operable in the current repository: which supported tools are present, which capabilities are available, and where the operating surface is incomplete.\n\nTreat this as the inventory view before recommending changes.\n\n---\n\n## From: Ops and Tools — Recommendations\n\n```bash\nxops recommendations\nxops recommendations apply\n```\n\nRecommendations are evidence-based. xops should not invent tools the repo does not need. Apply only after reviewing the plan — especially for non-seamless setup that needs approval.\n\n---\n\n## From: Ops and Tools — Seamless tools\n\nWhen a missing tool is catalog-marked as seamless (user-space install, no password, no account login, no secret prompt, no privileged write), xops may bootstrap it behind the scenes during ask / ops flows.\n\n```bash\n# disable seamless auto-install\nexport XOPS_AUTO_INSTALL_TOOLS=0\n```\n\nNon-seamless tools always require explicit approval or operator setup.\n\n---\n\n## From: Ops and Tools — Playbooks\n\nOperational playbooks cover repeated repository actions with parameters, planning, risk metadata, and run reports.\n\n```bash\nxops playbooks list\nxops playbooks status --json\nxops playbooks init kill-port\nxops playbooks plan kill-port --port 3000 --json\nxops playbooks run kill-port --port 3000 --dry-run\nxops playbooks run dev-stack --stack jobs --port 3000\nxops playbooks run publish-chain --package @scope/app\n```\n\nBuilt-in catalog includes `kill-port`, `dev-stack`, `publish-chain`, and `publish-all`. Prefer playbooks over ad-hoc shell scripts when the action is already modeled.\n\n## Also see\n\n- **Ops and Tools** (`04-ops-and-tools`) — ops status, recommendations, seamless tools, and operational playbooks.\n- **Platform Overview** (`00-platform-overview`) — What xops is, the operating contract, three interfaces, and which book to open next.\n\n---\n\n_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._\n",
+    "downloads/use-cases/orient-xops.md": "# Orient on xops\n\n> **Use case id:** `orient-xops`\n> **Goal:** Understand the operating layer, three interfaces, and which book to open next.\n> **Audiences:** developers, builders\n> **Tags:** platform, start-here\n\n## Reading path\n\n1. **Platform Overview** (developers) → chapters: `the-mental-model`, `one-contract-three-interfaces`, `what-xops-owns`, `hard-product-rules`, `which-book-next`\n\n## From: Platform Overview — The mental model\n\n`npm` and `git` are not the problem. The problem is everything around them.\n\nxops is the **operating layer** for Node.js repositories. It detects repository state, routes work to the right native owner, plans risky actions, executes approved workflows, and reports what happened.\n\n> Native tools own their domains.  \n> xops owns the workflow between them.\n\nxops does not replace npm, git, scanners, task runners, or code agents. It makes them usable as one safe operating surface.\n\n---\n\n## From: Platform Overview — One contract, three interfaces\n\n| Interface | Caller | Shape |\n|---|---|---|\n| CLI | Humans | Readable prompts, recovery hints, summarized reports |\n| SDK | Scripts, CI, platforms | Typed `XopsRunResult`-style objects |\n| MCP | IDE / autonomous agents | Tools + resources; plan-first approvals |\n\n```bash\nxops doctor\nxops ask \"is this package publishable?\"\nxops mcp --stdio\n```\n\n```ts\nimport { runValidate, runRelease } from \"@x12i/xops\";\n```\n\nSame engine. Different presentation and safeguards per caller.\n\n---\n\n## From: Platform Overview — What xops owns\n\n- Discovery of packages, workspaces, and dependency order\n- Install / validate / build health (including optional native binding remediations)\n- Release, publish, push, and undo with safety gates\n- Ask / passthrough over npm and git\n- Ops status, recommendations, seamless tool bootstrap\n- Operational playbooks (`kill-port`, `dev-stack`, `publish-chain`, …)\n- Agent context packs and MCP tool surfaces\n\nWhat it does **not** own: being a second package manager, unrestricted shell as primary interface, or inventing domain tools that already exist.\n\n---\n\n## From: Platform Overview — Hard product rules\n\nSee [HARD-RULES.md](../../HARD-RULES.md). Short list: native owners stay native; plan before risk; workspace install once at root; never pin platform bindings into consumer manifests; secrets stay out of packs.\n\n---\n\n## From: Platform Overview — Which book next\n\n| Goal | Open |\n|---|---|\n| Get on PATH / doctor | [Install and Daily CLI](../../01-install-and-daily/developers/BOOK.md) |\n| Publish safely | [Release and Publish](../../02-release-and-publish/developers/BOOK.md) |\n| Automate / agents | [CLI, SDK, and MCP](../../03-cli-sdk-mcp/developers/BOOK.md) |\n| Tool catalog / playbooks | [Ops and Tools](../../04-ops-and-tools/builders/BOOK.md) (Operators) |\n| AI packs + safety | [Agents and Safety](../../05-agents-and-safety/developers/BOOK.md) |\n\n## Also see\n\n- **Platform Overview** (`00-platform-overview`) — What xops is, the operating contract, three interfaces, and which book to open next.\n\n---\n\n_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._\n",
+    "downloads/use-cases/run-a-safe-release.md": "# Run a safe release\n\n> **Use case id:** `run-a-safe-release`\n> **Goal:** Plan, approve, publish, and undo a monorepo or single-package release.\n> **Audiences:** developers\n> **Tags:** release, publish\n\n## Reading path\n\n1. **Release and Publish** (developers) → chapters: `discovery-and-order`, `safety-gates`, `publish-and-push`, `undo-and-recovery`\n\n## From: Release and Publish — Discovery and order\n\nxops discovers packages in the repo (single package, packages root, or workspaces), builds a dependency-aware publish order, and plans the release before mutating anything.\n\n```bash\nxops release --dry-run\nxops map\n```\n\nAgents and CI should prefer structured / JSON outputs and dry-run plans over scraping terminal prose.\n\n---\n\n## From: Release and Publish — Safety gates\n\nBefore publish, xops applies safety checks that include (among others):\n\n- gitignore rules for `.env*` (and related patterns)\n- pack validation so secrets and junk do not ship in the tarball\n- registry / version consistency expectations for the planned packages\n\nIf a gate fails, fix the reported issue — do not bypass with force flags unless you explicitly understand the risk.\n\n---\n\n## From: Release and Publish — Publish and push\n\nTypical human path:\n\n```bash\nxops release\n# or more explicit publish/push flows from the CLI once the plan is approved\n```\n\nTypical agent path: call the SDK / MCP release tools with an explicit approval profile. Risky operations return `approval-required` instead of blocking forever or publishing silently.\n\n---\n\n## From: Release and Publish — Undo and recovery\n\nWhen a release step needs reversal, use the product undo path rather than ad-hoc git surgery:\n\n```bash\nxops undo\n```\n\nFor install/tree corruption, prefer root reinstall hygiene (`node_modules` + lock policy) and `xops validate` / `xops validate --build` after recovery. `xops clean` clears xops state — it is not a full `node_modules` wipe unless documented otherwise.\n\n## Also see\n\n- **Release and Publish** (`02-release-and-publish`) — Discovery, dependency order, safety, publish, push, and undo for humans and agents.\n- **Agents and Safety** (`05-agents-and-safety`) — AI context packs, safety gates, and how agents should call xops without scraping terminals.\n\n---\n\n_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._\n",
+    "downloads/use-cases/wire-sdk-or-mcp.md": "# Wire the SDK or MCP\n\n> **Use case id:** `wire-sdk-or-mcp`\n> **Goal:** Call the same operating layer from TypeScript or an MCP host with plan-first approvals.\n> **Audiences:** developers\n> **Tags:** sdk, mcp, agents\n\n## Reading path\n\n1. **CLI, SDK, and MCP** (developers) → chapters: `ask-and-passthrough`, `typed-sdk-results`, `mcp-tools-and-resources`, `plan-first-approvals`\n\n## From: CLI, SDK, and MCP — Ask and passthrough\n\n`xops ask` resolves plain-English requests to automation, npm/pnpm, or git. Native project package-manager and git subcommands also pass through (for example `xops run build`, `xops status`).\n\n```bash\nxops ask \"show parallel branches\"\nxops ask \"is this package publishable?\"\n```\n\nPrefer ask when the caller does not know the exact verb; prefer explicit commands when the verb is known.\n\n---\n\n## From: CLI, SDK, and MCP — Typed SDK results\n\n```ts\nimport {\n  detectRepository,\n  runCheck,\n  runAskPlan,\n  runValidate,\n  runRelease,\n  runAiPack,\n  listPlaybooks,\n  planPlaybook,\n  runPlaybook,\n} from \"@x12i/xops\";\n```\n\nSDK functions return structured results with issues, tool runs, recommendations, reports, repository context, duration, and stable status values. Agents should consume JSON — not scrape CLI text.\n\n---\n\n## From: CLI, SDK, and MCP — MCP tools and resources\n\n```bash\nxops mcp --stdio\nxops mcp start --stdio\nxops agent mcp --stdio\nxops agent mcp --http --port 7331 --profile readonly\nxops mcp --list-tools\nxops mcp --list-resources\n```\n\nTools cover `xops.repo.*`, `xops.pkg.*`, `xops.deps.*`, `xops.security.*`, `xops.release.*`, `xops.ai.*`, `xops.net.*`, `xops.system.*`, `xops.node.*`, `xops.tools.*`, `xops.reports.*`, `xops.playbooks.*`, and `xops.plan.*`.\n\nResources include `xops://repo/context`, `xops://tools/catalog`, `xops://playbooks/catalog`, `xops://reports/latest`, and related URIs.\n\nMCP does **not** expose unrestricted shell as its primary interface.\n\n---\n\n## From: CLI, SDK, and MCP — Plan-first approvals\n\nRisky MCP operations (mutations, publish/release, tool installation, network exposure scans) return structured `approval-required` or `authorization-required` unless the caller supplies explicit approval inputs and a profile that allows the action.\n\nSystem-native tools such as Nmap or Trivy are not silently installed; MCP returns missing-tool / setup guidance the same way the CLI agent mode does.\n\n## Also see\n\n- **CLI, SDK, and MCP** (`03-cli-sdk-mcp`) — Ask, typed SDK results, MCP tools/resources, and plan-first approvals for agents.\n- **Agents and Safety** (`05-agents-and-safety`) — AI context packs, safety gates, and how agents should call xops without scraping terminals.\n\n---\n\n_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._\n",
+    "catalog.json": "{\"roles\":[{\"id\":\"developers\",\"label\":\"Developers\",\"tagline\":\"Run xops every day\",\"description\":\"Humans and coding agents who install, release, ask, and operate Node.js repositories through xops.\"},{\"id\":\"builders\",\"label\":\"Operators\",\"tagline\":\"Set up PATH, CI, and the operating contract\",\"description\":\"People who bootstrap the CLI, wire CI/agent hosts, and keep doctor/ops status green.\"}],\"families\":[{\"id\":\"xops\",\"name\":\"xops\",\"tagline\":\"The operating layer for Node.js repositories.\",\"description\":\"Detects repo state, routes work to native owners, plans risky actions, executes approved workflows, and reports what happened — via CLI, SDK, and MCP.\",\"color\":\"#1a2f45\"}],\"books\":[{\"id\":\"00-platform-overview\",\"familyId\":\"xops\",\"audiences\":[\"developers\",\"builders\"],\"status\":\"available\",\"kicker\":\"CASE FILE · XOPS-00\",\"title\":\"Platform Overview\",\"subtitle\":\"Mental model and surfaces\",\"blurb\":\"What xops is, the operating contract, three interfaces, and which book to open next.\",\"tags\":[\"platform\",\"start-here\"],\"color\":\"#1a2f45\",\"dir\":\"00-platform-overview\"},{\"id\":\"01-install-and-daily\",\"familyId\":\"xops\",\"audiences\":[\"developers\"],\"status\":\"available\",\"kicker\":\"CASE FILE · XOPS-01\",\"title\":\"Install and Daily CLI\",\"subtitle\":\"Get xops on PATH and use it every day\",\"blurb\":\"Global install, doctor, workspace install-once, and the daily command surface.\",\"tags\":[\"install\",\"cli\",\"workspaces\"],\"color\":\"#b14a2c\",\"dir\":\"01-install-and-daily\"},{\"id\":\"02-release-and-publish\",\"familyId\":\"xops\",\"audiences\":[\"developers\"],\"status\":\"available\",\"kicker\":\"CASE FILE · XOPS-02\",\"title\":\"Release and Publish\",\"subtitle\":\"The original wedge\",\"blurb\":\"Discovery, dependency order, safety, publish, push, and undo for humans and agents.\",\"tags\":[\"release\",\"publish\",\"safety\"],\"color\":\"#1f6e5c\",\"dir\":\"02-release-and-publish\"},{\"id\":\"03-cli-sdk-mcp\",\"familyId\":\"xops\",\"audiences\":[\"developers\"],\"status\":\"available\",\"kicker\":\"CASE FILE · XOPS-03\",\"title\":\"CLI, SDK, and MCP\",\"subtitle\":\"One contract, three interfaces\",\"blurb\":\"Ask, typed SDK results, MCP tools/resources, and plan-first approvals for agents.\",\"tags\":[\"sdk\",\"mcp\",\"ask\",\"agents\"],\"color\":\"#a5710f\",\"dir\":\"03-cli-sdk-mcp\"},{\"id\":\"04-ops-and-tools\",\"familyId\":\"xops\",\"audiences\":[\"builders\"],\"status\":\"available\",\"kicker\":\"CASE FILE · XOPS-04\",\"title\":\"Ops and Tools\",\"subtitle\":\"Catalog, recommendations, playbooks\",\"blurb\":\"ops status, recommendations, seamless tools, and operational playbooks.\",\"tags\":[\"ops\",\"tools\",\"playbooks\"],\"color\":\"#2c5f7a\",\"dir\":\"04-ops-and-tools\",\"buildersPrimary\":true},{\"id\":\"05-agents-and-safety\",\"familyId\":\"xops\",\"audiences\":[\"developers\"],\"status\":\"available\",\"kicker\":\"CASE FILE · XOPS-05\",\"title\":\"Agents and Safety\",\"subtitle\":\"Agent packs, gitignore, publish safety\",\"blurb\":\"AI context packs, safety gates, and how agents should call xops without scraping terminals.\",\"tags\":[\"agents\",\"safety\",\"ai-pack\"],\"color\":\"#4a3f6b\",\"dir\":\"05-agents-and-safety\"}]}",
+    "use-cases.json": "{\"useCases\":[{\"id\":\"orient-xops\",\"title\":\"Orient on xops\",\"goal\":\"Understand the operating layer, three interfaces, and which book to open next.\",\"audiences\":[\"developers\",\"builders\"],\"tags\":[\"platform\",\"start-here\"],\"path\":[{\"bookId\":\"00-platform-overview\",\"audience\":\"developers\",\"chapters\":[\"the-mental-model\",\"one-contract-three-interfaces\",\"what-xops-owns\",\"hard-product-rules\",\"which-book-next\"]}],\"alsoSee\":[\"00-platform-overview\"]},{\"id\":\"install-and-doctor\",\"title\":\"Install xops and run doctor\",\"goal\":\"Get @x12i/xops on PATH, confirm shims, and clear doctor checks.\",\"audiences\":[\"developers\",\"builders\"],\"tags\":[\"install\",\"doctor\"],\"path\":[{\"bookId\":\"01-install-and-daily\",\"audience\":\"developers\",\"chapters\":[\"install-the-cli\",\"confirm-on-path\",\"run-doctor\",\"workspace-install-once\"]}],\"alsoSee\":[\"01-install-and-daily\",\"04-ops-and-tools\"]},{\"id\":\"run-a-safe-release\",\"title\":\"Run a safe release\",\"goal\":\"Plan, approve, publish, and undo a monorepo or single-package release.\",\"audiences\":[\"developers\"],\"tags\":[\"release\",\"publish\"],\"path\":[{\"bookId\":\"02-release-and-publish\",\"audience\":\"developers\",\"chapters\":[\"discovery-and-order\",\"safety-gates\",\"publish-and-push\",\"undo-and-recovery\"]}],\"alsoSee\":[\"02-release-and-publish\",\"05-agents-and-safety\"]},{\"id\":\"wire-sdk-or-mcp\",\"title\":\"Wire the SDK or MCP\",\"goal\":\"Call the same operating layer from TypeScript or an MCP host with plan-first approvals.\",\"audiences\":[\"developers\"],\"tags\":[\"sdk\",\"mcp\",\"agents\"],\"path\":[{\"bookId\":\"03-cli-sdk-mcp\",\"audience\":\"developers\",\"chapters\":[\"ask-and-passthrough\",\"typed-sdk-results\",\"mcp-tools-and-resources\",\"plan-first-approvals\"]}],\"alsoSee\":[\"03-cli-sdk-mcp\",\"05-agents-and-safety\"]},{\"id\":\"operate-the-tool-catalog\",\"title\":\"Operate the tool catalog\",\"goal\":\"Read ops status, apply recommendations, and run playbooks without inventing a second ops stack.\",\"audiences\":[\"builders\"],\"tags\":[\"ops\",\"tools\",\"playbooks\"],\"path\":[{\"bookId\":\"04-ops-and-tools\",\"audience\":\"builders\",\"chapters\":[\"ops-status\",\"recommendations\",\"seamless-tools\",\"playbooks\"]}],\"alsoSee\":[\"04-ops-and-tools\",\"00-platform-overview\"]},{\"id\":\"brief-a-coding-agent\",\"title\":\"Brief a coding agent\",\"goal\":\"Generate AI context packs and teach an agent to use xops safely.\",\"audiences\":[\"developers\"],\"tags\":[\"agents\",\"ai-pack\",\"safety\"],\"path\":[{\"bookId\":\"05-agents-and-safety\",\"audience\":\"developers\",\"chapters\":[\"ai-packs\",\"agent-call-shape\",\"publish-and-secret-safety\",\"knowledge-sdk\"]}],\"alsoSee\":[\"05-agents-and-safety\",\"03-cli-sdk-mcp\"]}]}",
+    "site.json": "{\"product\":\"xops\",\"brand\":\"xops · docs\",\"brandAccent\":\"docs\",\"siteUrl\":\"https://docs.xops.x12i.com\",\"knowledgePackage\":\"@x12i/xops-docs\",\"footer\":\"XOPS FIELD GUIDES · OPERATING LAYER\",\"accent\":\"oklch(42% 0.09 250)\",\"accentAlt\":\"oklch(52% 0.11 35)\",\"productUrl\":\"https://github.com/x12i/npm\",\"nav\":[{\"label\":\"Getting started\",\"href\":\"/getting-started\"},{\"label\":\"Use cases\",\"href\":\"/use-cases\"},{\"label\":\"Catalog\",\"href\":\"/catalog\"}],\"footerLinks\":[{\"label\":\"Docs home\",\"href\":\"/docs\"},{\"label\":\"Getting started\",\"href\":\"/getting-started\"},{\"label\":\"Use cases\",\"href\":\"/use-cases\"},{\"label\":\"Catalog\",\"href\":\"/catalog\"},{\"label\":\"Agents/SDK\",\"href\":\"/agents\"}]}",
+    "agent-manifest.json": "{\"version\":1,\"product\":\"xops\",\"site\":\"https://docs.xops.x12i.com\",\"knowledgePackage\":\"@x12i/xops-docs\",\"roles\":[\"developers\",\"builders\"],\"books\":[{\"id\":\"00-platform-overview\",\"audiences\":[\"developers\",\"builders\"],\"md\":{\"developers\":\"downloads/books/00-platform-overview/developers.md\",\"builders\":\"downloads/books/00-platform-overview/builders.md\"},\"pdf\":{\"developers\":null,\"builders\":null},\"chapters\":{\"developers\":\"downloads/books/00-platform-overview/developers.chapters.json\",\"builders\":\"downloads/books/00-platform-overview/builders.chapters.json\"}},{\"id\":\"01-install-and-daily\",\"audiences\":[\"developers\"],\"md\":{\"developers\":\"downloads/books/01-install-and-daily/developers.md\"},\"pdf\":{\"developers\":null},\"chapters\":{\"developers\":\"downloads/books/01-install-and-daily/developers.chapters.json\"}},{\"id\":\"02-release-and-publish\",\"audiences\":[\"developers\"],\"md\":{\"developers\":\"downloads/books/02-release-and-publish/developers.md\"},\"pdf\":{\"developers\":null},\"chapters\":{\"developers\":\"downloads/books/02-release-and-publish/developers.chapters.json\"}},{\"id\":\"03-cli-sdk-mcp\",\"audiences\":[\"developers\"],\"md\":{\"developers\":\"downloads/books/03-cli-sdk-mcp/developers.md\"},\"pdf\":{\"developers\":null},\"chapters\":{\"developers\":\"downloads/books/03-cli-sdk-mcp/developers.chapters.json\"}},{\"id\":\"04-ops-and-tools\",\"audiences\":[\"builders\"],\"md\":{\"builders\":\"downloads/books/04-ops-and-tools/builders.md\"},\"pdf\":{\"builders\":null},\"chapters\":{\"builders\":\"downloads/books/04-ops-and-tools/builders.chapters.json\"}},{\"id\":\"05-agents-and-safety\",\"audiences\":[\"developers\"],\"md\":{\"developers\":\"downloads/books/05-agents-and-safety/developers.md\"},\"pdf\":{\"developers\":null},\"chapters\":{\"developers\":\"downloads/books/05-agents-and-safety/developers.chapters.json\"}}],\"useCases\":[{\"id\":\"orient-xops\",\"title\":\"Orient on xops\",\"md\":\"downloads/use-cases/orient-xops.md\",\"path\":[{\"bookId\":\"00-platform-overview\",\"audience\":\"developers\",\"chapters\":[\"the-mental-model\",\"one-contract-three-interfaces\",\"what-xops-owns\",\"hard-product-rules\",\"which-book-next\"]}]},{\"id\":\"install-and-doctor\",\"title\":\"Install xops and run doctor\",\"md\":\"downloads/use-cases/install-and-doctor.md\",\"path\":[{\"bookId\":\"01-install-and-daily\",\"audience\":\"developers\",\"chapters\":[\"install-the-cli\",\"confirm-on-path\",\"run-doctor\",\"workspace-install-once\"]}]},{\"id\":\"run-a-safe-release\",\"title\":\"Run a safe release\",\"md\":\"downloads/use-cases/run-a-safe-release.md\",\"path\":[{\"bookId\":\"02-release-and-publish\",\"audience\":\"developers\",\"chapters\":[\"discovery-and-order\",\"safety-gates\",\"publish-and-push\",\"undo-and-recovery\"]}]},{\"id\":\"wire-sdk-or-mcp\",\"title\":\"Wire the SDK or MCP\",\"md\":\"downloads/use-cases/wire-sdk-or-mcp.md\",\"path\":[{\"bookId\":\"03-cli-sdk-mcp\",\"audience\":\"developers\",\"chapters\":[\"ask-and-passthrough\",\"typed-sdk-results\",\"mcp-tools-and-resources\",\"plan-first-approvals\"]}]},{\"id\":\"operate-the-tool-catalog\",\"title\":\"Operate the tool catalog\",\"md\":\"downloads/use-cases/operate-the-tool-catalog.md\",\"path\":[{\"bookId\":\"04-ops-and-tools\",\"audience\":\"builders\",\"chapters\":[\"ops-status\",\"recommendations\",\"seamless-tools\",\"playbooks\"]}]},{\"id\":\"brief-a-coding-agent\",\"title\":\"Brief a coding agent\",\"md\":\"downloads/use-cases/brief-a-coding-agent.md\",\"path\":[{\"bookId\":\"05-agents-and-safety\",\"audience\":\"developers\",\"chapters\":[\"ai-packs\",\"agent-call-shape\",\"publish-and-secret-safety\",\"knowledge-sdk\"]}]}]}"
+};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { type DocifySdk } from "@x12i/docify-sdk";
+import { catalog, useCases, site, manifest, files } from "./generated/bundle.js";
+/** Pre-wired xops knowledge SDK. Install as a **devDependency** only. */
+export declare const xopsDocs: DocifySdk;
+export { createDocifySdk, type DocifySdk } from "@x12i/docify-sdk";
+export { catalog, useCases, site, manifest, files };
+export default xopsDocs;

package/dist/index.js

@@ -0,0 +1,13 @@
+import { createDocifySdk } from "@x12i/docify-sdk";
+import { catalog, useCases, site, manifest, files } from "./generated/bundle.js";
+/** Pre-wired xops knowledge SDK. Install as a **devDependency** only. */
+export const xopsDocs = createDocifySdk({
+    catalog: catalog,
+    useCases: useCases,
+    site: site,
+    manifest: manifest,
+    files,
+});
+export { createDocifySdk } from "@x12i/docify-sdk";
+export { catalog, useCases, site, manifest, files };
+export default xopsDocs;

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@x12i/xops-docs",
+  "version": "0.1.0",
+  "description": "xops docs knowledge SDK — install as a devDependency only. Catalog, use cases, and markdown packs for humans and agents.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "xops-docs": "bin/xops-docs.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md"
+  ],
+  "scripts": {
+    "prebuild": "rm -rf dist",
+    "build": "tsc -p tsconfig.build.json && node -e \"import('node:fs').then(fs=>fs.chmodSync('dist/cli.js',0o755))\"",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@x12i/docify-core": "^1.0.1",
+    "@x12i/docify-sdk": "^1.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/x12i/npm.git",
+    "directory": "xops-docs/packages/xops-docs"
+  },
+  "keywords": [
+    "x12i",
+    "xops",
+    "docs",
+    "knowledge",
+    "devDependency",
+    "docify"
+  ],
+  "license": "MIT"
+}