@docsworth/cli 0.0.0-stage → 0.3.0

package/dist/web/assets/index-BGpAZzeM.css

@@ -0,0 +1 @@
+:root,:host{--dw-bg:#fbfbfa;--dw-surface:#fff;--dw-fg:#1d1d1b;--dw-muted:#6b6b66;--dw-line:#e4e3de;--dw-track:#ecebe6;--dw-accent:#2b5fa8;--dw-good:#2f7d4f;--dw-warn:#b7791f;--dw-bad:#b4442c;--dw-code:#f2f1ed;--dw-radius:8px;--dw-font:15px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif;--dw-mono:13px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;--lightningcss-light:initial;--lightningcss-dark: ;color-scheme:light}@media (prefers-color-scheme:dark){:root,:host{--dw-bg:#161615;--dw-surface:#1d1d1c;--dw-fg:#ecebe6;--dw-muted:#9a9993;--dw-line:#2c2c2a;--dw-track:#2a2a28;--dw-accent:#7aa7e8;--dw-good:#58b07c;--dw-warn:#d9a441;--dw-bad:#e0735a;--dw-code:#242422;--lightningcss-light: ;--lightningcss-dark:initial;color-scheme:dark}}*{box-sizing:border-box}.dw{background:var(--dw-bg);color:var(--dw-fg);font:var(--dw-font)}.dw a{color:var(--dw-accent);text-decoration:none}.dw a:hover{text-decoration:underline}.dw code{font:var(--dw-mono);background:var(--dw-code);border-radius:4px;padding:0 4px}.dw h1{margin:0 0 4px;font-size:24px;line-height:1.25}.dw h2{margin:28px 0 10px;font-size:17px}.dw-muted{color:var(--dw-muted)}.dw-num{font-variant-numeric:tabular-nums}.dw-header{border-bottom:1px solid var(--dw-line);background:var(--dw-surface);flex-wrap:wrap;align-items:center;gap:20px;padding:12px 20px;display:flex}.dw-brand{letter-spacing:-.01em;font-weight:650;color:var(--dw-fg)!important}.dw-nav{flex-wrap:wrap;gap:4px;display:flex}.dw-nav a{color:var(--dw-muted);border-radius:6px;padding:6px 10px}.dw-nav a[aria-current=page]{color:var(--dw-fg);background:var(--dw-track)}.dw-who{color:var(--dw-muted);align-items:center;gap:8px;margin-left:auto;font-size:13px;display:flex}.dw-main{max-width:1040px;margin:0 auto;padding:28px 20px 64px}.dw-sub{color:var(--dw-muted);margin:0 0 20px}.dw-save{flex-wrap:wrap;gap:8px;margin:0 0 20px;display:flex}.dw-save .dw-note{flex-basis:100%;margin:4px 0 0}.dw-tiles{grid-template-columns:repeat(auto-fit,minmax(160px,1fr));gap:12px;display:grid}.dw-tile{border:1px solid var(--dw-line);border-radius:var(--dw-radius);background:var(--dw-surface);padding:14px 16px}.dw-tile b{font-variant-numeric:tabular-nums;font-size:28px;display:block}.dw-tile span{color:var(--dw-muted);font-size:13px}.dw-table{border-collapse:collapse;width:100%}.dw-table th,.dw-table td{text-align:left;border-bottom:1px solid var(--dw-line);vertical-align:middle;padding:8px 6px}.dw-table thead th{text-transform:uppercase;letter-spacing:.04em;color:var(--dw-muted);font-size:12px;font-weight:600}.dw-scroll{overflow-x:auto}.dw-bar{background:var(--dw-track);border-radius:4px;max-width:240px;height:8px;margin-bottom:4px;overflow:hidden}.dw-bar>span{height:100%;display:block}.dw-good{background:var(--dw-good)}.dw-warn{background:var(--dw-warn)}.dw-bad{background:var(--dw-bad)}.dw-badge{border:1px solid var(--dw-line);color:var(--dw-muted);white-space:nowrap;border-radius:999px;padding:0 7px;font-size:12px;line-height:18px;display:inline-block}.dw-badge.ok{color:var(--dw-good);border-color:currentColor}.dw-badge.warn{color:var(--dw-warn);border-color:currentColor}.dw-badge.bad{color:var(--dw-bad);border-color:currentColor}.dw-meta{color:var(--dw-muted);flex-wrap:wrap;align-items:center;gap:8px;font-size:13px;display:flex}.dw-search{gap:8px;margin-bottom:20px;display:flex}.dw-search input{flex:1}.dw-results{gap:10px;margin:0;padding:0;list-style:none;display:grid}.dw-result{border:1px solid var(--dw-line);border-radius:var(--dw-radius);background:var(--dw-surface);padding:12px 14px}.dw-result h3{margin:0 0 4px;font-size:16px}.dw-result p{color:var(--dw-muted);margin:6px 0 0;font-size:14px}.dw-excluded{border-left:3px solid var(--dw-warn);background:var(--dw-surface);margin:6px 0;padding:8px 12px}.dw-page{max-width:760px}.dw-prose{line-height:1.65}.dw-prose pre{font:var(--dw-mono);background:var(--dw-code);border-radius:var(--dw-radius);padding:12px 14px;overflow-x:auto}.dw-prose pre code{background:0 0;padding:0}.dw-prose .dw-table-scroll{margin:12px 0;overflow-x:auto}.dw-prose table{border-collapse:collapse;font-size:14px;line-height:1.45}.dw-prose th,.dw-prose td{border:1px solid var(--dw-line);text-align:left;vertical-align:top;padding:6px 10px}.dw-prose th{background:var(--dw-surface);font-weight:600}.dw-prose .dw-align-center{text-align:center}.dw-prose .dw-align-right{text-align:right}.dw-prose h1{margin-top:24px;font-size:22px}.dw-prose h2{margin-top:24px}.dw-note{border:1px solid var(--dw-line);border-left:3px solid var(--dw-warn);background:var(--dw-surface);border-radius:6px;margin:12px 0;padding:10px 12px;font-size:14px}.dw-error{border-left-color:var(--dw-bad)}.dw input,.dw select,.dw textarea,.dw button{font:inherit;color:inherit}.dw input,.dw select,.dw textarea{background:var(--dw-surface);border:1px solid var(--dw-line);border-radius:6px;width:100%;padding:8px 10px}.dw textarea{font:var(--dw-mono);resize:vertical;min-height:220px}.dw button{background:var(--dw-fg);color:var(--dw-bg);cursor:pointer;border:0;border-radius:6px;padding:8px 14px;font-weight:550}.dw button.secondary{color:var(--dw-fg);border:1px solid var(--dw-line);background:0 0}.dw button:disabled{opacity:.45;cursor:not-allowed}.dw-form{gap:14px;max-width:760px;display:grid}.dw-form label{gap:6px;font-size:14px;font-weight:550;display:grid}.dw-form .dw-row{grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:12px;display:grid}.dw-preview{font:var(--dw-mono);white-space:pre-wrap;background:var(--dw-code);border-radius:var(--dw-radius);max-height:260px;padding:12px 14px;overflow:auto}.dw-graph{border:1px solid var(--dw-line);border-radius:var(--dw-radius);background:var(--dw-surface);width:100%;height:auto;display:block}.dw-graph line{stroke:var(--dw-line);stroke-width:1.2px}.dw-graph circle{stroke:var(--dw-surface);stroke-width:1.5px;cursor:pointer}.dw-graph circle.dim{opacity:.35}.dw-graph text{fill:var(--dw-muted);pointer-events:none;font-size:11px}.dw-legend{color:var(--dw-muted);flex-wrap:wrap;gap:14px;margin:10px 0;font-size:13px;display:flex}.dw-teams{flex-wrap:wrap;gap:12px;margin:-8px 0 16px;font-size:14px;display:flex}.dw-swatch{vertical-align:-1px;border-radius:50%;width:10px;height:10px;margin-right:6px;display:inline-block}

package/dist/web/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Docsworth</title>
+    <link rel="icon" href="data:," />
+    <script type="module" crossorigin src="/assets/index-8J-FUbb0.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BGpAZzeM.css">
+  </head>
+  <body class="dw">
+    <div id="app"></div>
+  </body>
+</html>

package/docs/format-spec.md

@@ -0,0 +1,349 @@
+# Docsworth format spec
+
+**Format version:** 1 · **License:** Apache-2.0
+
+This is the public contract between a knowledge repo and the tools that read it:
+`docsworth lint`, the MCP server, the skills compiler and the mirror. A repo that follows it
+can be linted, served to agents and compiled into skills by any implementation.
+
+## Repo layout
+
+```
+knowledge/
+  index.md                     # root map; agents read this first (required)
+  glossary.md                  # acronyms and codenames (recommended)
+  services/<name>/index.md     # type: service
+  runbooks/<slug>.md           # type: runbook
+  decisions/ADR-0001-<slug>.md # type: adr
+  onboarding/<role>.md         # type: guide
+  <anything>/…                 # any type; only the three directories above constrain it
+.knowledge/config.yaml         # org, repo, SLA window, mirror sources
+CODEOWNERS                     # or .github/CODEOWNERS or docs/CODEOWNERS
+```
+
+Every `.md` file under the knowledge root is a page, and every page has frontmatter.
+Inside the knowledge root, a directory whose name starts with a dot (an editor's
+`.obsidian/`, say) is skipped, with everything in it: its files are neither pages nor lint
+errors. The knowledge root itself is read whatever its name, and a file whose name starts
+with a dot is a page like any other.
+
+## Frontmatter
+
+At most 16 KB of YAML between the `---` lines; a page over that is reported by lint and
+not served (frontmatter runs to a few hundred bytes, and YAML parsing slows past linear
+on hostile input).
+
+```yaml
+---
+title: Deploying to production
+id: rb-deploy-prod            # required, stable, unique; lowercase letters, digits, dashes
+type: runbook                 # required: runbook | adr | service | guide | policy
+status: canonical             # required: canonical | draft | deprecated
+owner_team: platform          # required: team slug; CODEOWNERS must assign @<org>/platform
+last_verified: 2026-10-15     # required: YYYY-MM-DD, a real calendar date
+review_every: 90d             # required: <n>d | <n>w | <n>m | <n>y
+supersedes: [rb-deploy-legacy] # optional: ids this page replaces
+applies_to: [service:payments] # optional: free-form tags, matched exactly by search filters
+acl: internal                 # optional, default internal; or a team slug
+description: One sentence.    # optional; used in search and compiled skills
+---
+```
+
+Unknown fields produce a lint warning, never an error, unless the config lists them in
+`frontmatter.extra_fields`: keys a site generator keeps there, such as Docusaurus's
+`sidebar_position`.
+
+## Links
+
+Lint reads a page's links as CommonMark reads them. A `[x](y)` in code (a fenced or
+indented block, or a code span) or in HTML is no link. A reference link counts through its
+definition, and a definition no link uses is invisible.
+
+A relative link must resolve inside the repo. Under the knowledge root it must name a page
+(`.md`) or an attachment (a file with an extension, such as `diagram.png`). A link to a
+directory, or to a file with no extension, is an error: it names no page, and a route like
+Docusaurus's `/guides/setup` reads as one. Link the page itself (`guides/setup.md`).
+
+A root-relative link to an attachment (`/img/x.png`) that names no file of the repo's
+resolves in the directories `static_dirs` lists, as a docs site serves them (Docusaurus's
+`static/`). A page never does: pages are under the knowledge root.
+
+A root-relative link (`/docs`) is an error too when it names a directory or a file with no
+extension outside the knowledge root, and, read from the knowledge root as a docs site
+serves it (with or without a leading `docs/`, a number prefix, or a page's own `slug` or `id`),
+also names a page. The repo's file and the page both answer to it. Link the one you mean,
+with its extension.
+
+## Ownership
+
+- CODEOWNERS uses GitHub's semantics: the last matching rule wins. It supports anchored,
+  `*`, `**` and trailing-slash patterns, and `docs/*` matches direct children only.
+- The winning rule for a page's path must name **exactly one owner**, and that owner
+  must be a **team of the configured org** (`@<org>/<team>`). Individual owners (`@alice`,
+  emails), several owners, foreign-org teams and owner-less rules are all lint errors.
+  Individual ownership is banned deliberately: people change teams, and teams don't.
+- `owner_team` must equal that team's slug.
+
+## Review SLA
+
+Dates are date-only and compared as UTC calendar dates. The due date is
+`last_verified + review_every`:
+
+- `d` and `w` add fixed days.
+- `m` and `y` add calendar months or years, clamped to the end of the month
+  (2026-01-31 + 1m = 2026-02-28).
+
+States are evaluated in this order:
+
+| State | Condition |
+| --- | --- |
+| `unverified` | `last_verified` or `review_every` missing or invalid (this is also a lint error) |
+| `overdue` | today is after the due date (a lint warning on canonical pages) |
+| `due_soon` | at most `sla.due_soon_days` (default 14) days until due |
+| `fresh` | otherwise |
+
+The due date itself is still within SLA.
+
+## Citation gate
+
+A page is **citable** when all three hold:
+
+1. `status: canonical`.
+2. Its SLA state is `fresh` or `due_soon`.
+3. Its ownership resolves as above.
+
+The gate is fixed by this spec; configuration cannot widen it.
+
+- **`search`:** returns only citable pages. Matching pages that aren't citable are
+  listed separately as `excluded`, each with a reason such as "past review date (due
+  2026-10-30), owned by platform". Agents can then say what was excluded instead of
+  silently missing it.
+- **`read`:** returns any visible page, with `citable`, `flags` and `gate_reason`.
+
+## ACL
+
+`acl` narrows which callers the **MCP server serves** a page to:
+
+- **`internal`:** anyone the server serves at all.
+- **A team slug:** only members of `@<org>/<slug>`.
+
+In a page the caller can see, a reference to a page they can't see (a link in any form,
+a URL, or its path in text) reads `[restricted page]`. A page that doesn't load counts as
+one they can't see, and so does a link to a path under the knowledge root that is no page
+at all: relative, or, with `github.repo` set, a GitHub URL into the repo on any branch.
+
+Links are also read as a docs site serves them. A link to a hidden page's route reads
+`[restricted page]` too: by its `slug`, by an `id` other than its file name, by its path
+without number prefixes, or by its file's stem. So does a link without an extension that
+names no page, file or directory in the repo (`/guides/gone`), for every reader. With
+`site_url` set, a URL on the docs site counts as the route it names. A route written in
+plain text, not as a link, is served as written.
+See [security-model.md](security-model.md#the-one-read-path).
+
+**`acl` isn't confidentiality.** GitHub has no per-file read permissions, so anyone with
+read access to the knowledge repo can read every file in it. Keep confidential content
+in a separate repository whose GitHub permissions match its audience. See
+[security-model.md](security-model.md).
+
+## Runbook sections
+
+For the skills compiler, a runbook has these `##` sections. The heading match is
+case-insensitive:
+
+| Section | Holds |
+| --- | --- |
+| `## When to use` | Triggers: alerts, symptoms, requests. This becomes the skill's description. |
+| `## Steps` | Numbered actions with exact commands. |
+| `## Checks` | How to tell it worked. |
+| `## Rollback` | How to undo it, or why it can't be undone. |
+
+A canonical runbook missing any of these still lints. It's reported and skipped by
+`docsworth compile`.
+
+## Compiled skills
+
+`docsworth compile` writes `skills/<id>/SKILL.md` in the Agent Skills format: `name` and
+`description` frontmatter, plus string-valued `metadata`:
+
+```yaml
+metadata:
+  source_id: rb-deploy-prod
+  source_path: knowledge/runbooks/deploy-production.md
+  source_sha256: <sha256 of the source file>
+  owner_team: platform
+  last_verified: 2026-10-15
+  review_every: 90d
+  review_due: 2027-01-13
+  compiled_at: 2026-11-02
+  stale: "false"
+```
+
+A skill is **stale** when its source page changed (`source_sha256`), was re-verified
+(`last_verified`), stopped being canonical, or was deleted. `docsworth compile --check` exits 1
+on stale skills. `--mark-stale` sets `stale: "true"` and prefixes the description with
+`[STALE: …]`. Runbooks with a non-`internal` ACL are compiled only with
+`--include-restricted`.
+
+Compiling removes only skills whose `generator` is `docsworth`. A skill whose generator
+is `agent-kb`, the pre-release name, is rewritten if its page still compiles. If it
+remains, `--check` reports it, but it's never removed or marked, because that name now
+belongs to another publisher: delete it by hand.
+
+## Polish
+
+`propose_edit` with `polish: true` proposes a restructure or rewording that must not
+change what the page says. The agent sends the new `body` (what `read` returns as
+`content`, rewritten), and the server keeps the frontmatter. Before any branch is
+created, the server compares the current page with the proposed one and refuses
+(`invalid`, naming the changes it saw, up to eight) unless all of these are unchanged.
+Pages over 64 KB, before or after, aren't polished.
+
+| Compared | How |
+| --- | --- |
+| Frontmatter | byte for byte |
+| Code order | all code, fenced and inline, in reading order; and the code under each heading both versions have (ATX or setext, in a quote or a list item or neither, subsections included) stays under it. Headings match as written, apart from spacing and closing `#`s, and a repeated heading matches by its occurrence while both versions repeat it as often. Sections without code may move, and headings may be added or reworded |
+| Code blocks, fenced (backticks or tildes) and indented (four spaces or a tab), in quotes and list items too | content, as CommonMark reads the page's block structure: a line is code only where CommonMark makes it code, and leaves code where CommonMark ends the block (a quote or list item that ends, an outdented line). Each line loses its containers' markers and up to the fence's own indentation, so moving a block into a list item or a quote is a polish but shifting its code isn't. Trailing spaces count (`\ ` ends a shell line differently from `\`), and so does a fence's info string (```` ```text ```` stays inert where ```` ```mermaid ```` draws a diagram), added, dropped or changed. The fence's characters and line endings are ignored, and a fenced block without an info string equals an indented one with the same lines |
+| Reference definitions | read for the links that use them, and otherwise treated as invisible, as they render: nothing inside one counts as page text. A line is a definition only if CommonMark takes it as one: its destination in `<…>`, or bare with no space or control character and its parentheses balanced. Anything else renders, and is compared, as text. Code spans in a label, destination or title count as written, and labels match as CommonMark matches them (`[STRASSE]` uses `[straße]: …`). A page isn't polished at all if a definition-like line is indented by a tab or four spaces, has a label or title spanning lines, or follows an indented or `===` line: whether it renders depends on block structure this check doesn't model. Use `edits` there |
+| HTML comments (outside code) | as a multiset, and kept out of every other row: a fact moved into a comment has left the page a reader sees. A comment inside a code block is code. A comment block (a line starting `<!--`, to its `-->`) holds text, as CommonMark reads it: code or a definition inside it isn't one. A comment opened mid-paragraph that wraps a code block makes the page unpolishable |
+| Raw HTML (tags, processing instructions, declarations, CDATA, and any opener such as `<!--`, `<?` or `<div`, closed or not) | none may be added: an unclosed opener hides everything after it. A page that already has raw HTML (outside code), or a control character U+0000 to U+0004 (the check's own marks), isn't polished at all: where a tag sits decides what it hides (`<span hidden>…</span>`), which only a renderer could compare. Use `edits` there |
+| Unusual characters | a polish may not add an invisible character (zero-width, soft hyphen, an ASCII control), even one the page already has or a letter from a script the page doesn't use (a Cyrillic `о` in an English word). Numeric entities and `&amp; &lt; &gt; &quot; &apos; &nbsp; &minus; &plus;` are decoded first, for this and for numbers and negation words. Other named entities are compared as written, each with what follows it: a polish adds, removes or moves none |
+| Inline code, link targets | as multisets: order may change, nothing added or dropped. Each link is also compared with the text that shows it, as written apart from spacing, and its title, so links may move but not trade destinations or change what they say on hover. Link targets are inline and reference links (resolved through their definitions), autolinks (`<https://…>`, `<ops@example.com>`), bare URLs, emails and `www.` links, and HTML `href`/`src`, quoted or not. Punctuation after a bare URL isn't part of it, as GFM links it (`?!.,:*_~;` and an unbalanced `)`). A `](` that doesn't parse as a link is compared as written, to the end of its line |
+| Struck-through text (`~~…~~`, `<del>`, `<s>`) | as a multiset, so striking an instruction out is a change |
+| Task-list items (`- [ ]`, `1. [x]`) | each box with its task's text, as a multiset: tasks may move with their boxes, but ticking one, or moving a tick to another task, says a different step is done. A task's text stays as written |
+| Words with digits (`TLSv1.2`, `IPv4`, `RHEL8`, `p99`) | as a multiset |
+| Numbers (digits of any script) | each with its sign and the word after it (`-5 minutes`, `.5 seconds`, `3 retries`, `5-minute`) as a multiset, so swapping two numbers with different units is caught. Every run of digits in the visible text is compared too, whatever it's attached to (`on-c3`). A plural is the same unit. Case counts (`5 MB` isn't `5 Mb`, `500MB` isn't `500Mb`), except that a unit word of three letters or more may be capitalised (`5 Minutes`). Ordered-list markers aren't numbers where they surely start a list item (a `1`, after a blank line or a heading, or after list items at the same indentation), so renumbering a list is a polish; `retry\n3. times` is paragraph text in CommonMark, and its `3` is compared. The word may sit on the next line of the same paragraph; bold and italics are ignored |
+| Negation and modal words | the count of each, in any case: not, never, no, must, should, cannot, can't, don't, doesn't, won't, shouldn't, mustn't, isn't, aren't, only, without, unless, except, nor, none, neither, always, and every other "n't" (didn't, wasn't, …) counted together, counted twice: with emphasis markers taken out and with them read as breaks, since an unclosed `**` is text in CommonMark (`no**t` isn't `not`) |
+
+Because the frontmatter and every link target are unchanged, a polished page stays as
+valid as it was.
+
+On a page that links to pages the caller can't see (shown as `[restricted page]` in
+`read`), `propose_edit` takes only `edits`, and no polish. A whole `body` or `content`
+written from the redacted view would overwrite or drop those links, and a polish
+refusal would name them. An edit that writes `[restricted page]` is refused too. An
+`append` is taken there: it adds to the end of the page as it is on the default branch,
+so nothing written from the redacted view goes back into it.
+
+## New pages (`draft_page`)
+
+`draft_page` opens a draft PR that adds one page, on a `docsworth/draft/<id>-…` branch.
+
+- **The server names it.** Its id is `<prefix>-<slug>-<12 hex>` and its file
+  `<slug>-<12 hex>.md`, where the slug comes from the title and the hex is random. A name
+  the caller chose could be aimed at a page they can't see, and "already exists" would
+  then say it is there. Owners can rename it in the PR before merging.
+- **Where it lands.** The type's directory (`runbooks/`, `services/<name>/index.md`,
+  `guides/`, `policies/`) or a `dir` under the knowledge root. CODEOWNERS must assign
+  `owner_team` there, so the page lints. Where the plain name is another team's, the
+  server tries `<owner_team>-<slug>-<12 hex>` (id `<prefix>-<owner_team>-<slug>-<12 hex>`)
+  in the same directory, so rules on file names (`runbooks/payments-*`) route the page to
+  its team; if that isn't the team's either, `draft_page` refuses and names the directory.
+  ADRs are written by hand.
+- **What it holds.** `status: draft` (never citable until its owners make it canonical),
+  `last_verified` today, `review_every: 90d`, the caller's one-line title and optional
+  description, and `acl` `internal` or a team the caller is on. A `source_url` becomes a
+  first line, `> Captured from <url> on <date>.`
+
+**How it's checked.** Besides its own tests, the guard is fuzzed against CommonMark's
+reference parser (commonmark.js): pages are mutated at random, and no pair may change a
+code block, inline code, a link (its text, target or title, and GitHub's bare-URL
+autolinks), a digit or a negation word as commonmark.js renders it while the guard
+reports nothing (`test/polish-fuzz.test.ts`, and `scripts/fuzz-polish.ts` for long
+runs). Where CommonMark implementations disagree (a tab inside a link's or a
+definition's parentheses), the page is refused rather than read one way.
+
+**Not detected.** This is a structural check, not proof that the meaning is unchanged.
+It doesn't see a renamed service or team in prose, a command written as plain prose,
+a changed word that isn't a number's unit, a
+number spelled out (`five`), two numbers with the same unit trading places (`wait 5
+minutes`, `retry after 10 minutes`), steps without code put in another order, code
+moved across headings that were reworded in the same polish, a negation moved to
+another clause, or a reworded sentence that now means something else. That's why the PR goes to the owner team like any other, titled
+`polish(<id>): <title>`, with a body that lists what the guard compared and asks for
+the diff to be read.
+
+## Mirror namespace
+
+Mirrored pages live under `mirror.out_dir` (default `.knowledge/mirror/`), never under
+the knowledge root, and are never citable. Each file carries a `mirror:` frontmatter block
+(source, native id, url, `last_edited`, versions, `owner_team` from a `team-<slug>` or
+`owner-<slug>` label, labels, acl). Each source and space directory also holds
+`_scores.json` and `_report.json`. Pages with read restrictions in the source, and their
+descendants, are never written, and the report lists them by native id only.
+
+**Serving the mirror** (`mirror.serve: true`, off by default, and not yet recommended:
+on the benchmark it was neutral on answer questions but just missed its bar on gate
+questions). The MCP server then lists
+matching mirrored pages in search under `mirrored`, at most 3, apart from `results`, each
+with `citable: false`, its source URL and last edit. `read` takes a `mirror:` id and
+returns the page with `citable: false` and `flags: ["mirrored"]`. Filters on page type
+or `applies_to` leave mirrored pages out; `owner_team` applies to them.
+
+- **Audience:** each space's `acl`, by the same rule as pages. A hidden and an unknown
+  mirror id answer alike, and a team space's page taints the session like a team page.
+- **Links:** in a mirrored page someone can see, links to a repo page they can't see
+  read `[restricted page]` as they do in repo pages (by URL, say). In a page someone can
+  see, mirrored or from the repo, links to a mirrored
+  page they can't see read `[restricted page]` (and don't count toward ranking): markdown links (any title form, nested or escaped brackets),
+  bare URLs, and Confluence's linked-title form. A link is matched by the page it
+  names, so a relative path, a URL without its title slug, `?pageId=`, a Confluence
+  tiny link (`/wiki/x/…`), or a Notion id in any form is caught too, also encoded,
+  broken across lines or with markup inside, as for repo pages.
+- **Ranking:** each audience gets its own index, so ranking, snippets and counts never
+  draw on a page outside that audience.
+- **What is served:** only files one of this user's mirror runs wrote and that are
+  unchanged since, read through the records in the state directory. A new run is picked
+  up without a restart. An `out_dir` that resolves outside the repo serves nothing, with
+  a warning.
+
+## Config (`.knowledge/config.yaml`)
+
+```yaml
+format: 1
+knowledge_root: knowledge     # a directory in the repo, named relative to it: not . or .., not absolute, not in .git or .knowledge; a trailing slash is ignored
+static_dirs: [website/static] # optional: directories a docs site serves at its root; lint reads /img/x.png there too
+site_url: https://docs.example.com/docs/  # optional: where a docs site serves the pages; redaction reads a URL under it as a route
+github:
+  org: acme                 # required: team owners resolve to @acme/<team>
+  repo: acme/knowledge      # optional: makes GitHub the ACL authority; enables PR tools
+  default_branch: main      # optional: otherwise read from GitHub
+  api_url: https://ghe.example.com/api/v3   # optional: GitHub Enterprise Server
+sla:
+  due_soon_days: 14
+usage_log: true             # page-id-only read log for the owner digest
+frontmatter:
+  extra_fields: [sidebar_label, sidebar_position]   # keys a site generator keeps in frontmatter; lint doesn't warn on them
+audit_log:                  # attributed audit log; off unless enabled
+  enabled: true
+  dir: /var/lib/docsworth/audit   # optional; default $XDG_STATE_HOME/docsworth/<repo>-<hash>/audit
+  include_queries: false    # search text is not recorded unless true
+  required: false           # true: nothing is answered or changed unless its event is written first (see security-model.md)
+  retention_days: 365
+policy:                     # org policy; every default keeps v0.1 behaviour
+  admins: kb-admins         # lint: CODEOWNERS must make this team own the config and CODEOWNERS
+  tools:                    # per-tool allowlists (search, read, list, stale, propose_edit, verify, draft_page); an empty list disables a tool for everyone
+    propose_edit: { teams: [platform, payments] }
+  writes: enabled           # disabled: propose_edit, verify and draft_page are not offered
+  require_human_approval: false   # true: Claude Code asks on every write call
+  include_stale: allowed    # denied: search never returns gated pages inline
+  identity_cache_seconds: 300     # team-membership cache for reads (30-3600)
+audit_http:                 # pro: ship each event to a collector (SIEM) as it happens
+  url_env: DOCSWORTH_AUDIT_URL    # env var with the https:// URL (http only on loopback)
+  token_env: DOCSWORTH_AUDIT_TOKEN
+  required: false
+skills:
+  out_dir: skills
+mirror:
+  out_dir: .knowledge/mirror
+  serve: false              # true: search lists matching mirrored pages under `mirrored` (never citable)
+  sources:
+    - kind: confluence
+      base_url: https://acme.atlassian.net
+      spaces: [{ key: ENG, acl: internal }]
+    - kind: notion
+      root_page_ids: []     # empty: everything shared with the integration
+      acl: internal
+digest:
+  slack_webhook_env: SLACK_WEBHOOK_URL
+  team_webhooks: { security: SLACK_WEBHOOK_SECURITY }
+```

package/package.json

@@ -1,6 +1,77 @@
 {
   "name": "@docsworth/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Git-native knowledge layer for coding agents: team-owned pages, review SLAs, a citation gate, and an MCP server agents read for free.",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/docsworth/docsworth.git"
+  },
+  "homepage": "https://github.com/docsworth/docsworth#readme",
+  "bugs": {
+    "url": "https://github.com/docsworth/docsworth/issues"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "bin": {
+    "docsworth": "dist/cli.js"
+  },
+  "exports": {
+    "./host": {
+      "types": "./dist/core/host.d.ts",
+      "default": "./dist/core/host.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/pro",
+    "plugin",
+    "templates",
+    "docs/format-spec.md"
+  ],
+  "workspaces": [
+    "packages/ui",
+    "packages/web",
+    "packages/extension"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prebuild": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "tsc -p tsconfig.build.json && npm run build -w @docsworth/web && node scripts/copy-web.mjs",
+    "postbuild": "node -e \"require('node:fs').chmodSync('dist/cli.js', 0o755)\"",
+    "docsworth": "tsx --conditions=docsworth-source src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run test:core && npm run test:web",
+    "test:core": "npm run typecheck && vitest run",
+    "test:web": "npm test -w @docsworth/ui && npm test -w @docsworth/web && npm test -w @docsworth/extension",
+    "test:watch": "vitest",
+    "bench:search": "tsx scripts/bench-search.ts",
+    "live:github": "tsx scripts/live/github.ts",
+    "live:quickstart": "tsx scripts/live/quickstart.ts",
+    "live:skills": "tsx scripts/live/skills.ts",
+    "live:governance": "tsx scripts/live/governance.ts",
+    "live:polish": "tsx scripts/live/polish.ts",
+    "live:serve": "tsx scripts/live/serve.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "commander": "^15.0.0",
+    "commonmark": "^0.31.2",
+    "yaml": "^2.9.1",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@mixmark-io/domino": "2.2.0",
+    "@types/commonmark": "0.27.10",
+    "@types/node": "^22.20.5",
+    "entities": "3.0.1",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2",
+    "vitest": "^5.1.0"
+  }
+}

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "docsworth",
+  "version": "0.3.0",
+  "description": "Team-owned, verified engineering knowledge for Claude Code: an MCP server that cites only canonical pages inside their review SLA, plus skills to draft, update and verify runbooks through PRs.",
+  "author": { "name": "docsworth" },
+  "license": "Apache-2.0",
+  "keywords": ["knowledge", "runbooks", "docs-as-code", "mcp", "codeowners"]
+}

package/plugin/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "docsworth": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/bin/docsworth-mcp.mjs"]
+    }
+  }
+}

