docspack 0.2.0 → 0.4.0

package/dist/help.js

@@ -0,0 +1,342 @@
+import { AGENTS_SNIPPET, FEEDBACK_SNIPPET } from "./snippet.js";
+const LIMIT = 3;
+const MAX_TOKENS = 3000;
+const QUERY_OPTIONS = [
+    ["-p, --package <s>", "only packages whose name contains this text"],
+    ["--limit <n>", `maximum chunks to return (default ${LIMIT})`],
+    ["--max-tokens <n>", `token ceiling for the result set (default ${MAX_TOKENS})`],
+    ["--all", "search the whole store, not just this project"],
+];
+export const COMMANDS = [
+    {
+        name: "sync",
+        summary: "Index the docs packages this project depends on",
+        group: "core",
+        usage: "docspack sync [options]",
+        options: [["--force", "re-index packages already in the store"]],
+        detail: [
+            "Reads node_modules and indexes every @vendor/docspack and @docspack-community/<name>",
+            "package this project declares. Makes no network requests.",
+        ],
+        examples: ["docspack sync", "docspack sync --force"],
+    },
+    {
+        name: "ask",
+        summary: "Answer from the local index — the command to give an agent",
+        group: "core",
+        usage: 'docspack ask "<question>"',
+        options: QUERY_OPTIONS,
+        detail: [
+            "Answers from the installed versions, in the Markdown an agent should read. Exits 0 when",
+            "chunks were returned, 3 when a docs package is installed but not indexed, and 4 when",
+            "everything installed is indexed and nothing matched.",
+        ],
+        examples: [
+            'docspack ask "how do I verify a webhook signature"',
+            'docspack ask "webhook signature" --package stripe --limit 5',
+        ],
+    },
+    {
+        name: "search",
+        summary: "Same index, formatted for a human reading the terminal",
+        group: "core",
+        usage: "docspack search <query>",
+        options: QUERY_OPTIONS,
+        detail: ["The same index and ranking as `ask`, printed as a list of hits with a preview."],
+        examples: ["docspack search webhook signature"],
+    },
+    {
+        name: "list",
+        summary: "Show this project's docs packages and their index state",
+        group: "core",
+        usage: "docspack list",
+        options: [],
+        examples: ["docspack list", "docspack list --json"],
+    },
+    {
+        name: "verify",
+        summary: "Check the docs still describe the code you installed",
+        group: "core",
+        usage: "docspack verify [options]",
+        options: [["--package-dir <d>", "verify one package directory instead of what is installed"]],
+        detail: [
+            "Compares the identifiers the chunks name against what the documented libraries declare,",
+            "read from their .d.ts files. Nothing you depend on is imported or executed. The libraries",
+            'come from the manifest\'s "documents", or from the docspack key when the manifest has none.',
+            "Exits 1 when anything was reported.",
+        ],
+        examples: ["docspack verify", "docspack verify --json"],
+    },
+    {
+        name: "feedback",
+        summary: "Record documentation problems: add, list, submit, remove",
+        group: "core",
+        usage: "docspack feedback <add|list|submit|remove> [options]",
+        options: [
+            ["--chunk <id>", "add: the chunk the problem is in"],
+            ["--kind <k>", "add: drift, incorrect or missing"],
+            ["--evidence <text>", "add: the claim, in one line"],
+            ["--expected <text>", "add: what the documentation led you to expect"],
+            ["--actual <text>", "add: what happened instead"],
+            ["--repro <code>", "add: code that demonstrates it"],
+            ["-p, --package <s>", "submit: only findings from packages matching this text"],
+            ["--all", "remove: every recorded finding"],
+        ],
+        detail: [
+            "Writes to .docspack/feedback.jsonl in this project. Nothing is transmitted: docspack",
+            "contains no code that can send a report anywhere.",
+            "",
+            "`drift` must name the identifier that drifted. `incorrect` and `missing` must carry",
+            "--expected, --actual and --repro, so a claim that cannot show its work cannot be",
+            "recorded. `submit` prints a prefilled GitHub issue URL for a human to open and file.",
+        ],
+        examples: [
+            'docspack feedback add --chunk @acme/docspack@1.4.0/api-auth --kind drift --evidence "client.setKey is not exported; setApiKey is"',
+            "docspack feedback list",
+            "docspack feedback submit",
+            "docspack feedback remove <fingerprint>",
+        ],
+    },
+    {
+        name: "mcp",
+        summary: "Serve the index over MCP instead, as a long-lived process",
+        group: "core",
+        usage: "docspack mcp",
+        options: [],
+        detail: [
+            "Serves the same index over the Model Context Protocol, for clients that prefer a tool",
+            "definition to a shell command. `query_local_docs` returns exactly what `ask` prints.",
+            "stdout is the protocol channel, so nothing else is written to it.",
+        ],
+        examples: ["docspack mcp"],
+    },
+    {
+        name: "sources",
+        summary: "List curated sources that `docspack build` can fetch",
+        group: "core",
+        usage: "docspack sources",
+        options: [],
+        examples: ["docspack sources", "docspack build hono --name @docspack-community/hono"],
+    },
+    {
+        name: "init",
+        summary: "Scaffold a documentation package, then build and check it",
+        group: "authoring",
+        usage: "docspack init [name] [options]",
+        options: [
+            ["-y, --yes", "skip the prompts and use flags plus detected defaults"],
+            ["--dry-run", "print the file tree and write nothing"],
+            ["--mirror <id|url>", "bootstrap from a published llms.txt"],
+            ["--community", "scaffold under @docspack-community"],
+            ["--template <t>", "full (default) or minimal"],
+            ["--mode <m>", "standalone or in-repo"],
+            ["--no-workflow", "skip the release workflow"],
+            ["--no-build", "scaffold only"],
+            ["--name <name>", "package name, e.g. @acme/docspack"],
+            ["--pkg-version <v>", "package version"],
+            ["--from <dir>", "directory of Markdown to package"],
+            ["--openapi <file>", "OpenAPI JSON to package"],
+            ["--out <dir>", "where to scaffold (default: ./docspack)"],
+            ["--force", "overwrite files that already exist"],
+        ],
+        detail: [
+            "Reads the surrounding project first — name, version, a docs directory, an OpenAPI",
+            "document, the git remote, the license — and proposes a package built from what it found.",
+        ],
+        examples: [
+            "docspack init",
+            "docspack init --name @acme/docspack --from ./docs --yes",
+            "docspack init --mirror hono --community --yes",
+        ],
+    },
+    {
+        name: "build",
+        summary: "Generate the .llms/ payload for publishing",
+        group: "authoring",
+        usage: "docspack build [source] [options]",
+        options: [
+            ["--from <dir>", "directory of Markdown to package"],
+            ["--openapi <file>", "OpenAPI JSON to package, one chunk per operation"],
+            ["--name <name>", "package name, e.g. @acme/docspack"],
+            ["--pkg-version <v>", "package version"],
+            ["--out <dir>", "output directory (default: the current directory)"],
+            ["--pages <n>", "maximum documents to fetch from a remote source"],
+            ["--max-chunk-tokens <n>", "split a section above this size (default 800)"],
+            ["--min-chunk-tokens <n>", "pack adjacent sections up to this size before splitting"],
+            ["--documents <p>", "library this package documents, repeatable: acme@1.4.0"],
+        ],
+        detail: [
+            "Splits each document at ## headings, then ###, then paragraphs, until every chunk fits",
+            "the budget. --min-chunk-tokens packs the other way first, merging adjacent sections up to",
+            "the budget: use it for generated reference, where a heading is a field name and one chunk",
+            "per heading is hundreds of chunks too small to answer anything.",
+            "",
+            "With no flags, settings are read from the docspack key of the package.json in --out.",
+        ],
+        examples: [
+            "docspack build",
+            "docspack build --from ./docs --name @acme/docspack --pkg-version 1.4.0",
+            "docspack build --from ./reference --min-chunk-tokens 400 --max-chunk-tokens 900",
+            "docspack build --openapi ./openapi.json",
+        ],
+    },
+    {
+        name: "doctor",
+        summary: "Check a package the way the indexer and a reviewer would",
+        group: "authoring",
+        usage: "docspack doctor [options]",
+        options: [
+            ["--strict", "treat structural warnings as failures"],
+            ["--pedantic", "--strict, and fail on prose style as well"],
+            ["--package-dir <d>", "the package to inspect (default: .)"],
+        ],
+        detail: [
+            "Errors are packages that will not index. Warnings are packages that will index and",
+            "retrieve badly. Prose style is a note unless --pedantic, because writing by hand is not a",
+            "reason to block a first publish. Exits 1 when the package is not ready to publish.",
+        ],
+        examples: ["docspack doctor", "docspack doctor --strict", "docspack doctor --json"],
+    },
+    {
+        name: "preview",
+        summary: "Answer a query from the local package, as an agent would",
+        group: "authoring",
+        usage: "docspack preview <query> [options]",
+        options: [
+            ["--package-dir <d>", "the package to read (default: .)"],
+            ["--limit <n>", `maximum chunks to return (default ${LIMIT})`],
+            ["--max-tokens <n>", `token ceiling for the result set (default ${MAX_TOKENS})`],
+        ],
+        detail: [
+            "Indexes the package in memory and answers through the same ranking and token budget an",
+            "agent gets. Nothing is published, installed, or written to the global store.",
+        ],
+        examples: ['docspack preview "how do I authenticate"'],
+    },
+    {
+        name: "eval",
+        summary: "Measure retrieval against a set of questions",
+        group: "authoring",
+        usage: "docspack eval <queries.json> [options]",
+        options: [
+            ["--package-dir <d>", "the package to read (default: .)"],
+            ["--limit <n>", `chunks per answer, the window a hit must fall in (default ${LIMIT})`],
+            ["--max-tokens <n>", `token ceiling for each answer (default ${MAX_TOKENS})`],
+            ["--min-hit-rate <n>", "exit 1 below this percentage of questions answered"],
+        ],
+        detail: [
+            "The evaluation set is a JSON array of questions and the chunk ids that would answer them:",
+            "",
+            '  [{ "query": "how do I verify a webhook signature", "expect": "webhooks-signing" },',
+            '   { "query": "rate limits", "expect": ["rate-limits", "errors"] }]',
+            "",
+            "Reports hit rate, top-1 rate and mean answer size — the numbers that settle the chunk",
+            "budget, which no structural check can see. With --min-hit-rate it gates a publish on",
+            "retrieval quality the way `doctor --strict` gates it on structure.",
+        ],
+        examples: [
+            "docspack eval ./eval/queries.json",
+            "docspack eval ./eval/queries.json --min-hit-rate 90",
+            "docspack eval ./eval/queries.json --limit 1 --json",
+        ],
+    },
+];
+const GLOBAL_OPTIONS = [
+    ["--store <path>", "Use a different index"],
+    ["--cwd <dir>", "Run in a different directory"],
+    ["--json", "Machine-readable output"],
+    ["-q, --quiet", "Only print errors"],
+    ["-h, --help", "Show this help, or a command's help"],
+    ["-v, --version", "Show the version"],
+];
+export function findCommandHelp(name) {
+    return COMMANDS.find((command) => command.name === name);
+}
+const WIDTH = 21;
+function row([flag, description]) {
+    return `  ${flag.padEnd(WIDTH)} ${description}`;
+}
+/** The page one command prints for `docspack <command> --help`. */
+export function commandHelpText(command) {
+    const blocks = [
+        `docspack ${command.name} — ${command.summary}`,
+        "",
+        "Usage",
+        `  ${command.usage}`,
+    ];
+    if (command.detail !== undefined) {
+        blocks.push("", ...command.detail.map((line) => (line.length === 0 ? "" : `  ${line}`)));
+    }
+    if (command.options.length > 0) {
+        blocks.push("", "Options", ...command.options.map(row));
+    }
+    blocks.push("", "Global options", ...GLOBAL_OPTIONS.map(row), "", "Examples", ...command.examples.map((example) => `  ${example}`), "");
+    return blocks.join("\n");
+}
+/**
+ * The global page. It lists the commands and the options that apply to all of them, and points
+ * at the per-command pages for the rest — one list of every flag of every command was what made
+ * the flags unfindable in the first place.
+ */
+export function globalHelpText(storePath, notIndexed, noMatch) {
+    const group = (which) => COMMANDS.filter((command) => command.group === which)
+        .map((command) => row([command.name, command.summary]))
+        .join("\n");
+    return `docspack — local, version-locked documentation for AI agents
+
+Usage
+  docspack <command> [options]
+  docspack <command> --help      every flag that command takes
+
+Commands
+${group("core")}
+
+Authoring
+${group("authoring")}
+
+How it works
+  Documentation ships as npm packages named @vendor/docspack or
+  @docspack-community/<name>. Add them to package.json, run \`docspack sync\`, and
+  every chunk is indexed into a shared SQLite database with FTS5. Agents query
+  that index locally: no network, no scraping, always the installed version.
+
+Giving an agent access
+  Any agent with a shell can run \`docspack ask\`, so one line in AGENTS.md or
+  CLAUDE.md is the whole setup — no server, no per-agent configuration, and
+  nothing resident when nobody is asking:
+
+${AGENTS_SNIPPET.map((line) => `    ${line}`).join("\n")}
+
+  Add the block below as well if you want the agent to record documentation
+  problems it runs into. It writes to a local file; nothing is sent:
+
+${FEEDBACK_SNIPPET.map((line) => `    ${line}`).join("\n")}
+
+  \`docspack mcp\` serves the same index over the Model Context Protocol for
+  clients that prefer a tool definition. Both return identical text.
+
+Global options
+${GLOBAL_OPTIONS.map(row).join("\n")}
+
+  The default index is ${storePath}.
+
+Exit codes
+  \`ask\` and \`search\` answer with an exit code a script can branch on:
+
+    0  chunks were returned
+    ${notIndexed}  nothing matched, and a docs package is installed but not indexed —
+       run \`docspack sync\`
+    ${noMatch}  nothing matched, and everything installed is already indexed
+    1  the command failed; 2  the command was used wrongly
+
+Examples
+  npx docspack sync
+  npx docspack ask "how do I verify a webhook signature"
+  npx docspack init
+  npx docspack doctor --strict
+  npx docspack preview "how do I authenticate"
+  npx docspack eval ./eval/queries.json --min-hit-rate 90
+  npx docspack feedback submit
+`;
+}
+//# sourceMappingURL=help.js.map

