Docsworth
Team-owned docs for coding agents: review SLAs, a citation gate, and PR-only writes.
التثبيت
أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: .cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).
@docsworth/cliclaude mcp add docsworth -e 'DOCSWORTH_KNOWLEDGE_DIR=<DOCSWORTH_KNOWLEDGE_DIR>' -e 'GITHUB_TOKEN=<your github_token>' -- npx -y @docsworth/cli@0.3.2 mcp
{
"mcpServers": {
"docsworth": {
"command": "npx",
"args": [
"-y",
"@docsworth/cli@0.3.2",
"mcp"
],
"env": {
"DOCSWORTH_KNOWLEDGE_DIR": "<DOCSWORTH_KNOWLEDGE_DIR>",
"GITHUB_TOKEN": "<your github_token>"
}
}
}
}
متغيرات البيئة
DOCSWORTH_KNOWLEDGE_DIRإلزامي A local clone of the knowledge repository to serveGITHUB_TOKENسري Your GitHub token, for your identity and team access when the repository names one in github.repo (otherwise GH_TOKEN, then `gh auth token`)
التوثيق
مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.
المحتويات
Docsworth
Your runbooks, owned, verified and executable by every agent.
Docsworth is a git-native knowledge layer for coding agents. Pages are markdown in your own repo. Every page has exactly one owning team in CODEOWNERS and a review date. Agents reach the pages through an MCP server that cites only pages a team has verified within their review window. Everything else comes back as excluded: past review date, owned by platform, so the gap is visible rather than silently stale.
- Customer-owned git. Plain markdown in your GitHub repo; no lock-in, and it reviews like code.
- Enforced ownership.
docsworth lintfails CI unless each page's CODEOWNERS rule names exactly one team, and that team matches the page. - Citation gate. Only
canonicalpages inside their SLA are citable. The gate is fixed and not configurable. - PR-only writes. Agents propose edits and owners verify pages through pull requests. Nothing writes to the default branch.
- Polish without drift. Agents can restructure and reword a page as a
polishPR. The server refuses one that changes a code block, inline code, a link, a number or a negation word. The check reads pages as CommonMark does, and is fuzzed against CommonMark's reference parser: no miss in 1.5 million mutated pages. - Mirror, don't migrate. Read-only Confluence and Notion mirror, scored for
freshness, ownership and overlap with canonical pages. With
mirror.serve, agents see it as context they may never cite. - Skills compiler. Verified runbooks compile into
SKILL.mdfiles that agents execute. - Agents read free. No metering on reads.
5-minute quickstart
You need Node 22.12+, a GitHub repo for your knowledge, and Claude Code.
Install the CLI from npm. It's @docsworth/cli: agent-kb and docsworth there are
not ours.
npm install --global @docsworth/cli
cd your-knowledge-repo
docsworth init --team platform # config, CODEOWNERS, root map, a guide
docsworth lint . # 3 pages, 0 errors, 0 warnings
init reads your GitHub org from the repo's remote; in a repo without one yet, add
--org <your-org>. Add --ci for a workflow that lints every PR and every push to main.
Install the Claude Code plugin from this repo's marketplace:
claude plugin marketplace add docsworth/docsworth
claude plugin install docsworth@docsworth
The plugin runs the published CLI through npx. To run your own install instead (Docsworth
pro needs it), set DOCSWORTH_BIN in Claude Code's environment to its absolute path, such
as $(npm prefix -g)/bin/docsworth.
Start Claude Code in the knowledge repo, or set DOCSWORTH_KNOWLEDGE_DIR to its path, then ask
"How do I add a page to our knowledge base?". The answer cites
guide-writing-pages.
The server uses your own GitHub identity (GITHUB_TOKEN, GH_TOKEN or gh auth
token), so your repo and team permissions decide what you see.
Adopting existing docs
Docs you already have, a Docusaurus site's say, become pages without moving a URL. With
them under knowledge/ (or knowledge_root in .knowledge/config.yaml set to where they
are), after init:
docsworth adopt --team docs # the frontmatter each page lacks, as drafts
docsworth lint .
adopt gives each page the fields it lacks, and keeps everything it has:
- a page's
idis its own, else its file name, a Docusaurus number prefix removed, so the site's URLs stay where they are; - its owner comes from CODEOWNERS, else
--team; - a route link like
/guides/setupbecomes a relative link to the file,../guides/setup.md; - keys a site generator keeps, such as
sidebar_position, go infrontmatter.extra_fields; - images a site serves from its
static/directory (/img/x.png) get a hint naming thestatic_dirsline to add, after which lint reads them there.
A page or link it can't settle stays as it is, listed, and lint fails it until it's fixed
by hand: a category index like guides/index.md, two pages with one file name, a link to
nothing. --dry-run reports and writes nothing.
Adopted pages are drafts, so agents cite none of them yet. Once a team has read its pages:
docsworth verify knowledge/guides # canonical, verified today
Both commands only change files. Commit them and open a pull request, which CODEOWNERS sends to the owning team.
If the site stays up, set site_url (https://docs.example.com/docs/) in the config.
Then a link to a page someone can't see reads [restricted page] by its full URL on the
site, as it already does by its route. A link without an extension that names nothing
reads [restricted page] too: a route can't be told from a hidden page's.
Commands
| Command | What it does |
|---|---|
docsworth init [dir] | Scaffold config, CODEOWNERS, knowledge/index.md, a glossary and a writing guide. Never overwrites. |
docsworth lint [dir] | Frontmatter, CODEOWNERS ownership, links and duplicate ids. Exit 1 on errors; overdue pages only warn. |
docsworth adopt [dir] [--team t] | Existing pages get the frontmatter they lack, as drafts, and route links become .md links; lists what it can't settle. Working tree only; --dry-run. |
docsworth verify <paths…> | The draft or canonical pages under the paths become canonical, verified today. Working tree only; --dry-run. |
docsworth stale [dir] | Pages past their review SLA or without a team owner. |
docsworth coverage [dir] [--html f] | Percentage team-owned and percentage verified within SLA, by team; optional static dashboard (--html, pro). |
docsworth digest [dir] [--send] | Pro. Weekly per-team digest: due, overdue, most read by agents. Prints unless --send. |
docsworth mcp [dir] | The MCP server (stdio): search, read, list, stale, propose_edit, verify, draft_page. Without dir, it serves DOCSWORTH_KNOWLEDGE_DIR, else the current directory. |
docsworth serve [dir] | The web app at 127.0.0.1:4747 (overview, search, pages, teams, a link graph, capture), and the same server over HTTP for it and the browser extension, behind a token kept in your state directory (--print-token, --rotate-token, --allow-extension <id>). |
docsworth compile [dir] [--check] | Pro. Canonical runbooks → skills/<id>/SKILL.md; --check exits 1 on drift. |
docsworth mirror [dir] | Pro. Read-only Confluence and Notion mirror into .knowledge/mirror, scored. |
docsworth promote <mirror-id> --owner-team t | Pro. Draft PR copying a mirrored page into knowledge/. |
docsworth audit [dir] [--bench d] | Pro. Audit report: coverage, stale and overlapping pages, DIY accuracy score. |
docsworth bench run [dir] | Pro. Citation benchmark: Claude on the raw wiki vs. the ungated layer vs. the gated layer. |
Commands marked pro are Docsworth pro's (@docsworth-pro/pro); without it installed, each exits 2 and
says so. --as-of YYYY-MM-DD evaluates SLAs on a fixed date, for reproducible reports.
How it works
knowledge/*.md ──lint (CI)──▶ CODEOWNERS: one team per page
│
├─▶ docsworth mcp ──▶ ACL filter (your GitHub teams) ──▶ citation gate ──▶ agent
│ propose_edit / verify ──▶ PR only
├─▶ docsworth compile ──▶ skills/<id>/SKILL.md
Confluence / Notion ──docsworth mirror──▶ .knowledge/mirror (scored, never citable) ──promote──▶ PR
- docs/format-spec.md: the format contract.
- docs/security-model.md: ACLs, writes and prompt injection.
Note that
aclnarrows what agents are served; it isn't confidentiality inside one repo. - docs/enterprise/: for a security review. The two modes, what is inherited from GitHub, a responsibility matrix, a data-flow diagram and a pre-filled questionnaire. Vulnerabilities: SECURITY.md.
- docs/rollout.md: org-wide rollout with managed settings.
Try it on the example
npm install
npm run docsworth -- --as-of 2026-11-02 lint examples/acme
npm run docsworth -- --as-of 2026-11-02 coverage examples/acme --html coverage.html
npm run mirror-fixture -w @docsworth-pro/pro -- examples/acme
npm run docsworth -- --as-of 2026-11-02 audit examples/acme --out audit
Browser extension
A side panel for Chrome (and other Chromium browsers) over docsworth serve. From the panel
you can search and read pages, or suggest an addition to one.
Saving what you read.
- From the menu: on any page, right-click and choose Save page to Docsworth, or select some text and choose Save selection to Docsworth.
- From the panel: Save this page and Save the selection read the tab you opened the panel from with the toolbar button.
- In Gmail: a Save to Docsworth button beside a thread's subject.
The page's main content or the selection arrives as markdown, with its headings, links, code blocks and tables, and without what the page hides or its navigation. The panel first shows the pages that may already cover it, each with Add the capture here, then a draft page filled from it, with its source. Nothing is written until you open the PR. The extension isn't in the Chrome Web Store yet: build it and load it unpacked.
npm run build -w @docsworth/extension
- In Chrome, open
chrome://extensions, turn on Developer mode, choose Load unpacked and pickpackages/extension/dist. Note the extension's id. - Start the server so it answers the extension:
docsworth serve --allow-extension <the extension's id> - Open the extension's options (its toolbar icon, then Options). Paste the link
serveprinted, then choose Connect. Chrome forgets the token when it quits; paste it again then (docsworth serve --print-tokenshows it).
What it can reach and keep, and why the token is safe from pages: docs/security-model.md.
Gmail checklist. Gmail's markup isn't a contract. The tests run against Gmail-shaped fixtures, so check these by hand, signed in, after loading a new build:
- [ ] An open thread shows Save to Docsworth beside its subject. The inbox list shows none.
- [ ] Clicking it opens the side panel with "From Gmail", related pages, and a draft whose title is the subject and whose body is the expanded messages, each with its sender's name and no addresses.
- [ ] Moving to another thread moves the button with it. Clicking it while a draft is open shows "Another capture is waiting" rather than replacing the draft.
- [ ] A thread with collapsed messages captures only the expanded ones: expand what you want in the draft first.
Development
The one verify target is npm test: a typecheck and the vitest suite, including an MCP
end-to-end test and the ACL matrix. It also builds, packs and installs the real tarball.
See AGENTS.md, and docs/releasing.md for releases.
Status
v0.3. What's in it, and what hasn't been verified against the real thing yet, is in the release notes for 0.3.0, 0.3.1 and 0.3.2.
License
Apache-2.0. Docsworth pro (@docsworth-pro/pro: the mirror connectors, digest, reports,
the SIEM audit sink and the benchmark) is a separate package under its own, proprietary
licence.
الأسئلة الشائعة
ما هو Docsworth؟
Team-owned docs for coding agents: review SLAs, a citation gate, and PR-only writes.
كيف أثبّت Docsworth؟
يعمل على جهازك. في Claude Code: claude mcp add docsworth -e 'DOCSWORTH_KNOWLEDGE_DIR=<DOCSWORTH_KNOWLEDGE_DIR>' -e 'GITHUB_TOKEN=<your github_token>' -- npx -y @docsworth/cli@0.3.2 mcp. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.
هل يحتاج Docsworth إلى مفتاح API؟
نعم. يتطلب DOCSWORTH_KNOWLEDGE_DIR, GITHUB_TOKEN، وتضبطها في إعداداته.
هل Docsworth مفتوح المصدر؟
نعم. شيفرته متاحة على GitHub بترخيص Apache-2.0.
من يصون Docsworth؟
ينشره docsworth. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.
من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.