# kyber-docs-authoring Adopt this skill: https://proskills.md/skills/other/dpalfery-kyber-weave-apm-skills-kyber-docs-authoring Page: https://proskills.md/skills/other/dpalfery-kyber-weave-apm-skills-kyber-docs-authoring This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required. ## File: .apm/skills/kyber-docs-authoring/SKILL.md size: 12800 sha: 6e4492188bd37be3ecb55616100100b079a5a745 upstream: https://github.com/dpalfery/kyber-weave/blob/main/.apm/skills/kyber-docs-authoring/SKILL.md ````text --- name: kyber-docs-authoring description: "Generate conformant Kyber-Weave frontmatter for repository documentation so that docs validate and docs drift pass. Use when a document fails a KW-DOC-SPEC or KW-DOC-DRIFT rule, when retrofitting an existing documentation tree after kyber-weave docs init, or when authoring a new governed document — including a todo or a coding standard — and you must choose doc-type, status, component, technology, source-root, and code-refs. Not for editing prose or style, authoring SKILL.md skills, or writing harness agent definitions." license: MIT metadata: author: dpalfery version: 0.1.4 --- # Authoring Kyber-Weave documentation Your job is to make a Markdown document **conformant**: correct frontmatter, honest claims about code, and a `doc-type` that matches what the document actually is. Verify with the tool, never by eye: ```bash kyber-weave docs validate . kyber-weave docs drift . ``` ## Required frontmatter Every governed document needs all six base keys: ```yaml --- id: docgraph/architecture # permanent, unique slug; others reference this title: DocGraph architecture doc-type: architecture # closed vocabulary — see below status: current # closed vocabulary — see below owner: dpalfery # MUST already exist in /catalog.md last-reviewed: 2026-08-01 # ISO yyyy-MM-dd, no other format --- ``` **doc-type** and **status** are closed sets. Read both, and the required-key matrix, from the document named by `` in the Config Reg. `docs init` writes that file from the host's ontology, so a list copied into this skill goes stale the next time a type is added. That is how `todo` and `coding-standard` were omitted here, and how an agent then labelled a coding standard `reference`: the document validated, and nothing reported that it would never resolve as a standard. If `` does not exist yet, finish **Setting up a new repository** and run `docs init` before choosing a type. Do not guess the set. Do not invent a value. Do not relabel a document `reference` because no type seems to fit. `reference` is reference material. A reminder of work not done now is `todo`. A document that says how one technology's code is written in this repository is `coding-standard`. ## Additional keys by doc-type Read the required-key matrix in `` and apply that row. The ontology document is the authority; this skill does not keep a second copy of the matrix. Two rows the omitted list used to hide, which the product defaults still require: - `todo` — `component`, in addition to the base keys - `coding-standard` — `technology`, and not `component` When the ontology document disagrees with those two rows, the ontology document wins. A host can require more; it cannot make a copied list in this skill true. `component` and `owner` must already be rows in the catalog. If the value you need is not there, **add the catalog row first** — inventing a component in frontmatter fails `KW-DOC-SPEC-004`. A repository has exactly one catalog, at `/catalog.md` — the first root, when `docs-root` names several — or wherever `ontology.catalog-path` puts it. A `catalog.md` sitting in another root is an ordinary document and supplies no vocabulary; adding a row there will not make a component valid. ## The pairing invariant For `architecture` and `runbook` only: `source-root` and `code-refs` travel together. - An architecture doc with `source-root` **must** list `code-refs` - An architecture doc with `code-refs` **must** declare `source-root` - A runbook with `source-root` **must** list `code-refs` If you cannot name real symbols, drop `source-root` rather than inventing them. ## code-refs are claims, not mentions ```yaml code-refs: - DocumentIndex - DocumentCorpus api-endpoints: - GET /api/me/usage ``` Listing a symbol asserts **this document is answerable for it**. Every entry is resolved against a live code index — a name that does not resolve fails `KW-DOC-DRIFT-001`. So: list only symbols the document genuinely describes. Do not list every type it mentions in passing. Three accurate entries beat twenty aspirational ones. **Verify before writing.** Confirm each symbol exists, and prefer the bare name over a fully qualified one unless it is ambiguous. If a code graph index is present you can check directly: ```bash sqlite3 .codegraph/codegraph.db \ "SELECT name, kind, file_path FROM nodes WHERE name='DocumentIndex' AND kind<>'import';" ``` `source-root` must be a real repository-relative directory that actually contains the indexed source for that component. LOAD `references/retrofit.md` when converting an existing documentation tree. LOAD `references/rules.md` for every rule id and what clears it. ## Choosing doc-type honestly The type drives retrieval ranking, so a wrong one is not cosmetic: - **`plan` and `spec` are demoted to 0.55** — they are records of intent, not current guidance - **`superseded` is demoted to 0.4** - **`adr` sits at 0.9** Labelling a standard as a `plan` buries it. Labelling a closed plan as `reference` promotes a work artifact into guidance an agent will act on. Labelling a coding standard as `reference` validates and then never resolves as a standard. Labelling a deferred finding as `reference` or `plan` hides it from the todo inventory. Pick what the document *is*, not what would rank best. Set `status: draft` when you have filled the mechanical keys but a human has not confirmed the semantic ones. Draft is demoted to 0.85, which degrades gracefully — far better than a confident `current` on metadata nobody checked. ## Example A file at `/payments/architecture.md` opening with `# Payments service` and no frontmatter. The catalog already has a `Payments` component owned by `payments-team`, whose source root is `src/Payments`. Verify the symbols first: ```bash sqlite3 .codegraph/codegraph.db \ "SELECT name, kind FROM nodes WHERE name IN ('PaymentProcessor','RefundHandler') AND kind<>'import';" ``` `PaymentProcessor` returns a class; `RefundHandler` returns nothing. So only the first is listed — the second would fail `KW-DOC-DRIFT-001`: ```yaml --- id: payments/architecture title: Payments service doc-type: architecture status: draft component: Payments source-root: src/Payments owner: payments-team last-reviewed: 2026-08-01 code-refs: - PaymentProcessor --- ``` `status: draft` because a human has not yet confirmed the component and source-root are right. `source-root` and `code-refs` appear together, satisfying the pairing invariant for an architecture document. ## Authoring a coding standard A coding standard is how one technology's code is written in this repository. It is not a `rule`, which governs the repository whatever the language, and it is not a `reference`. 1. Read the technologies list in ``. It is the same list as `ontology.technologies` in `.kyber-weave/kyber-weave.yml`. A value that is not on it is not a legal `technology`. 2. Write the document at `/standards//README.md`. The folder name and the `technology` value are the same string. That is the file the registry property `-coding-standard` points at. 3. Frontmatter is the six base keys plus `technology`. Do not set `component`. One standard covers every component the catalog lists, so naming one of them would claim a scope the document does not have. 4. `owner` must already be a catalog row. Add the row first when it is missing. 5. When the repository writes that stack and the technology is not declared yet, add it under `ontology.technologies` and run `kyber-weave docs init`. Init creates the folder and publishes the registry property. Do that only for a stack the repository actually uses. Do not add a technology, and do not add a doc-type, to silence a finding on a document that is not a standard. `technology` on any other doc-type fails `KW-DOC-SPEC-007`. A technology the repository has not declared fails `KW-DOC-SPEC-002`. A folder name that does not match the key fails `KW-DOC-SPEC-007`. `csharp` in the example has to already be declared. `status: draft` because a human has not confirmed the prose; the keys themselves are the mechanical part. ```yaml --- id: standards/csharp title: C# coding standard doc-type: coding-standard status: draft technology: csharp owner: payments-team last-reviewed: 2026-08-01 --- ``` The file is `/standards/csharp/README.md`. ## Setting up a new repository Before a governed corpus can exist, every agent and skill must be able to resolve the docs root. It is declared once, in the repository's root `AGENTS.md`, under a canonical heading — never hardcode it, never assume it. 1. **Read the root `AGENTS.md`** and look for the heading `## Repository Configuration & Paths Registry (Config Reg)`. 2. **If it exists, its declared values are authoritative.** Use `docs-root`, ``, and `` as `` and its fixed files everywhere in this skill. 3. **If it does not exist, ask the user for the documentation root.** It is a repository-relative directory, conventionally `docs`. Ask — where a new corpus lives is the user's choice, not an agent's guess. 4. **Update the root `AGENTS.md`** with the section, deriving the two fixed filenames from the root the user provided: ```markdown ## Repository Configuration & Paths Registry (Config Reg) Agents and skills should look up the following properties dynamically to find the relevant documentation and references for this repository: - ****: `docs` - ****: `/catalog.md` - ****: `/documentation-ontology.md` ``` 1. Read the document. Decide what it actually *is* → `doc-type`, from ``, not from memory. 2. Check the catalog for the `component` and `owner`. Add a row if missing. A coding standard uses `technology` instead of `component`. 3. Write the base keys. Use a real ISO date for `last-reviewed`. 4. Add type-specific keys from the ontology's required-key matrix. Honour the pairing invariant. 5. Verify every `code-refs` symbol resolves before listing it. 6. Run `kyber-weave docs validate .` and fix findings by rule id. 7. Run `kyber-weave docs drift .` and correct or drop unresolved symbols. Fix what a rule reports. Do not widen the ontology in `.kyber-weave/kyber-weave.yml` to make a failure disappear — that discards the guarantee the corpus exists to provide. ## After conformance: analyze, do not auto-rewrite When the repository supports documentation analysis, run it only after `docs validate` and `docs drift` are clean: ```bash kyber-weave docs integrity-check . ``` Treat duplicate, conflict, and terminology findings as evidence to review. Never merge, delete, or rewrite source documentation merely because analysis paired two claims. Exact duplicates are deterministic; conflicts and distinct term senses need a scope-aware human or agent verdict through `docs review export` / `docs review import`. Use `` only for intentional, reviewed cases and only with `duplicate`, `conflict`, `terminology`, or `all`. The tags are case-sensitive, balanced, non-nested, and cannot cross frontmatter or a `##` boundary. Malformed suppression is an operational error rather than a silent ignore. `docs glossary .` previews terminology proposals; `--write` merges them into the one configured glossary without rewriting source documents. The glossary remains a conformant `reference` document. Humans approve/reject sense rows, supply approved definitions and component/code scopes, update `last-reviewed`, and return the document to `current` after review. Do not invent a glossary doc-type or use sense-row status as document status. ## Never - Invent a `component` or `owner` that is not in the catalog - Add a `code-refs` symbol you have not verified - Guess the docs root during setup — ask the user and record the answer under the Config Reg heading in `AGENTS.md` - Change `doc-type` or `status` vocabularies to fit one document - Label a coding standard or a todo as `reference` to make validation pass - Copy a doc-type list into this skill — read `` - Set `status: current` on frontmatter you filled in without review - Backdate or forward-date `last-reviewed` — use the date it was actually reviewed - Auto-rewrite source prose from an unreviewed duplicate, conflict, or terminology candidate - Use ignore markup to hide a finding whose scope or evidence has not been reviewed ```` ## File: .apm/skills/kyber-docs-authoring/references/retrofit.md size: 6154 sha: c75cacf66502c23b9394ff3e729e2b2eee4a3c69 upstream: https://github.com/dpalfery/kyber-weave/blob/main/.apm/skills/kyber-docs-authoring/references/retrofit.md ````text # Retrofitting an existing documentation tree Converting a tree that has never been governed. The corpus starts at "every file fails `KW-DOC-SPEC-001`" — no frontmatter at all. Work in this order. Each step makes the next one's errors meaningful instead of drowned. ## 1. Establish the vocabulary first Nothing else can pass until the catalog — `/catalog.md`, or wherever `ontology.catalog-path` points — names the components and owners the documents will claim. `kyber-weave docs init` seeds the table; fill it from what the repository actually contains. One row per genuine unit of the system. Resist one row per document — a catalog with forty components is a list of files, and the closed vocabulary stops meaning anything. Owners come from `CODEOWNERS`, `git log`, or the team that answers pages. A placeholder owner is worse than an honest `unassigned` row, because it looks reviewed. ## 2. Mechanical keys, in bulk, as draft For every file, fill what needs no judgment: | Key | Derive from | |---|---| | `id` | Path below the docs root, without `.md`, e.g. `docgraph/architecture` — but see below when there are several roots | | `title` | The H1, or the filename in title case | | `last-reviewed` | Today, or `git log -1 --format=%ad --date=short ` | | `owner` | `CODEOWNERS` entry for the path, else the dominant committer | | `status` | **`draft`** — always, at this stage | | `doc-type` | Best guess from path and filename; see the heuristics below | #### Ids when documentation lives beside the code A repository whose `docs-root` names several roots — a module's `README.md` staying next to the code it describes — will have a `README.md` in most of them. The path below the root is then `readme` every time, and `KW-DOC-SPEC-006` fails the collision. Prefix with the root: `automation/readme`, `network_manager/readme`, `lab/readme`. The first root keeps bare ids, since it is the documentation tree proper and its paths are already distinct. Ids are permanent, so this is worth getting right in the first pass rather than renaming a corpus later. `status: draft` is the important one. It is honest, and retrieval demotes draft to 0.85 so a half-retrofitted corpus degrades gracefully instead of serving unreviewed metadata as current guidance. Promote to `current` only when a human has confirmed that file. ### doc-type heuristics | Signal in path or filename | Likely type | |---|---| | `adr/`, `decisions/`, `NNNN-*.md` | `adr` | | `runbook`, `playbook`, `oncall`, `incident` | `runbook` | | `architecture`, `design`, `hld`, `lld` | `architecture` | | `onboarding`, `getting-started`, `setup` | `onboarding` | | `requirements`, `prd`, `user-stories` | `requirements` | | `plan`, `roadmap`, `proposal` | `plan` | | `spec`, `rfc` | `spec` | | `standards//README.md` | `coding-standard` — the registry target; wins over the `standard` and directory-root `README.md` rows | | `todo/` | `todo` | | `policy`, `standard`, `convention` | `rule` or `governance`, except `standards//README.md` | | `README.md` at a directory root | `index`, except `standards//README.md` | | anything else that is reference material | `reference` | `reference` requires no extra keys, so a wrong guess there is recoverable when the document really is reference material. It is the wrong type for a coding standard or a todo: both validate, and neither is then found as what it is. The coding standard is `standards//README.md`, the file the registry property points at. Another file in that directory is not the standard; classify it on its own. The word `standard` on that README is not the `rule` heuristic. Guessing `architecture` is also not recoverable — it demands `component` and drags in the pairing invariant. ## 3. Validate and iterate ```bash kyber-weave docs validate . ``` Fix by rule id, most common first: - **`KW-DOC-SPEC-004`** — the catalog is missing a row, or the value is a typo. The diagnostic names the nearest match when one is plausible; trust it. - **`KW-DOC-SPEC-003`** — a type-specific key is missing. Either supply it, or reconsider whether the `doc-type` guess was right. A file that cannot name a `component` is usually not an `architecture` document. - **`KW-DOC-SPEC-006`** — duplicate `id`. Two files claimed the same slug; path-derived ids collide when two directories hold the same filename. Qualify with the parent directory. - **`KW-DOC-SPEC-005`** — `source-root` does not exist. Usually a stale path from a previous layout. Drop it, and drop `code-refs` with it. ## 4. Add code-refs last, selectively Only after the corpus validates clean. This is the step that needs real judgment, and it is worth doing on the documents that matter rather than all of them. Good candidates: architecture documents for a component, runbooks that operate a named service, references describing a public API. Poor candidates: onboarding prose, meeting notes, anything narrative. A document with no `code-refs` is completely valid — an empty claim is better than a false one. Then: ```bash kyber-weave docs drift . ``` Every `KW-DOC-DRIFT-001` means the symbol does not exist. Correct it or remove it; never silence it by widening configuration. ## 5. Promote out of draft Walk the corpus a component at a time. When someone who knows that component confirms the frontmatter is true, set `status: current` and `last-reviewed` to that date. A corpus that stays entirely `draft` still works — everything is retrievable, uniformly demoted. That is a stable resting place, not a failure. ## What not to do **Do not widen the ontology to make errors disappear.** Adding a doc-type to `.kyber-weave/kyber-weave.yml` because six files do not fit converts a closed vocabulary into a text field, which is the exact failure the ontology prevents. **Do not retrofit the archive.** `archive` is an excluded path segment by default because an archived plan is not current guidance. Leave it out of scope. **Do not fabricate `last-reviewed`.** A date nobody stood behind makes every freshness check meaningless. ```` ## File: .apm/skills/kyber-docs-authoring/references/rules.md size: 7254 sha: afaa1690ee81d29f501da8d9316a8f1f9efba39b upstream: https://github.com/dpalfery/kyber-weave/blob/main/.apm/skills/kyber-docs-authoring/references/rules.md ````text # Documentation rule reference Every rule `kyber-weave docs validate` and `docs drift` can emit, and what clears it. ## Schema — `docs validate` Needs no code index. ### `KW-DOC-SPEC-001` — no frontmatter, or unparseable The file has no `---` block, or the YAML inside it failed to parse. Clear it by adding the six base keys. If the block exists but fails, the usual causes are tab indentation, an unquoted value containing `:`, or a list written inline where `- ` items are expected. Quote any title containing a colon: ```yaml title: "Skills in your ALM: a governance playbook" ``` ### `KW-DOC-SPEC-002` — outside a closed vocabulary `doc-type` or `status` is not in the closed set, `last-reviewed` is not ISO `yyyy-MM-dd`, or `technology` names a stack the repository has not declared in `ontology.technologies`. `2026-8-1` fails; `2026-08-01` passes. `Current` fails on the value, not the case — comparison is case-insensitive, so the real cause is a value like `active` or `published` that simply is not in the set. An undeclared technology is this rule, not `KW-DOC-SPEC-007`. Add the stack under `ontology.technologies` and re-run `docs init` only when the repository writes that stack. Init creates `/standards//` and publishes `-coding-standard`. Do not add a technology to silence a finding on a document that is not a coding standard. ### `KW-DOC-SPEC-003` — required key missing A base key, or a key this `doc-type` requires. Before supplying it, check the `doc-type` is right: this rule fires most often on a document mislabelled `architecture` that cannot name a `component`. For `architecture` and `runbook` it also enforces the pairing invariant — `source-root` present without `code-refs`, or the reverse. ### `KW-DOC-SPEC-004` — value not in the catalog `component` or `owner` is not a row in the repository's one catalog — `/catalog.md`, or wherever `ontology.catalog-path` points. The diagnostic suggests the nearest catalog value when the edit distance is plausible. Two fixes, and picking the right one matters: if the value is a typo, correct the document. If the unit genuinely exists and is absent from the catalog, add the row. Do not retype the frontmatter to match an unrelated component just to pass. ### `KW-DOC-SPEC-005` — source-root does not exist The path is not a directory or file in the repository. Paths are repository-relative and forward-slashed — not relative to the document, and not absolute. ### `KW-DOC-SPEC-006` — bad reference Either two documents declare the same `id`, or `decided-by` / `supersedes` names an `id` no document declares. Ids are permanent and unique. When two collide, the newer document changes — renaming an established id breaks every reference to it. ### `KW-DOC-SPEC-007` — technology on the wrong document `technology` is set on a document that is not a `coding-standard`, or the value does not match the folder the file sits in. Clear a misplaced key by dropping it, or by making the document a `coding-standard` when that is what it is and the file is already the registry target, `/standards//README.md`. A folder mismatch on that file is cleared by changing the key to the folder's name. A file anywhere else is cleared by moving it there; changing its key does not make the registry resolve it. The folder name, the key, and `ontology.technologies` are one value. ## Drift — `docs drift` Requires a CodeGraph index at `.codegraph/codegraph.db` and the `sqlite3` CLI. ### `KW-DOC-DRIFT-001` — code-refs symbol unresolved The symbol is not in the index. Either it was renamed or deleted, or it never existed. When the index itself is missing, this is reported **once as critical** rather than per document. That is an environment problem, not a documentation problem: build or restore the index. Otherwise the diagnostic names the nearest surviving symbol when one is close. Update the reference, or drop it if the document no longer covers that code. Dropping is legitimate and often correct — a stale claim is worse than no claim. ### `KW-DOC-DRIFT-002` — api-endpoints route unmatched Route strings are exact, including method and full path template: ```yaml api-endpoints: - GET /api/me/usage ``` `/api/me/usage` alone fails. So does `GET /api/me/usage/` and a concrete `GET /api/me/123` where the indexed route is templated. ### `KW-DOC-DRIFT-003` — source-root indexed nothing Warning, not error. The path exists but the index holds no file beneath it. Either the path is wrong, or the index is stale — the tool cannot tell which, which is why it does not fail the build. ## Exit codes `docs validate` and `docs drift` exit non-zero on any **error**. Warnings and info do not gate. `--no-info` hides informational findings; `--format sarif` emits SARIF for code scanning. ## Analysis — `docs integrity-check` Analysis is advisory by default and never edits source documentation. ### `KW-DOC-ANALYSIS-001` — duplicate cluster Info for a pending near duplicate; Warning for a deterministic exact cluster or a high-confidence imported duplicate verdict. Confirm that the claims are substantively the same, not merely about the same topic. ### `KW-DOC-ANALYSIS-002` — potential conflict Info while pending; Error only after a high-confidence imported `conflict` verdict. Confirm that both claims cannot be true in the same scope and time before choosing a canonical source. ### `KW-DOC-ANALYSIS-003` — ambiguous terminology Warning when one informative term occurs in divergent contexts not fully accounted for by approved scoped glossary senses. Preview proposals with `docs glossary .`; do not rename terms automatically. ### `KW-DOC-ANALYSIS-004` — invalid ignore markup Operational Error. `` must be balanced, case-sensitive, non-nested, use `duplicate`, `conflict`, `terminology`, or `all`, and stay within frontmatter/`##` boundaries. Fix the markup; suppression never fails open. ### `KW-DOC-ANALYSIS-005` — CodeGraph unavailable Warning. Analysis continues with document relationships and bounded lexical search. Build or restore `.codegraph/codegraph.db` for code-neighborhood evidence. ### `KW-DOC-ANALYSIS-006` — embedding unavailable Warning in `prefer`, operational Error in `required`. Embeddings remain off by default and are never invoked unless the local cache path is safely ignored. Restore the loopback provider/safe cache, use `prefer` for lexical fallback, or use `off`. ### `KW-DOC-REVIEW-001` — invalid or stale verdict bundle Operational Error. Regenerate candidates from the current corpus and validate every candidate id, claim hash, evidence id, label, confidence, and glossary proposal. Import is atomic; one invalid item writes nothing. ### `KW-DOC-GLOSSARY-001` — invalid managed glossary Operational Error. Keep the document a conformant `reference`; use only `proposed`, `approved`, or `rejected` row status. Approved senses require a definition and at least one valid `component:` or `code-ref:` scope. `docs integrity-check --fail-on none|warning|error` controls finding gating. Operational errors always return non-zero. ```` ## File: README.md upstream: https://github.com/dpalfery/kyber-weave/blob/main/README.md ````text # Kyber-Weave **Agentic coding framework and meta-harness. Plan. Build. Tune.** Kyber-Weave turns coding assistants into a coordinated engineering team. It combines specialist agents and reusable skills with durable project knowledge, explicit delivery workflows, quality gates, and local observability. As a **meta-harness**, Kyber-Weave provides a shared workflow, knowledge, and quality layer across coding harnesses such as Claude Code, Codex, GitHub Copilot, Cursor, and OpenCode. People own the requirements, decisions, and approvals. Agents plan, build, test, review, and maintain the project documentation. ### Plan. Build. Tune. - **Plan** — turn an idea into a reviewed plan or specification grounded in project knowledge. - **Build** — coordinate specialists through implementation, tests, review, and documentation closeout. - **Tune** — inspect token and context costs, execution traces, and run comparisons to improve agent instructions and workflows. Kyber-Weave provides the framework around the coding harnesses your team already uses: a canonical agent team, portable skills, project knowledge, workflow orchestration, automated quality checks, and local evidence about agent runs. Start with the feature map below, or install Kyber-Weave to put the framework to work. ```bash curl -fsSL https://raw.githubusercontent.com/dpalfery/kyber-weave/main/scripts/install.sh | sh ``` Installs the latest release as self-contained binaries in `~/.local/bin` — no .NET runtime, no sudo, checksum-verified: the `kyber-weave` CLI, the `kyber-weave-mcp` server, and, from releases that publish it, the [`kyberdash`](docs/dash/README.md) observability binary. This one-liner and the Windows `.zip` are the only supported install paths: npm, Homebrew, and `dotnet tool` are not. Already installed? `kyber-weave update`, which also updates an installed KyberDash tray. [Install details →](docs/install.md) · [KyberDash adoption →](docs/dash/onboarding.md) **Windows users:** download the `.zip` archives from [Releases](https://github.com/dpalfery/kyber-weave/releases), verify the SHA-256 hash, and extract them to a directory on your PATH. See [Verifying a download](docs/install.md#verifying-a-download) and [Windows: unsigned binaries and SmartScreen](docs/install.md#windows-unsigned-binaries-and-smartscreen) for detailed guidance. > **This repository governs its own documentation.** Everything under [`docs/`](docs/) > carries conformant frontmatter and passes `kyber-weave docs validate` and `docs drift` > with zero findings. If the ontology were unusable, you would see it here first. --- ## The framework, in five parts Together, these parts cover the agent delivery loop—from durable project context, through coordinated implementation and review, to observable runs that teams can tune. 1. **[DocGraph (Kyber-Docs)](#feature-1--docgraph)** — Give agents durable, searchable project knowledge, and keep documentation aligned with the code. 2. **[ContextHygiene](#feature-2--contexthygiene)** — Check that skills and agent instructions are clear, portable, consistent, and safe to route. 3. **[Kyber-Squad](#feature-3--kyber-squad)** — Deploy one canonical team of agents and skills across 13 coding harnesses. 4. **[CI Pipelines](#feature-4--ci-pipelines)** — Catch quality and policy problems before a change reaches a pull request. 5. **[KyberDash](#feature-5--kyberdash)** — Understand local agent runs and tune context, tools, and workflows using execution evidence. --- ## Feature 1 — DocGraph Agents work better when project knowledge survives beyond a chat. DocGraph turns documentation into a **typed, owned, cross-referenced, searchable corpus** and checks that it stays aligned with the code. **The opinion.** Eleven closed doc-types, four statuses, a required-key matrix that varies by type, and a catalog that is the authoritative vocabulary for components and owners. A `component` cannot be invented one document at a time until nobody can say how many exist. [The ontology →](docs/documentation-ontology.md) **The enforcement.** `docs validate` checks conformance. `docs drift` resolves every documented symbol against a live code index, which catches the failure nothing else does: after a rename, **prose still reads correctly**. No linter, reviewer, or test notices — only resolution does. [Governance →](docs/docgraph/governance.md) **The payoff.** An in-memory graph that ranks on *declared identity* rather than word frequency, demotes plans and superseded documents so an agent is not handed a closed work artifact as current guidance, and returns budgeted excerpts that name what they omitted. [Retrieval →](docs/docgraph/retrieval.md) ```bash kyber-weave docs init . # scaffold config/catalog/ontology, protect local cache, deploy the skill kyber-weave docs validate . kyber-weave docs drift . kyber-weave docs integrity-check . # advisory duplicate/conflict/terminology findings kyber-weave docs export-graph . --out ./build/doc-graph ``` ### Adopting an existing tree `docs init` does the mechanical half — host config, the catalog that supplies the component and owner vocabularies, the ontology reference every diagnostic points at, and the narrow ignored cache path analysis needs before it can persist verdicts or vectors. It then deploys the **`kyber-docs-authoring` skill** through [APM](https://microsoft.github.io/apm), defaulting to `.agents/skills/` so every APM-supported client picks it up. The skill does the judgment half: choosing `doc-type`, verifying that `code-refs` symbols actually resolve, and retrofitting a whole tree as `status: draft` so a partially adopted corpus degrades gracefully rather than serving unreviewed metadata as current guidance. [Adoption guide →](docs/docgraph/onboarding.md) ### The MCP server `kyber-weave-mcp` is where the feature is actually consumed. Point any MCP client at it: | Tool | What it does | |---|---| | `docs_explore(query, cursor?)` | One leaf answer (preamble or `###` section) with confidence, a single source line, and an optional continuation cursor past 24,000 characters | | `docs_for_symbol(symbol)` | Reverse lookup: documents whose `code-refs` **formally claim** a symbol — not those that merely mention it | | `docs_analysis_candidates(kind, cursor, limit, charBudget)` | Capped, stable, read-only duplicate/conflict/terminology evidence with local cost metrics | | `docs_glossary(term)` | Capped, read-only lookup of managed term senses, scopes, and aliases | It is a separate binary from the CLI on purpose: JSON-RPC owns stdout and Spectre.Console also writes there, so separate entry points make stream corruption structurally impossible. [MCP runbook →](docs/docgraph/mcp-runbook.md) ### Documentation analysis and terminology `docs integrity-check` extracts line-addressable claims from paragraphs, list items, table rows, and code fences, then uses DocGraph and one-hop CodeGraph relationships before bounded lexical search. Exact duplicates are deterministic; potential conflicts and distinct term senses can be exported for agent review and imported as reusable, content-addressed verdicts. Source documents are never rewritten. ```bash kyber-weave docs integrity-check . kyber-weave docs review export . --out candidates.json kyber-weave docs review import . --in verdicts.json kyber-weave docs glossary . # preview kyber-weave docs glossary . --write # merge proposals into one reference document ``` Embeddings are off by default. When enabled, endpoints must resolve only to loopback, redirects are disabled, and no document text is sent unless the local SQLite cache is safely ignored. Default hybrid search avoids all-pairs work; `high-recall` is an explicit quadratic first pass outside the default latency target. [Analysis and review →](docs/docgraph/analysis.md) ### One external dependency, and it's optional `docs drift` and `docs export-graph` resolve symbols against a **CodeGraph** index at `.codegraph/co ````