package/dist/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -4,8 +4,10 @@ export { defaultStorePath, type IndexedChunk, type IndexedPackage, type SearchHi
 export { type DiscoveredPackage, type Discovery, discoverPackages, projectPackageIds, resolvePackageDir, } from "./discovery.js";
 export { type DoctorOptions, type DoctorReport, type Finding, runDoctor, type Severity, } from "./doctor.js";
 export { DocspackError } from "./errors.js";
+export { type EvalCase, type EvalCaseResult, type EvalOptions, type EvalReport, evaluatePackage, parseEvalSet, readEvalSet, } from "./eval.js";
 export { type ExportSurface, readExportSurface } from "./exports.js";
 export { type AddOptions, type AddResult, addFinding, FEEDBACK_DIR, FEEDBACK_FILE, type FeedbackFinding, feedbackPath, fingerprintOf, type RemoveOptions, readFeedback, removeFindings, } from "./feedback.js";
+export { COMMANDS, type CommandHelp, commandHelpText, findCommandHelp, globalHelpText, } from "./help.js";
 export { type FetchLike, HttpClient } from "./http.js";
 export { type Detected, detectProject, type PackageManager } from "./init/detect.js";
 export { type InitMode, type InitOptions, type InitPlan, type InitTemplate, type InputKind, type PlannedFile, planInit, proposePackageName, } from "./init/plan.js";
@@ -18,7 +20,8 @@ export { type PreviewOptions, type PreviewResult, previewPackage } from "./previ
 export { type Choice, defaultStreams, Prompter, type PromptStreams } from "./prompt.js";
 export { DEFAULT_LIMIT, DEFAULT_MAX_TOKENS, type QueryHit, type QueryOptions, type QueryResult, queryDocs, renderAnswer, splitPackageId, } from "./search.js";
 export { AGENTS_SNIPPET, FEEDBACK_SNIPPET } from "./snippet.js";
-export { CHUNKS_DIR, type ChunkSpec, chunkId, estimateTokens, isCommunityPackage, isDocsPackage, isVendorPackage, LLMS_DIR, MANIFEST_FILE, type PackageManifest, packageId, parseManifest, resolveChunkFile, SCHEMA_URL, SPEC_URL, serializeManifest, } from "./spec.js";
+export { CHUNKS_DIR, type ChunkSpec, chunkId, type DocumentedLibrary, estimateTokens, formatDocumentedLibrary, isCommunityPackage, isDocsPackage, isVendorPackage, LLMS_DIR, MANIFEST_FILE, type PackageManifest, packageId, parseDocumentedLibrary, parseManifest, resolveChunkFile, SCHEMA_URL, SPEC_URL, serializeManifest, } from "./spec.js";
+export { STOPWORDS } from "./stopwords.js";
 export { type BlockedFinding, type BlockedReason, issueUrl, prepareSubmission, type RoutedFinding, renderBody, type SubmitOptions, type SubmitReport, } from "./submit.js";
 export { type SyncedPackage, type SyncOptions, type SyncResult, type SyncStatus, syncProject, } from "./sync.js";
 export { type DriftFinding, type VerifiedPackage, type VerifyOptions, type VerifyReport, type VerifyStatus, verifyProject, } from "./verify.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -4,8 +4,10 @@ export { defaultStorePath, Store, silenceSqliteWarning, toFtsQuery, } from "./db
 export { discoverPackages, projectPackageIds, resolvePackageDir, } from "./discovery.js";
 export { runDoctor, } from "./doctor.js";
 export { DocspackError } from "./errors.js";
+export { evaluatePackage, parseEvalSet, readEvalSet, } from "./eval.js";
 export { readExportSurface } from "./exports.js";
 export { addFinding, FEEDBACK_DIR, FEEDBACK_FILE, feedbackPath, fingerprintOf, readFeedback, removeFindings, } from "./feedback.js";
+export { COMMANDS, commandHelpText, findCommandHelp, globalHelpText, } from "./help.js";
 export { HttpClient } from "./http.js";
 export { detectProject } from "./init/detect.js";
 export { planInit, proposePackageName, } from "./init/plan.js";
@@ -18,7 +20,8 @@ export { previewPackage } from "./preview.js";
 export { defaultStreams, Prompter } from "./prompt.js";
 export { DEFAULT_LIMIT, DEFAULT_MAX_TOKENS, queryDocs, renderAnswer, splitPackageId, } from "./search.js";
 export { AGENTS_SNIPPET, FEEDBACK_SNIPPET } from "./snippet.js";
-export { CHUNKS_DIR, chunkId, estimateTokens, isCommunityPackage, isDocsPackage, isVendorPackage, LLMS_DIR, MANIFEST_FILE, packageId, parseManifest, resolveChunkFile, SCHEMA_URL, SPEC_URL, serializeManifest, } from "./spec.js";
+export { CHUNKS_DIR, chunkId, estimateTokens, formatDocumentedLibrary, isCommunityPackage, isDocsPackage, isVendorPackage, LLMS_DIR, MANIFEST_FILE, packageId, parseDocumentedLibrary, parseManifest, resolveChunkFile, SCHEMA_URL, SPEC_URL, serializeManifest, } from "./spec.js";
+export { STOPWORDS } from "./stopwords.js";
 export { issueUrl, prepareSubmission, renderBody, } from "./submit.js";
 export { syncProject, } from "./sync.js";
 export { verifyProject, } from "./verify.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuC,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/E,OAAO,EAEL,UAAU,EAEV,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gBAAgB,EAKhB,KAAK,EACL,oBAAoB,EACpB,UAAU,GACX,MAAM,SAAS,CAAC;AACjB,OAAO,EAGL,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAIL,SAAS,GAEV,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAsB,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,EAGL,UAAU,EACV,YAAY,EACZ,aAAa,EAEb,YAAY,EACZ,aAAa,EAEb,YAAY,EACZ,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,OAAO,EAAkB,UAAU,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,EAAiB,aAAa,EAAuB,MAAM,kBAAkB,CAAC;AACrF,OAAO,EAOL,QAAQ,EACR,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAwC,OAAO,EAAE,MAAM,eAAe,CAAC;AAC9E,OAAO,EAEL,SAAS,EACT,UAAU,GAGX,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAoB,aAAa,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACpE,OAAO,EACL,cAAc,EAId,YAAY,GACb,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAmB,cAAc,EAAE,MAAM,UAAU,CAAC;AAC5E,OAAO,EAA2C,cAAc,EAAE,MAAM,cAAc,CAAC;AACvF,OAAO,EAAe,cAAc,EAAE,QAAQ,EAAsB,MAAM,aAAa,CAAC;AACxF,OAAO,EACL,aAAa,EACb,kBAAkB,EAIlB,SAAS,EACT,YAAY,EACZ,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EACL,UAAU,EAEV,OAAO,EACP,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,QAAQ,EACR,aAAa,EAEb,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,UAAU,EACV,QAAQ,EACR,iBAAiB,GAClB,MAAM,WAAW,CAAC;AACnB,OAAO,EAGL,QAAQ,EACR,iBAAiB,EAEjB,UAAU,GAGX,MAAM,aAAa,CAAC;AACrB,OAAO,EAKL,WAAW,GACZ,MAAM,WAAW,CAAC;AACnB,OAAO,EAML,aAAa,GACd,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuC,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/E,OAAO,EAEL,UAAU,EAEV,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gBAAgB,EAKhB,KAAK,EACL,oBAAoB,EACpB,UAAU,GACX,MAAM,SAAS,CAAC;AACjB,OAAO,EAGL,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAIL,SAAS,GAEV,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAKL,eAAe,EACf,YAAY,EACZ,WAAW,GACZ,MAAM,WAAW,CAAC;AACnB,OAAO,EAAsB,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,EAGL,UAAU,EACV,YAAY,EACZ,aAAa,EAEb,YAAY,EACZ,aAAa,EAEb,YAAY,EACZ,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,QAAQ,EAER,eAAe,EACf,eAAe,EACf,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EAAkB,UAAU,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,EAAiB,aAAa,EAAuB,MAAM,kBAAkB,CAAC;AACrF,OAAO,EAOL,QAAQ,EACR,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAwC,OAAO,EAAE,MAAM,eAAe,CAAC;AAC9E,OAAO,EAEL,SAAS,EACT,UAAU,GAGX,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAoB,aAAa,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACpE,OAAO,EACL,cAAc,EAId,YAAY,GACb,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAmB,cAAc,EAAE,MAAM,UAAU,CAAC;AAC5E,OAAO,EAA2C,cAAc,EAAE,MAAM,cAAc,CAAC;AACvF,OAAO,EAAe,cAAc,EAAE,QAAQ,EAAsB,MAAM,aAAa,CAAC;AACxF,OAAO,EACL,aAAa,EACb,kBAAkB,EAIlB,SAAS,EACT,YAAY,EACZ,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EACL,UAAU,EAEV,OAAO,EAEP,cAAc,EACd,uBAAuB,EACvB,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,QAAQ,EACR,aAAa,EAEb,SAAS,EACT,sBAAsB,EACtB,aAAa,EACb,gBAAgB,EAChB,UAAU,EACV,QAAQ,EACR,iBAAiB,GAClB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAGL,QAAQ,EACR,iBAAiB,EAEjB,UAAU,GAGX,MAAM,aAAa,CAAC;AACrB,OAAO,EAKL,WAAW,GACZ,MAAM,WAAW,CAAC;AACnB,OAAO,EAML,aAAa,GACd,MAAM,aAAa,CAAC"}

