{"_id":"@anokye-labs/kbx","_rev":"3-3ade5862bb3c5f727252336e4e647475","name":"@anokye-labs/kbx","dist-tags":{"latest":"0.2.1"},"versions":{"0.1.0":{"name":"@anokye-labs/kbx","version":"0.1.0","keywords":["knowledge-base","graph","documentation","code-analysis","copilot"],"author":{"name":"Anokye Labs"},"license":"MIT","_id":"@anokye-labs/kbx@0.1.0","maintainers":[{"name":"hoopsomuah","email":"hoop@somuah.com"}],"homepage":"https://github.com/anokye-labs/kbexplorer-cli","bugs":{"url":"https://github.com/anokye-labs/kbexplorer-cli/issues"},"bin":{"kbx":"bin/cli.js"},"dist":{"shasum":"2f3545246a6e9c2533ce6a1d4e3d709c366ba7a1","tarball":"https://registry.npmjs.org/@anokye-labs/kbx/-/kbx-0.1.0.tgz","fileCount":128,"integrity":"sha512-hrFnGj3brVLd1irt9sDYQuaorr24ClrmhH+1l/mDCyqxVsOf4v18uT5lsfbsrhswB43T2oiUZPJrB9MSc6xAMA==","signatures":[{"sig":"MEUCIQDqxdXGxtEDyxpmlAt6SqnjeFQWkWq62WLUK7UIJC5eYQIgSeKpoDj+PxXzed/SqkyHUXUPvTsnvBIsmvg/Dd5uMso=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":966395},"type":"module","engines":{"node":">=22"},"gitHead":"afc42156e285ee24a2060fe52f6d078309ea7528","scripts":{"test":"node scripts/run-tests.js","kb:dev":"kbx dev","kb:build":"kbx build","kb:generate":"kbx generate"},"_npmUser":{"name":"hoopsomuah","email":"hoop@somuah.com"},"repository":{"url":"git+https://github.com/anokye-labs/kbexplorer-cli.git","type":"git"},"_npmVersion":"11.16.0","description":"CLI tool for the kbexplorer interactive knowledge base — turn any repo into a navigable knowledge graph","directories":{},"_nodeVersion":"26.3.0","dependencies":{"@modelcontextprotocol/sdk":"1.29.0","@anokye-labs/kbexplorer-core":"github:anokye-labs/kbexplorer-core#v0.3.0","@anokye-labs/kbexplorer-search":"github:anokye-labs/kbexplorer-search#ff6c5999c3d78290606d421b4616f984b66c5213","@anokye-labs/kbexplorer-provider-rich-markdown":"github:anokye-labs/kbexplorer-provider-rich-markdown#v0.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/kbx_0.1.0_1783048212356_0.9003909695029122","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@anokye-labs/kbx","version":"0.2.0","keywords":["knowledge-base","graph","documentation","code-analysis","copilot"],"author":{"name":"Anokye Labs"},"license":"MIT","_id":"@anokye-labs/kbx@0.2.0","maintainers":[{"name":"hoopsomuah","email":"hoop@somuah.com"}],"homepage":"https://github.com/anokye-labs/kbexplorer-cli","bugs":{"url":"https://github.com/anokye-labs/kbexplorer-cli/issues"},"bin":{"kbx":"bin/kbx.js"},"dist":{"shasum":"17afc2e8b7aeaea551fd341cb00ee307350bf150","tarball":"https://registry.npmjs.org/@anokye-labs/kbx/-/kbx-0.2.0.tgz","fileCount":146,"integrity":"sha512-zLLxBpYpZqyqQzOrHgWb/ZAxRIxTjp7rPEPLaINS2hTEujn+iwhMPJbb8h7hlGklQL9C3Vv1MWiVMmngMV+ZDg==","signatures":[{"sig":"MEQCIAtzELj084lnql5wW0NsJ0TM2cunEwjNfwK/8r9bRSkhAiBd8SMUqBkUWS0jizrW92l/E5jfIc3OP20H5QqN/nTnKg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@anokye-labs%2fkbx@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":1071654},"type":"module","engines":{"node":">=22"},"gitHead":"04e1d24dd7b9b89d36bd3a5c9670b3a1879d5c05","scripts":{"test":"node --experimental-strip-types scripts/run-tests.js","build":"tsup src/cli.ts --format esm --platform node --target node22 --out-dir dist --clean","kb:dev":"kbx dev","kb:build":"kbx build","typecheck":"tsc --noEmit","kb:generate":"kbx generate"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:0d1181bc-07d7-4bc9-87c8-7f9a10bc33b5"}},"repository":{"url":"git+https://github.com/anokye-labs/kbexplorer-cli.git","type":"git"},"_npmVersion":"12.0.2","description":"CLI tool for the kbexplorer interactive knowledge base — turn any repo into a navigable knowledge graph","directories":{},"_nodeVersion":"22.23.1","dependencies":{"yaml":"^2.9.0","@modelcontextprotocol/sdk":"1.29.0","@anokye-labs/kbexplorer-core":"^0.5.1","@anokye-labs/kbexplorer-engine":"^0.1.0","@anokye-labs/kbexplorer-search":"github:anokye-labs/kbexplorer-search#v0.1.0","@anokye-labs/kbexplorer-provider-rich-markdown":"^0.1.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","typescript":"^6.0.3","@types/node":"^26.1.0"},"_npmOperationalInternal":{"tmp":"tmp/kbx_0.2.0_1786634819633_0.49298117928669805","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"_id":"@anokye-labs/kbx@0.2.1","bin":{"kbx":"bin/kbx.js"},"bugs":{"url":"https://github.com/anokye-labs/kbexplorer-cli/issues"},"dist":{"shasum":"7bb6842a2d9be9c7bd3321b52c709aafc8823df8","tarball":"https://registry.npmjs.org/@anokye-labs/kbx/-/kbx-0.2.1.tgz","integrity":"sha512-amcykNjqFE1mh0cZfMYesmKh2ZC1XLd0s/fvKlaXuXprs1HBYju9+Zj6RyNpGixMXD8nrOJ786GMkWZpScBrsQ==","fileCount":151,"unpackedSize":1516834,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@anokye-labs%2fkbx@0.2.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDGSKGbFat4eV8Bywj7JlczN6V7ewAJFOeInaIdqnkWDgIhAORO3KWlHGocY+/zeamz+EM+/KQuKOqQCG0WD/ooagSd"}]},"name":"@anokye-labs/kbx","type":"module","author":{"name":"Anokye Labs"},"engines":{"node":">=22"},"gitHead":"4c569dcb604ba3d22d2569690f53ab0ba1161625","license":"MIT","scripts":{"test":"node --experimental-strip-types scripts/run-tests.js","build":"tsup src/cli.ts --format esm --platform node --target node22 --out-dir dist --clean","kb:dev":"kbx dev","kb:build":"kbx build","typecheck":"tsc --noEmit","kb:generate":"kbx generate"},"version":"0.2.1","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:0d1181bc-07d7-4bc9-87c8-7f9a10bc33b5"},"approver":{"name":"hoopsomuah","email":"hoop@somuah.com"}},"homepage":"https://github.com/anokye-labs/kbexplorer-cli","keywords":["knowledge-base","graph","documentation","code-analysis","copilot"],"repository":{"url":"git+https://github.com/anokye-labs/kbexplorer-cli.git","type":"git"},"_npmVersion":"12.0.2","description":"CLI tool for the kbexplorer interactive knowledge base — turn any repo into a navigable knowledge graph","directories":{},"maintainers":[{"name":"hoopsomuah","email":"hoop@somuah.com"}],"_nodeVersion":"22.23.2","dependencies":{"yaml":"^2.9.0","@modelcontextprotocol/sdk":"1.29.0","@anokye-labs/kbexplorer-core":"^0.6.0","@anokye-labs/kbexplorer-engine":"^0.1.1","@anokye-labs/kbexplorer-search":"^0.1.1","@anokye-labs/kbexplorer-provider-rich-markdown":"^0.1.3"},"publishConfig":{"access":"public"},"devDependencies":{"tsup":"^8.5.1","typescript":"^6.0.3","@types/node":"^26.1.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/kbx_0.2.1_1789614237319_0.3825897181340492"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-03T03:10:12.255Z","modified":"2026-09-17T03:03:57.777Z","0.1.0":"2026-07-03T03:10:12.568Z","0.2.0":"2026-08-13T15:26:59.863Z","0.2.1":"2026-09-17T03:03:57.457Z"},"bugs":{"url":"https://github.com/anokye-labs/kbexplorer-cli/issues"},"author":{"name":"Anokye Labs"},"license":"MIT","homepage":"https://github.com/anokye-labs/kbexplorer-cli","keywords":["knowledge-base","graph","documentation","code-analysis","copilot"],"repository":{"url":"git+https://github.com/anokye-labs/kbexplorer-cli.git","type":"git"},"description":"CLI tool for the kbexplorer interactive knowledge base — turn any repo into a navigable knowledge graph","maintainers":[{"name":"hoopsomuah","email":"hoop@somuah.com"}],"readme":"# kbx\n\nCLI tool for the [kbexplorer-template](https://github.com/anokye-labs/kbexplorer-template) interactive knowledge base — turn any GitHub repository into a navigable knowledge graph.\n\n## Install\n\n```bash\n# Use directly\nnpx @anokye-labs/kbx init\n\n# Or install as dev dependency\nnpm install -D @anokye-labs/kbx\n```\n\n> Until the first npm publish lands, install from GitHub instead:\n> `npm install -D github:anokye-labs/kbexplorer-cli`.\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `kbx init` | Add `.kbx/` submodule, install agents/skills, configure |\n| `kbx generate` | Run content generation pipeline (architect → transform → writer) |\n| `kbx derive <source...>` | Extract JSON-LD entities from unstructured sources (.docx/.md/.txt) via Copilot |\n| `kbx scaffold <slug> --cluster <id>` | Create a single new content page with valid frontmatter |\n| `kbx audit` | Schema/structural validation (duplicate ids, broken parents, cycles) — CI-grade |\n| `kbx affected <git-ref>` | Map a git diff to impacted content nodes via citations |\n| `kbx links` | Graph health report (orphans, weak clusters, coverage gaps) |\n| `kbx dev` | Start dev server in local mode |\n| `kbx build` | Production build |\n| `kbx manifest` | Regenerate repo manifest from local data |\n| `kbx update` | Pull latest template + refresh agents/skills |\n| `kbx doctor` | Diagnose local runtime, MCP, template setup, and adoption readiness |\n\n## Quick Start\n\n```bash\n# In any GitHub repo:\nnpx kbx init    # Interactive setup wizard\nnpx kbx dev     # Launch the explorer\n```\n\n### Non-interactive setup (CI / scripted / no TTY)\n\nThe wizard needs a terminal. In CI or any non-interactive shell, pass `--yes`\nto take every answer from flags plus git-remote detection instead of prompting\n(without `--yes` on a non-TTY stdin, `init` now exits with this reminder rather\nthan hanging):\n\n```bash\nnpx kbx init --yes                         # inside a git repo: owner/repo/branch auto-detected\nnpx kbx init --yes --owner acme --repo widgets --title \"Acme KB\"\n```\n\nCommon flags (see `npx kbx init --help` for the full list): `--owner`, `--repo`,\n`--kb-branch`, `--title`, `--content-mode <repo|authored|both>`, `--content`,\n`--visual`, `--theme`, `--runtime <copilot|claude|custom|skip>`, and `--config\n<file>` to load any of them from JSON.\n\nFor a full enterprise deployment walkthrough — prerequisites, work-graph YAML\nauthoring, the local regeneration loop, and hosting options — see\n**[docs/deploy-to-a-work-repo.md](docs/deploy-to-a-work-repo.md)**.\n\nCopy-paste YAML starters for the five organizational-layer descriptor kinds are in\n**[docs/templates/](docs/templates/)**.\n\n## Dogfood: build a KB over this repo\n\nThe authored content in [`content/`](content/) describes kbexplorer-cli\nitself. Once the explorer is installed (`init`), `dev` will render it:\n\n```bash\nnpx kbx init --vendor   # one-time: vendors the explorer into .kbx/\nnpx kbx dev             # build the manifest, start Vite at :5173\n```\n\nOpen <http://localhost:5173>. You should see a graph of 27 nodes covering\nthe CLI router, every command, the lib/ heart, the agents, the skill,\ninstall modes, the zero-dependency design, and the **derivation & contract**\nsubsystem (the `derive` command, the programmatic-mode runtime, and the engine\nnode-type contract).\n\nTo regression-check the dogfood loop end-to-end:\n\n```bash\nnode scripts/verify-self-kb.js   # headless Playwright; screenshots → dist-screenshots/\n```\n\n## What `init` Does\n\n1. Adds `.kbx/` as a git submodule (the visual explorer app)\n2. Installs agents to `.github/agents/` (kb-architect, kb-writer, kb-researcher)\n3. Installs skills to `.github/skills/kbx/`\n4. Runs interactive config wizard (content mode, title, theme, etc.)\n5. Creates `.env.kbx` and adds npm scripts\n\n## Using a Custom Template\n\nBy default `init` installs the official `anokye-labs/kbexplorer-template`. To use your own\nfork or an org-internal template, pass `--template`:\n\n```bash\nnpx kbx init --template https://github.com/my-org/my-template.git\n```\n\n### Install modes\n\n| Mode | Flag | What you get |\n|------|------|--------------|\n| **Submodule** (default) | _(none)_ | `.kbx/` is a pinned git submodule. Lightweight; `kbx update` bumps the pin. Best when you track upstream as-is. |\n| **Vendor** (one-time copy) | `--vendor` / `--no-submodule` | `.kbx/` is a plain folder (the template's `.git` is stripped). Best when you want to copy-and-customize. |\n\n```bash\n# Pin to a specific tag or branch (default: latest release tag)\nnpx kbx init --ref v1.2.0\nnpx kbx init --vendor --ref main\n```\n\nBoth modes record where the template came from in **`.kbx.json`** at your repo root:\n\n```json\n{ \"template\": \"<url>\", \"ref\": \"v1.2.0\", \"refType\": \"tag\", \"resolvedCommit\": \"…\", \"mode\": \"submodule\" }\n```\n\n`kbx update` reads this record. For vendored installs it never overwrites your\n`.kbx/` silently — it fetches the new version into a sibling folder for review, and\n`--force` backs up your current copy before swapping it in.\n\n## Content Generation\n\n`kbx generate` runs the content pipeline on top of **Copilot CLI\nprogrammatic mode** (`copilot -p`). When there is no `catalogue.json` (or you\npass `--refresh`), it drives Copilot to analyze the repo and emit one, then\ndeterministically transforms it into `content/` and regenerates the manifest:\n\n```bash\n# Drives `copilot -p` (kb-architect) → catalogue.json → content/ → manifest\nnpx kbx generate\n\n# Preview the exact copilot command without running it\nnpx kbx generate --dry-run\n\n# Scope tool permissions instead of the default --allow-all-tools\nnpx kbx generate --allow-tool 'shell(git)' --allow-tool 'write'\n\n# Re-run analysis even if catalogue.json already exists\nnpx kbx generate --refresh\n\n# Skip the agent step and just transform an existing catalogue\nnpx kbx generate --no-agent\n```\n\nRequires the [Copilot CLI](https://docs.github.com/copilot/how-tos/copilot-cli)\non your `PATH` (or set `KBX_COPILOT_BIN` to its full path). The fuzzy\n(LLM) and deterministic (transform/manifest) phases both flow through a single\n**runtime router** — see [`docs/copilot-runtime.md`](docs/copilot-runtime.md)\nfor the adapter's public API and configuration.\n\nYou can still produce `catalogue.json` out-of-band (e.g. via the kb-architect\nagent in an interactive Copilot session) and run `kbx generate --no-agent`.\n\n## Build-time Derivation (unstructured → JSON-LD)\n\n`kbx derive` turns **unstructured / semi-structured** sources — `.docx`,\nprose Markdown, and loosely-structured text — into committed `*.jsonld` entity\nartifacts that conform to the engine's node-type contract. It mirrors\n`generate`: a fuzzy (LLM) phase runs through **Copilot programmatic mode**\n(`copilot -p`) to extract entities and relationships, then a deterministic phase\nnormalizes and validates them into canonical JSON-LD.\n\n```bash\n# Read .docx/.md/.txt, extract via `copilot -p`, emit content/derived/*.jsonld\nnpx kbx derive docs/org-chart.docx notes/teams.md\n\n# Preview the exact copilot command + planned outputs without running anything\nnpx kbx derive docs/org-chart.docx --dry-run\n\n# Write to a custom output directory\nnpx kbx derive docs/*.docx --out content/derived\n\n# CI drift gate: fail (non-zero exit) if any committed artifact is stale.\n# Pass the SAME source files you derived from — never the .jsonld outputs.\n# Never calls the LLM — purely deterministic.\nnpx kbx derive docs/*.docx --check\n\n# Force re-extraction even when a fresh artifact already exists\nnpx kbx derive docs/org-chart.docx --refresh\n```\n\nEach emitted node carries the F1 contract fields: an `@id` identity URN\n(`kg://<type>/<slug>`, reused as identity and **never** derived from a file\npath), an open lowercase `@type` entity kind (also never path-derived), a\n`@context` (defaults to `https://schema.org`), and relationships mapped onto the\nsix-relation taxonomy `leads | staffs | reports-to | structural | derived |\ndeprecated`. The committed artifact also embeds a KBNode mirror (`entityType` +\n`jsonld` + `data`) and a reversible `source.ref` back to the originating\ndocument.\n\nThese fields are exactly the **engine node-type contract** published by the\ntemplate (Epic 1 / F1 — see\n[kbexplorer-template#148](https://github.com/anokye-labs/kbexplorer-template/issues/148)).\nThe engine renders a `structured` node by resolving its `entityType` against an\nopen node-type registry: spine kinds such as `person`, `squad`, `workstream`,\n`mission`, `priority`, `cycle`, and `org` get bespoke viewers, and any other\n`@type` falls back to a generic structured view — so a derived artifact always\nrenders without core edits. A worked end-to-end example (a `.docx` sentence →\n`kg://person/…` + a `leads` edge → a rendered node) lives in the dogfood KB at\n[`content/node-type-contract.md`](content/node-type-contract.md).\n\n**Idempotency & drift.** Artifacts are timestamp-free and serialized with sorted\nkeys, so identical input yields **byte-identical** output. The artifact embeds\nthe extraction intermediate keyed by the source's SHA-256; re-running `derive`\non an unchanged source reuses that intermediate and re-emits deterministically\n**without calling the LLM**. `--check` is a read-only CI gate: it reports drift\n(and exits non-zero) when an artifact is missing, when its source has changed, or\nwhen a fresh deterministic emit differs from the committed bytes — never invoking\nCopilot.\n\nLike `generate`, the fuzzy phase requires the\n[Copilot CLI](https://docs.github.com/copilot/how-tos/copilot-cli) on your\n`PATH` (or `KBX_COPILOT_BIN`); sources already derived from unchanged\ninput do not need it. Both phases flow through the same **runtime router** — see\n[`docs/copilot-runtime.md`](docs/copilot-runtime.md).\n\n## GitHub API Base Configuration\n\nBy default the CLI fetches GitHub data (issues, PRs, releases) via the `gh` CLI — behaviour identical to previous releases. You can override this to point the CLI at a **Gitea DTU adapter** (for hermetic testing) or a **GitHub Enterprise / EMU host** (real deployment).\n\n### Precedence\n\n| Priority | Source | How |\n|----------|--------|-----|\n| 1 | `ghApiBase` in `.kbx.json` | Set once; travels with the repo |\n| 2 | `KBX_GH_API_BASE` env var | Runtime override |\n| 3 | Default | `gh` CLI (github.com) |\n\n### Gitea DTU adapter (hermetic testing)\n\nWhen the DTU adapter is running on `TWIN_PORT` (default 3456), point the CLI at it:\n\n```bash\nKBX_GH_API_BASE=http://localhost:3456 \\\nKBX_GH_TOKEN=<gitea-token> \\\nkbx manifest\n```\n\nThe adapter translates GitHub REST v3 requests to the Gitea API — the CLI needs no other changes.\n\n### GitHub Enterprise / EMU\n\nTwo options:\n\n```bash\n# Option A — direct HTTP (works without a gh auth handshake)\nKBX_GH_API_BASE=https://github.example.com/api/v3 \\\nKBX_GH_TOKEN=<personal-access-token> \\\nkbx manifest\n\n# Option B — gh CLI with GH_HOST (no base override needed)\nGH_HOST=github.example.com kbx manifest\n```\n\n### Auth\n\nWhen a base is set the CLI sends `Authorization: token <token>` where `<token>` is:\n\n| Priority | Source |\n|----------|--------|\n| 1 | `KBX_GH_TOKEN` env var |\n| 2 | `GH_TOKEN` env var |\n| 3 | Anonymous (no header sent) |\n\n### Repo-local config\n\nAdd `ghApiBase` alongside the existing template-source fields in `.kbx.json`:\n\n```jsonc\n{\n  \"template\": \"https://github.com/anokye-labs/kbexplorer-template.git\",\n  \"mode\": \"submodule\",\n  // …\n  \"ghApiBase\": \"http://localhost:3456\"\n}\n```\n\n## Runtime Configuration\n\nkbx supports three agent runtimes for fuzzy (LLM) steps: **copilot**\n(default), **claude**, and **custom** (any CLI). The active runtime is resolved\nusing the following precedence, from highest to lowest:\n\n| Priority | Source | How |\n|----------|--------|-----|\n| 1 | `--runtime <name>` flag | `kbx derive --runtime claude` |\n| 2 | `runtime` block in `.kbx.json` | Set once; travels with the repo |\n| 3 | `KBX_RUNTIME` env var | `KBX_RUNTIME=claude kbx derive …` |\n| 4 | Default | `copilot` |\n\n### Repo-local config (`.kbx.json`)\n\nAdd a `runtime` block alongside the existing template-source fields:\n\n```jsonc\n{\n  \"template\": \"https://github.com/anokye-labs/kbexplorer-template.git\",\n  \"mode\": \"submodule\",\n  // …\n  \"runtime\": {\n    \"agent\": \"copilot\"   // \"copilot\" | \"claude\" | \"custom\"\n  }\n}\n```\n\nFor `claude`:\n```json\n{\n  \"runtime\": { \"agent\": \"claude\" }\n}\n```\n\nFor a **custom** CLI (must include `{prompt}` placeholder):\n```json\n{\n  \"runtime\": {\n    \"agent\": \"custom\",\n    \"command\": \"my-agent\",\n    \"argsTemplate\": [\"-p\", \"{prompt}\", \"--json\"],\n    \"outputFormat\": \"jsonl\",\n    \"timeoutMs\": 600000\n  }\n}\n```\n\n`kbx init` offers a runtime selection step during interactive setup and\ncan write this block automatically.\n\n### MCP server requirements\n\nFuzzy tasks often depend on local MCP servers. Declare them in the `runtime`\nblock so the CLI verifies they are configured **before** any LLM call or\npartial write:\n\n```jsonc\n{\n  \"runtime\": {\n    \"agent\": \"copilot\",\n    \"mcp\": {\n      \"required\": [\"ado\", \"sharepoint-docs\"],   // preflight fails if missing\n      \"optional\": [\"org-chart\"]                  // warning only, never fails\n    }\n  }\n}\n```\n\nOn failure the CLI prints the missing server name, the config file it expected\nit in, and a one-line example entry, then exits non-zero. Optional servers that\nare absent produce a warning instead.\n\n#### Detection locations per adapter\n\n| Adapter | Files checked (in order) |\n|---------|--------------------------|\n| `copilot` | `~/.copilot/mcp-config.json` (the file Copilot CLI reads; it has no repo-local MCP config today) |\n| `claude` | `<repo>/.mcp.json` → `~/.claude.json` (project entries matching cwd) |\n| `custom` | Detection not possible — all declared servers reported as unverifiable (warning, not failure) |\n\n#### Config file shape\n\nBoth adapters' files use the same entry shape (`~/.copilot/mcp-config.json`\nfor copilot, `.mcp.json` for claude):\n\n```json\n{ \"mcpServers\": { \"ado\": { \"command\": \"npx\", \"args\": [\"-y\", \"ado-mcp\"] } } }\n```\n\n#### `--skip-preflight`\n\nDevelopment escape hatch. Bypasses the MCP check with a warning — never use\nin CI.\n\n```bash\nkbx derive docs/org.docx --skip-preflight\nkbx generate --skip-preflight\n```\n\n### Binary path overrides\n\nThe named adapters honour existing env vars for binary paths:\n\n| Env var | Purpose |\n|---------|---------|\n| `KBX_COPILOT_BIN` | Full path to the `copilot` binary |\n| `KBX_CLAUDE_BIN` | Full path to the `claude` binary |\n\nThese work alongside (not instead of) the runtime selection above.\n\n## Multi-source Ingestion (`kbx.sources[]`)\n\n`src/lib/composite-config.js` + `src/lib/composite-ingest.js` implement a\ngeneralized, multi-source knowledge-base build: instead of one authored\n`content/` tree, a `sources[]` array declares several providers whose fragments\nget resolved and merged into one source-qualified graph. It is currently a\nlibrary surface (`loadCompositeKnowledgeBase`) consumed by a host you wire up\nyourself — no `kbx` command reads it from `.kbx.json` today. The shape:\n\n```jsonc\n{\n  \"sources\": [\n    {\n      \"sourceId\": \"docs\",                          // unique, stable id\n      \"kind\": \"rich-markdown\",                      // advisory provider type\n      \"module\": \"@anokye-labs/kbexplorer-provider-rich-markdown\", // ES specifier\n      \"options\": { \"cluster\": \"docs\" },              // provider-specific options\n      \"credentials\": { \"token\": \"GH_TOKEN\" }         // logical key -> ENV VAR NAME\n    }\n  ],\n  \"ingestion\": {\n    \"failureMode\": \"fail-fast\",\n    \"budgets\": { \"maxSources\": 10, \"timeoutMs\": 30000 }\n  }\n}\n```\n\nCredentials are declared by **environment-variable name only**; the value is\nresolved from `process.env` at load time and never persisted to config.\n\n### Trust boundary\n\n**`kbx.sources[]` config is code.** Each source's `module` is passed straight\ninto a dynamic `import()` — loading a provider module *executes* it, with that\nsource's resolved credentials handed to whatever loads. There is intentionally\nno module allowlist or sandboxing: the CLI cannot distinguish a legitimate\nprovider package from something malicious once it agrees to import it.\n\nPractical consequences:\n\n- **Treat edits to `kbx.sources[]` (and any config that can add or change a\n  `module` entry) with the same review rigor as a dependency change** — a new\n  or modified `module` specifier is, in effect, a new piece of installed code\n  that runs with credentials.\n- Each source only ever receives the credentials **it declares under its own\n  `credentials:` block** — `buildProviderConfig()` forwards exactly that\n  source's resolved bag, never a broader one another source might hold.\n- Prefer installed, versioned packages (`@scope/name`) over raw filesystem\n  paths or URLs for `module`. `kbx doctor` warns (does not fail — this is\n  advisory, not enforced) when a declared `module` looks like a raw path/URL\n  instead of an installed package.\n\n## Doctor\n\n`kbx doctor` is the first thing to run when regeneration fails on a teammate's machine. It diagnoses the full local setup across several sections (Runtime, MCP, Template, Adoption readiness, Plugin, Sources, Environment):\n\n```\nRuntime\n───────\n  ✅ Adapter: copilot (source: default)\n  ✅ Binary: copilot\n  ✅ Binary available: copilot version 1.2.3\n\nMCP\n───\n  ✅ No MCP servers declared in runtime config\n\nTemplate\n────────\n  ✅ .kbx.json present (mode: submodule, template: …)\n  ✅ .gitmodules url agrees with .kbx.json\n  ⚠️  A newer release tag exists: v1.0.0 → v1.1.0 (run kbx update)\n\nAdoption readiness\n──────────────────\n  ✅ Structured-content path: content-model/ (default convention); 5 YAML descriptors found\n  ✅ Structured-content path is repo-relative (content-model/), so local and remote builds can use the same layout\n  ⚠️  Template compatibility/capabilities are not advertised yet — cannot confirm content-model ingestion, diagram rendering, or edge semantics\n\nSources\n───────\n  ✅ No kbx.sources[] configured in .kbx.json\n\nEnvironment\n───────────\n  ✅ Node v22.1.0 (requires >=22)\n  ✅ git available: git version 2.44.0\n  ✅ gh (GitHub CLI) available: gh version 2.40.0\n  ⚠️  content/ directory not found\n```\n\n```bash\nkbx doctor                 # full diagnosis\nkbx doctor --runtime claude  # diagnose a specific adapter\nkbx doctor --json          # machine-readable output for scripts\nkbx doctor --offline       # skip the latest-tag network check\n```\n\n**Exit codes:** `0` when all checks pass or produce warnings; `1` when any check fails. Suitable as a CI gate (`kbx doctor --offline || exit 1`).\n\n## Agents\n\n| Agent | Description |\n|-------|-------------|\n| `kb-architect` | Scans repo → structured catalogue with clusters, connections, Fluent icons |\n| `kb-writer` | Generates rich content pages with citations, Mermaid diagrams |\n| `kb-researcher` | Deep investigation with evidence-first analysis |\n\nFor environments without agent support, each agent has an equivalent\nstep-by-step playbook in\n`.github/skills/kbx/references/{architect,writer,researcher}-playbook.md`\nthat any LLM can follow directly.\n\nAdapted from [microsoft/skills deep-wiki](https://github.com/microsoft/skills/tree/main/.github/plugins/deep-wiki) (MIT License).\n\n## Skill — full lifecycle\n\n`kbx init` installs the `kbx` skill at\n`.github/skills/kbx/`. It is a single skill with a slim router and a\nlibrary of focused references loaded on demand:\n\n| Reference | Covers |\n|---|---|\n| `setup.md` | Bootstrap in a new repo |\n| `frontmatter.md` | Full schema for content files |\n| `add-node.md` | Add a single page |\n| `update-node.md` | Refresh one page preserving author intent |\n| `incremental-refresh.md` | Diff-driven multi-page refresh |\n| `graph-curation.md` | Rename / move / merge / split nodes; recolor clusters |\n| `connections.md` | Edge derivation rules and good descriptions |\n| `audit.md` | Hard structural lint rules and remediation |\n| `presentation.md` | Visual mode, theme, fonts, HUD |\n| `assets-pipeline.md` | Sprite and hero image workflows |\n| `architect-playbook.md` | Build a catalogue without an agent runtime |\n| `writer-playbook.md` | Author one page deeply without an agent runtime |\n| `researcher-playbook.md` | Systematic codebase investigation |\n| `configuration.md` | `config.yaml` reference |\n| `content-generation.md` | Pipeline + catalogue → node mapping |\n\n## License\n\nMIT\n","readmeFilename":"README.md"}