docspack 0.1.0 → 0.1.1

package/README.md

@@ -1,59 +1,179 @@
+<div align="center">
+
+<a href="https://docspack.dev"><img src="https://docspack.dev/logo.png" width="72" height="72" alt="docspack" /></a>
+
 # docspack
 
-**Local, version-locked documentation for AI agents.**
+Local, version-locked documentation packages for AI agents, indexed in SQLite and served over MCP.
+
+[![npm](https://img.shields.io/npm/v/docspack.svg)](https://www.npmjs.com/package/docspack)
+[![downloads](https://img.shields.io/npm/dm/docspack.svg)](https://www.npmjs.com/package/docspack)
+[![license](https://img.shields.io/npm/l/docspack.svg)](./LICENSE)
+[![node](https://img.shields.io/node/v/docspack.svg)](https://nodejs.org)
+[![types](https://img.shields.io/badge/types-TypeScript%20strict-blue.svg)](https://www.typescriptlang.org)
+[![status](https://img.shields.io/badge/status-experimental-orange.svg)](https://github.com/docspack/docspack/releases)
+
+[Website](https://docspack.dev) ·
+[Documentation](https://docspack.dev/llms.txt) ·
+[GitHub](https://github.com/docspack/docspack) ·
+[Releases](https://github.com/docspack/docspack/releases)
+
+</div>
+
+---
+
+> **Publishing documentation for your own library?** You want `docspack init`, which
+> scaffolds a documentation package. This README is mostly about consuming them.
+
+> **Just want your agent to read the docs?** Three lines: install a docs package, run
+> `docspack sync`, and paste one sentence into `AGENTS.md`. Jump to [Quick start](#quick-start).
+
+## Overview
+
+An AI coding agent answers from one of three places: its training data, which is frozen at
+some past version; a docs site it fetches, which is whatever the vendor publishes today; or
+nothing at all. None of those is the version in your lockfile.
 
-Documentation ships as npm packages (`@stripe/docspack`, `@docspack-community/jira`).
-`docspack` indexes the ones your project depends on into a global SQLite database with
-FTS5, and serves them to agents over MCP — offline, instant, and matched to the exact
-versions you installed.
+docspack closes that gap by making documentation an ordinary npm dependency. A documentation
+package (`@stripe/docspack`, `@docspack-community/jira`) holds Markdown split into chunks plus
+a manifest describing them, and its version tracks the library's. `docspack sync` indexes the
+ones this project depends on into one SQLite database per machine, and `docspack ask` answers
+from that index — offline, bounded, and matched to what you actually installed.
 
-```bash
+The mental model: **publish → sync → ask.**
+
+## Features
+
+- **Version-locked** — answers come from the docs package resolved in your lockfile, never a
+  newer or older one. The index may hold five versions of a library; a project sees only its own.
+- **Offline by construction** — `sync`, `ask`, `search` and `list` make no network requests.
+  They read `node_modules` and a local SQLite file.
+- **Bounded responses** — 3 chunks and 3,000 tokens by default, counted from the manifest
+  before content is returned, so a query cannot overrun its budget.
+- **No server, no resident context** — every agent already has a shell. One line in `AGENTS.md`
+  is the whole setup, and nothing runs when nobody is asking.
+- **MCP when you want it** — `docspack mcp` serves the same index over the Model Context
+  Protocol, returning identical text, for clients that prefer a declared tool.
+- **No native modules** — the index uses `node:sqlite` from the standard library.
+
+## Installation
+
+```sh
+npm  install -D docspack
+pnpm add     -D docspack
+yarn add     -D docspack
+```
+
+Requires Node 22.5 or newer.
+
+## Quick start
+
+```sh
+# 1. Add a documentation package, the same way you add any dependency
 pnpm add -D @acme/docspack
+
+# 2. Index every docs package this project depends on
 npx docspack sync
-npx docspack search "webhook signature"
+
+# 3. Ask it something
+npx docspack ask "how do I verify a webhook signature"
 ```
 
-Give an agent access with one command:
+Then give the agent access by pasting these two lines into `AGENTS.md` or `CLAUDE.md`:
 
-```bash
+```
+Run `docspack ask "<question>"` for documentation on this project's
+dependencies. It answers from the installed versions.
+```
+
+That is the entire integration. No server to start, no per-client configuration.
+
+<details>
+<summary>Using MCP instead</summary>
+
+```sh
 claude mcp add docspack -- npx -y docspack mcp
 ```
 
-The MCP server exposes `query_local_docs` (`query`, optional `packageFilter`), returns the
-best-ranked chunks, and caps a response at 3,000 tokens. It also exposes
-`record_docs_problem`, the equivalent of `docspack feedback add` — it appends to a local file
-and cannot send anything anywhere.
+The server exposes `query_local_docs` (`query`, optional `packageFilter`), returns the
+best-ranked chunks and caps a response at 3,000 tokens. It also exposes `record_docs_problem`,
+the equivalent of `docspack feedback add` — it appends to a local file and cannot send
+anything anywhere.
+
+</details>
 
 ## Commands
 
+Reading:
+
 ```
 docspack sync                Index the docs packages this project depends on
-docspack search <query>      Full-text search the local index
+docspack ask <question>      Answer from the local index — the command to give an agent
+docspack search <query>      Same index, formatted for a human reading the terminal
 docspack list                Show this project's docs packages and their index state
 docspack verify              Check the docs still describe the code you installed
 docspack feedback <sub>      Record documentation problems: add, list, submit, remove
-docspack mcp                 Run the MCP server over stdio
-docspack build [source]      Generate a docs package for publishing
+docspack mcp                 Serve the index over MCP instead, as a long-lived process
 docspack sources             List curated sources that `docspack build` can fetch
 ```
 
-## Authoring
+Authoring:
+
+```
+docspack init                Scaffold a documentation package, then build and check it
+docspack build [source]      Generate the .llms/ payload for publishing
+docspack doctor              Check a package the way the indexer and a reviewer would
+docspack preview <query>     Answer a query from the local package, as an agent would
+```
+
+Run `docspack --help` for every flag.
+
+## Authoring a documentation package
+
+```sh
+npx docspack init                                  # scaffold, build and check in one step
+npx docspack build --from ./docs                   # Markdown, split at headings
+npx docspack build --openapi ./openapi.json        # one chunk per operation
+npx docspack build stripe                          # from a project's public llms.txt
+```
+
+`build` writes `.llms/manifest.json`, `.llms/chunks/*.md` and an `llms.txt` table of contents,
+ready for `npm publish`. `docspack doctor --strict` checks the result the way the indexer and
+a reviewer would.
 
-```bash
-npx docspack build --from ./docs --name @acme/docspack --pkg-version 1.4.0
-npx docspack build --openapi ./openapi.json --name @acme/docspack --pkg-version 1.4.0
+Manifests validate against <https://docspack.dev/schema/v1.json>.
+
+## Recording documentation problems
+
+An agent holds the documentation, the installed library and a failing program at the same
+moment — a signal that today evaporates. `docspack feedback add` captures it locally:
+
+```sh
+npx docspack feedback add --chunk @acme/docspack@1.4.0/api-auth \
+  --kind drift --evidence "client.setKey is not exported; setApiKey is"
 ```
 
-Writes `.llms/manifest.json`, `.llms/chunks/*.md` and an `llms.txt` table of contents,
-ready for `npm publish`.
+Claims must be falsifiable. `drift` must name the identifier; `incorrect` and `missing` must
+carry `--expected`, `--actual` and `--repro`. There is deliberately no kind for "this page is
+confusing".
+
+**Nothing is transmitted, and nothing can be** — docspack contains no code that sends a report
+anywhere. `docspack feedback submit` prints a prefilled GitHub issue URL for vendors who opted
+in from their own `package.json`, and a human decides whether to open it.
+
+## Status
 
-## Requirements
+Pre-1.0 and versioned accordingly: minor releases may change behaviour. The package
+specification is the part most worth depending on, and it is documented at
+<https://docspack.dev/schema/v1.json>.
 
-Node 22.5 or newer — the index uses `node:sqlite` from the standard library, so there is
-no native module to build.
+## Related packages
 
-Full documentation: https://github.com/docspack/docspack
+| Package | Description |
+| --- | --- |
+| [`@docspack/registry`](https://www.npmjs.com/package/@docspack/registry) | Curated llms.txt sources for bootstrapping docs packages. |
+| [`@docspack/docspack`](https://www.npmjs.com/package/@docspack/docspack) | docspack's own documentation, shipped as a docs package. |
 
 ## License
 
-MIT
+MIT — see [LICENSE](./LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docspack",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Local, version-locked documentation packages for AI agents, indexed in SQLite and served over MCP.",
   "keywords": [
     "ai",
@@ -14,7 +14,7 @@
     "context",
     "cli"
   ],
-  "homepage": "https://github.com/docspack/docspack#readme",
+  "homepage": "https://docspack.dev",
   "bugs": "https://github.com/docspack/docspack/issues",
   "repository": {
     "type": "git",
@@ -37,8 +37,9 @@
   "files": [
     "bin",
     "dist",
+    "src",
     "README.md",
-    "src"
+    "LICENSE"
   ],
   "engines": {
     "node": ">=22.5.0"
@@ -47,7 +48,7 @@
     "@modelcontextprotocol/sdk": "1.30.0",
     "turndown": "7.2.4",
     "zod": "4.4.3",
-    "@docspack/registry": "^0.1.0"
+    "@docspack/registry": "^0.1.1"
   },
   "devDependencies": {
     "@types/node": "26.2.0",