package/dist/preview.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../src/preview.ts"],"names":[],"mappings":"AAIA,OAAO,EAAqC,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAY/E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAgEpF"}
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../src/preview.ts"],"names":[],"mappings":"AAIA,OAAO,EAAqC,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAa/E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAkEpF"}

package/dist/preview.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { Store } from "./db.js";
 import { DocspackError } from "./errors.js";
 import { DEFAULT_LIMIT, DEFAULT_MAX_TOKENS } from "./search.js";
-import { chunkId, estimateTokens, isCommunityPackage, LLMS_DIR, MANIFEST_FILE, packageId, parseManifest, resolveChunkFile, } from "./spec.js";
+import { chunkId, estimateTokens, formatDocumentedLibrary, isCommunityPackage, LLMS_DIR, MANIFEST_FILE, packageId, parseManifest, resolveChunkFile, } from "./spec.js";
 /**
  * Answers a query from a package on disk, through the same ranking and token budget an agent
  * gets. Nothing is published, installed, or written to the global store.
@@ -21,6 +21,7 @@ export async function previewPackage(options) {
     }
     const manifest = parseManifest(JSON.parse(raw), `${LLMS_DIR}/${MANIFEST_FILE}`);
     const id = packageId(manifest.name, manifest.version);
+    const documents = (manifest.documents ?? []).map(formatDocumentedLibrary);
     const chunks = [];
     for (const chunk of manifest.chunks) {
         let contents;
@@ -35,7 +36,7 @@ export async function previewPackage(options) {
         chunks.push({
             chunkId: chunkId(id, chunk.id),
             filePath: chunk.file,
-            tokens: chunk.tokens > 0 ? chunk.tokens : estimateTokens(contents),
+            tokens: chunk.tokens ?? estimateTokens(contents),
             content: contents,
             tags: [...chunk.tags, ...chunk.entities],
         });
@@ -58,6 +59,7 @@ export async function previewPackage(options) {
             name: manifest.name,
             version: manifest.version,
             trusted: !isCommunityPackage(manifest.name),
+            ...(documents.length === 0 ? {} : { documents }),
         }));
         return {
             hits,

package/dist/preview.js.map

@@ -1 +1 @@
-{"version":3,"file":"preview.js","sourceRoot":"","sources":["../src/preview.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"preview.js","sourceRoot":"","sources":["../src/preview.ts"],"names":[],"mappings":"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"}

package/dist/search.d.ts

@@ -20,6 +20,13 @@ export interface QueryHit extends SearchHit {
     readonly name: string;
     readonly version: string;
     readonly trusted: boolean;
+    /**
+     * Libraries this chunk documents, from its manifest. A docs package version cannot always
+     * imply this — a monorepo documents many libraries at many versions from one surface — so the
+     * answer states it rather than leaving the reader to infer it from the package name. A chunk
+     * that names its own libraries answers for those; otherwise the package's list stands.
+     */
+    readonly documents?: readonly string[];
 }
 export interface QueryResult {
     readonly hits: readonly QueryHit[];

package/dist/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAIhD,qGAAqG;AACrG,eAAO,MAAM,kBAAkB,OAAO,CAAC;AACvC,eAAO,MAAM,aAAa,IAAI,CAAC;AAE/B,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,QAAS,SAAQ,SAAS;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,wBAAsB,SAAS,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CA4B3E;AAMD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAsBvE;AAED,oEAAoE;AACpE,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAI5E"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAIhD,qGAAqG;AACrG,eAAO,MAAM,kBAAkB,OAAO,CAAC;AACvC,eAAO,MAAM,aAAa,IAAI,CAAC;AAE/B,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,QAAS,SAAQ,SAAS;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,wBAAsB,SAAS,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAoD3E;AAMD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CA6BvE;AAED,oEAAoE;AACpE,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAI5E"}