package/plugin/bin/docsworth-mcp.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// Launches the Docsworth MCP server for Claude Code.
+//   DOCSWORTH_KNOWLEDGE_DIR  local clone of the knowledge repo (default: the current project)
+//   DOCSWORTH_BIN            a local `docsworth` executable to use instead of the published
+//                            package: an absolute path, needed to use Docsworth pro, which an
+//                            npx-run CLI can't see
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+
+// The npm package to run. `agent-kb` on npm belongs to another publisher and nobody owns the
+// bare `docsworth`: never fall back to either. Kept equal to PUBLISHED_PACKAGE in
+// src/core/version.ts by test/package-name.test.ts.
+const PUBLISHED_PACKAGE = "@docsworth/cli@^0.3";
+
+// The repo reaches the server in the environment, never on the command line, which Windows
+// runs through cmd.exe: a path would split at a space there, and what follows an `&` would
+// run. A leading `~` is the home directory, as a shell would read it.
+const dir = resolve((process.env.DOCSWORTH_KNOWLEDGE_DIR || process.cwd()).replace(/^~(?=$|[\\/])/, () => homedir()));
+const env = { ...process.env, DOCSWORTH_KNOWLEDGE_DIR: dir };
+
+// npx runs in the home directory, so a .npmrc in the project can't send `@docsworth` to
+// another registry. A local CLI runs in the repo, which one too old to read the variable
+// serves by default.
+const [cmd, args, cwd] = process.env.DOCSWORTH_BIN
+  ? [process.env.DOCSWORTH_BIN, ["mcp"], dir]
+  : ["npx", ["-y", PUBLISHED_PACKAGE, "mcp"], homedir()];
+
+// Windows starts npx, and npm's .cmd shims, only through cmd.exe: each word is quoted, so the
+// `^` of the range and a space in DOCSWORTH_BIN arrive as they are. Quotes don't stop cmd.exe
+// expanding %VAR% (or !VAR!), and a quote or a line break would end the word, so a
+// DOCSWORTH_BIN with any of them is refused, not misread. No Windows path has them but %, !.
+const windows = process.platform === "win32";
+if (windows && /[%!"\x00-\x1f]/.test(cmd)) {
+  process.stderr.write(`docsworth: DOCSWORTH_BIN (${JSON.stringify(cmd)}) has a %, !, " or control character, which cmd.exe would read as part of a command; use a path without them\n`);
+  process.exit(1);
+}
+const child = windows
+  ? spawn([cmd, ...args].map((w) => `"${w}"`).join(" "), { stdio: "inherit", shell: true, cwd, env })
+  : spawn(cmd, args, { stdio: "inherit", cwd, env });
+child.on("error", (e) => {
+  process.stderr.write(`docsworth: couldn't start ${cmd}: ${e.message}\n`);
+  process.exit(1);
+});
+child.on("exit", (code, signal) => process.exit(code ?? (signal ? 1 : 0)));
+for (const s of ["SIGINT", "SIGTERM"]) process.on(s, () => child.kill(s));

package/plugin/skills/draft-runbook/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: draft-runbook
+description: Turn an incident write-up, postmortem, Slack thread or pasted notes into a draft runbook in the team's knowledge repo, opened as a draft pull request for the owning team. Use when someone says "write a runbook for this", "turn this incident into a runbook", or pastes an incident timeline and asks for a procedure.
+---
+
+# Draft a runbook
+
+The goal is a draft PR that adds one runbook in the Docsworth format. It's owned by one
+team and has the four sections the skills compiler needs. Nothing merges without that
+team's review.
+
+## 1. Gather the source
+
+Work only from material the user gave you: pasted text, a file path, or an incident
+document they point to. If a command or step isn't in the source, don't invent it. Leave
+a `TODO(owner):` line where the source is silent.
+
+## 2. Check for an existing page first
+
+Use the Docsworth `search` tool twice: once with the incident's symptoms, once with the
+service name. Pass `include_stale: true` both times, so you also see excluded pages.
+
+- If a runbook already covers this procedure, stop. Use the `update-after-incident`
+  skill instead and propose edits to that page. A second runbook for the same thing is
+  how wikis rot.
+- If a gated or overdue page covers it, say so and name the owning team.
+
+## 3. Work out the owner
+
+The owner is a team, never a person. Read the service page with the `read` tool (for
+example `svc-<service>`) and use its `owner_team`. If several teams are plausible, ask
+the user. You don't pick the file name: `draft_page` names the page and places it where
+CODEOWNERS gives it to that team, as `<team>-<slug>` where CODEOWNERS routes runbooks by
+prefix.
+
+## 4. Write the body
+
+`draft_page` writes the frontmatter itself (`status: draft`, the owner, today's
+`last_verified`, `review_every: 90d`), so write only the markdown after it, in this
+shape. The skills compiler needs all four sections.
+
+```markdown
+# <Imperative title, e.g. Drain the webhook backlog>
+
+## When to use
+- <the alert, symptom or request that triggers this>
+
+## Steps
+1. <one action per step, with the exact command in backticks>
+
+## Checks
+- <how to tell it worked>
+
+## Rollback
+- <how to undo it, or why it cannot be undone>
+```
+
+## 5. Open the draft PR with `draft_page`
+
+Call the Docsworth `draft_page` tool. Don't use git or `gh` for this: the tool opens the
+PR from its own `docsworth/draft/` branch and never writes to the default branch.
+
+- `type`: `runbook`
+- `title`: the imperative title
+- `owner_team`: the team from step 3
+- `description`: one sentence, what this procedure does
+- `body`: the markdown from step 4
+- `source_url`: the incident document's link, if the user gave one
+- `reason`: the incident it comes from, every `TODO(owner):` you left, and the service
+  it applies to (`applies_to: [service:<name>]`), which the owners add in review
+
+If it refuses because CODEOWNERS gives the directory to another team, tell the user what
+it said and ask which directory the team owns; pass that as `dir` and call it again.
+
+Report the PR URL and the page's path, and list every `TODO(owner):` you left.