package/dist/search.js

@@ -1,5 +1,5 @@
 import { discoverPackages } from "./discovery.js";
-import { isCommunityPackage } from "./spec.js";
+import { chunkId, formatDocumentedLibrary, isCommunityPackage } from "./spec.js";
 /** Ceiling on how much context one query may return, per the blueprint's context-exhaustion rule. */
 export const DEFAULT_MAX_TOKENS = 3000;
 export const DEFAULT_LIMIT = 3;
@@ -10,6 +10,22 @@ export async function queryDocs(options) {
     const unindexed = (installed ?? [])
         .filter((pkg) => !options.store.hasPackage(pkg.id))
         .map((pkg) => pkg.id);
+    // Read from the installed manifests rather than the index: the store is a cache of chunk text,
+    // and adding a column to it would make every existing store need a rebuild to answer this.
+    // Keyed by package id and by chunk id in the same map, because a chunk id already carries its
+    // package: `@acme/docspack@1.4.0/api-auth` cannot collide with `@acme/docspack@1.4.0`.
+    const documented = new Map();
+    for (const pkg of installed ?? []) {
+        const documents = pkg.manifest.documents;
+        if (documents !== undefined && documents.length > 0) {
+            documented.set(pkg.id, documents.map(formatDocumentedLibrary));
+        }
+        for (const chunk of pkg.manifest.chunks) {
+            if (chunk.documents === undefined || chunk.documents.length === 0)
+                continue;
+            documented.set(chunkId(pkg.id, chunk.id), chunk.documents.map(formatDocumentedLibrary));
+        }
+    }
     const hits = options.store
         .search(options.query, {
         ...(packageIds === undefined ? {} : { packageIds }),
@@ -21,7 +37,15 @@ export async function queryDocs(options) {
     })
         .map((hit) => {
         const { name, version } = splitPackageId(hit.packageId);
-        return { ...hit, name, version, trusted: !isCommunityPackage(name) };
+        // The chunk's own libraries win: they are the narrower, and therefore the truer, claim.
+        const documents = documented.get(hit.chunkId) ?? documented.get(hit.packageId);
+        return {
+            ...hit,
+            name,
+            version,
+            trusted: !isCommunityPackage(name),
+            ...(documents === undefined ? {} : { documents }),
+        };
     });
     return {
         hits,
@@ -47,9 +71,15 @@ export function renderAnswer(result, query) {
     }
     const sections = result.hits.map((hit) => {
         const trust = hit.trusted ? "" : " (community)";
+        // Which release the chunk describes, on the line that already carries provenance. An agent
+        // otherwise has to assume the docs package version is the library version, which a
+        // repository publishing eighteen packages from one docs surface cannot make true.
+        const describes = hit.documents === undefined || hit.documents.length === 0
+            ? ""
+            : ` · documents ${hit.documents.join(", ")}`;
         return [
             `## ${hit.chunkId}${trust}`,
-            `Source: ${hit.name}@${hit.version} — ${hit.filePath}`,
+            `Source: ${hit.name}@${hit.version} — ${hit.filePath}${describes}`,
             "",
             hit.content,
         ].join("\n");

package/dist/search.js.map

@@ -1 +1 @@
-{"version":3,"file":"search.js","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"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"}