@kolisachint/hoocode-agent 0.5.25 → 0.5.27

package/dist/core/capabilities/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/core/capabilities/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,kBAAkB,GAAG,kBAAkB,CAAC;AAElH,MAAM,WAAW,aAAa;IAC7B,yEAAyE;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,cAAc,CAAC;IACrB,yEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,QAAQ,EAAE,OAAO,CAAC;CAClB;AAWD,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,SAAS,aAAa,EAAE,GAAG,IAAI,CAG/F;AAED,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,KAAK,CAAC,EAAE,SAAS,cAAc,EAAE,GAAG,aAAa,EAAE,CAQlF;AAED,wDAAwD;AACxD,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,SAAS,aAAa,EAAsB,GAAG,MAAM,CAI5F","sourcesContent":["/**\n * One index of everything the agent can *acquire* — MCP tools, skills, slash\n * commands, subagents, and plugins available or installed.\n *\n * The problem this exists for: deferral already withholds MCP tool schemas, but\n * the model still needs some way to find a withheld tool, and the only one it\n * had was an exact name match against a catalog dumped in full into the\n * resolver's description. Those two are locked together — an exact-only matcher\n * *forces* the full dump, because a name you cannot guess is a tool you cannot\n * reach. Give the matcher retrieval and the dump becomes optional, which is\n * where the context saving actually lives.\n *\n * The producers are deliberately not coupled to it: each one hands over a flat\n * list of documents for its own kind and knows nothing about retrieval. That is\n * what lets skills and commands join later (§6.4 leaves them eager for now)\n * without touching the search side.\n *\n * See docs/plugin-system-architecture.md §6.\n */\n\nimport { createHash } from \"node:crypto\";\n\nexport type CapabilityKind = \"mcp-tool\" | \"skill\" | \"command\" | \"agent\" | \"plugin-available\" | \"plugin-installed\";\n\nexport interface CapabilityDoc {\n\t/** Unique and stable within a session; `<kind>:<name>` by convention. */\n\tid: string;\n\tkind: CapabilityKind;\n\t/** How the model refers to it — a tool name, skill name, plugin id. */\n\tname: string;\n\tdescription: string;\n\t/** Where it came from: MCP server, plugin id, marketplace name. */\n\tsource?: string;\n\t/**\n\t * Whether the expensive part (a JSON schema, a skill body) is currently\n\t * withheld from context.\n\t *\n\t * Recorded rather than derived because it is the policy knob of §6.3: it says\n\t * which entries retrieval is actually *for*. An eager capability is already\n\t * visible to the model, so surfacing it in search results is a convenience;\n\t * a deferred one is otherwise unreachable.\n\t */\n\tdeferred: boolean;\n}\n\n/**\n * Registered documents, by kind.\n *\n * Keyed by kind rather than a flat map because a producer owns its whole kind:\n * the MCP loader knows every MCP tool there is, and on reload it should replace\n * that set, not merge into a pile where a removed server's tools linger.\n */\nconst byKind = new Map<CapabilityKind, CapabilityDoc[]>();\n\n/** Replace every document of `kind`. Producers call this on load and on reload. */\nexport function registerCapabilities(kind: CapabilityKind, docs: readonly CapabilityDoc[]): void {\n\tif (docs.length === 0) byKind.delete(kind);\n\telse byKind.set(kind, [...docs]);\n}\n\n/** Every registered document, in a stable order (kind, then id). */\nexport function getCapabilities(kinds?: readonly CapabilityKind[]): CapabilityDoc[] {\n\tconst wanted = kinds && kinds.length > 0 ? new Set(kinds) : undefined;\n\tconst out: CapabilityDoc[] = [];\n\tfor (const kind of [...byKind.keys()].sort()) {\n\t\tif (wanted && !wanted.has(kind)) continue;\n\t\tout.push(...(byKind.get(kind) ?? []).slice().sort((a, b) => a.id.localeCompare(b.id)));\n\t}\n\treturn out;\n}\n\n/** Drop everything. Tests, and a full session reset. */\nexport function clearCapabilities(): void {\n\tbyKind.clear();\n}\n\n/**\n * Content hash of the current capability set — the key a persistent index is\n * stored under.\n *\n * Hashes the text that gets embedded, not the count: two sessions with the same\n * tools should share an index, and one where a server changed a description\n * should not silently reuse vectors describing the old one.\n */\nexport function capabilitySetHash(docs: readonly CapabilityDoc[] = getCapabilities()): string {\n\tconst h = createHash(\"sha256\");\n\tfor (const d of docs) h.update(`${d.id}\u0000${d.name}\u0000${d.description}\u0000`);\n\treturn h.digest(\"hex\").slice(0, 16);\n}\n"]}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/core/capabilities/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,MAAM,MAAM,cAAc,GACvB,UAAU,GACV,OAAO,GACP,SAAS,GACT,OAAO,GACP,kBAAkB,GAClB,kBAAkB;AACpB,oEAAoE;GAClE,KAAK,CAAC;AAET,MAAM,WAAW,aAAa;IAC7B,yEAAyE;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,cAAc,CAAC;IACrB,yEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,QAAQ,EAAE,OAAO,CAAC;CAClB;AAWD,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,SAAS,aAAa,EAAE,GAAG,IAAI,CAG/F;AAED,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,KAAK,CAAC,EAAE,SAAS,cAAc,EAAE,GAAG,aAAa,EAAE,CAQlF;AAED,wDAAwD;AACxD,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,SAAS,aAAa,EAAsB,GAAG,MAAM,CAI5F","sourcesContent":["/**\n * One index of everything the agent can *acquire* — MCP tools, skills, slash\n * commands, subagents, and plugins available or installed.\n *\n * The problem this exists for: deferral already withholds MCP tool schemas, but\n * the model still needs some way to find a withheld tool, and the only one it\n * had was an exact name match against a catalog dumped in full into the\n * resolver's description. Those two are locked together — an exact-only matcher\n * *forces* the full dump, because a name you cannot guess is a tool you cannot\n * reach. Give the matcher retrieval and the dump becomes optional, which is\n * where the context saving actually lives.\n *\n * The producers are deliberately not coupled to it: each one hands over a flat\n * list of documents for its own kind and knows nothing about retrieval. That is\n * what lets skills and commands join later (§6.4 leaves them eager for now)\n * without touching the search side.\n *\n * See docs/plugin-system-architecture.md §6.\n */\n\nimport { createHash } from \"node:crypto\";\n\nexport type CapabilityKind =\n\t| \"mcp-tool\"\n\t| \"skill\"\n\t| \"command\"\n\t| \"agent\"\n\t| \"plugin-available\"\n\t| \"plugin-installed\"\n\t/** A heading-level slice of hoocode's own shipped documentation. */\n\t| \"doc\";\n\nexport interface CapabilityDoc {\n\t/** Unique and stable within a session; `<kind>:<name>` by convention. */\n\tid: string;\n\tkind: CapabilityKind;\n\t/** How the model refers to it — a tool name, skill name, plugin id. */\n\tname: string;\n\tdescription: string;\n\t/** Where it came from: MCP server, plugin id, marketplace name. */\n\tsource?: string;\n\t/**\n\t * Whether the expensive part (a JSON schema, a skill body) is currently\n\t * withheld from context.\n\t *\n\t * Recorded rather than derived because it is the policy knob of §6.3: it says\n\t * which entries retrieval is actually *for*. An eager capability is already\n\t * visible to the model, so surfacing it in search results is a convenience;\n\t * a deferred one is otherwise unreachable.\n\t */\n\tdeferred: boolean;\n}\n\n/**\n * Registered documents, by kind.\n *\n * Keyed by kind rather than a flat map because a producer owns its whole kind:\n * the MCP loader knows every MCP tool there is, and on reload it should replace\n * that set, not merge into a pile where a removed server's tools linger.\n */\nconst byKind = new Map<CapabilityKind, CapabilityDoc[]>();\n\n/** Replace every document of `kind`. Producers call this on load and on reload. */\nexport function registerCapabilities(kind: CapabilityKind, docs: readonly CapabilityDoc[]): void {\n\tif (docs.length === 0) byKind.delete(kind);\n\telse byKind.set(kind, [...docs]);\n}\n\n/** Every registered document, in a stable order (kind, then id). */\nexport function getCapabilities(kinds?: readonly CapabilityKind[]): CapabilityDoc[] {\n\tconst wanted = kinds && kinds.length > 0 ? new Set(kinds) : undefined;\n\tconst out: CapabilityDoc[] = [];\n\tfor (const kind of [...byKind.keys()].sort()) {\n\t\tif (wanted && !wanted.has(kind)) continue;\n\t\tout.push(...(byKind.get(kind) ?? []).slice().sort((a, b) => a.id.localeCompare(b.id)));\n\t}\n\treturn out;\n}\n\n/** Drop everything. Tests, and a full session reset. */\nexport function clearCapabilities(): void {\n\tbyKind.clear();\n}\n\n/**\n * Content hash of the current capability set — the key a persistent index is\n * stored under.\n *\n * Hashes the text that gets embedded, not the count: two sessions with the same\n * tools should share an index, and one where a server changed a description\n * should not silently reuse vectors describing the old one.\n */\nexport function capabilitySetHash(docs: readonly CapabilityDoc[] = getCapabilities()): string {\n\tconst h = createHash(\"sha256\");\n\tfor (const d of docs) h.update(`${d.id}\u0000${d.name}\u0000${d.description}\u0000`);\n\treturn h.digest(\"hex\").slice(0, 16);\n}\n"]}

package/dist/core/capabilities/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/core/capabilities/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAyBzC;;;;;;GAMG;AACH,MAAM,MAAM,GAAG,IAAI,GAAG,EAAmC,CAAC;AAE1D,mFAAmF;AACnF,MAAM,UAAU,oBAAoB,CAAC,IAAoB,EAAE,IAA8B,EAAQ;IAChG,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;;QACtC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;AAAA,CACjC;AAED,oEAAoE;AACpE,MAAM,UAAU,eAAe,CAAC,KAAiC,EAAmB;IACnF,MAAM,MAAM,GAAG,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACtE,MAAM,GAAG,GAAoB,EAAE,CAAC;IAChC,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAC9C,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QAC1C,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,GAAG,CAAC;AAAA,CACX;AAED,wDAAwD;AACxD,MAAM,UAAU,iBAAiB,GAAS;IACzC,MAAM,CAAC,KAAK,EAAE,CAAC;AAAA,CACf;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAI,GAA6B,eAAe,EAAE,EAAU;IAC7F,MAAM,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,IAAI;QAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC;IACtE,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAAA,CACpC","sourcesContent":["/**\n * One index of everything the agent can *acquire* — MCP tools, skills, slash\n * commands, subagents, and plugins available or installed.\n *\n * The problem this exists for: deferral already withholds MCP tool schemas, but\n * the model still needs some way to find a withheld tool, and the only one it\n * had was an exact name match against a catalog dumped in full into the\n * resolver's description. Those two are locked together — an exact-only matcher\n * *forces* the full dump, because a name you cannot guess is a tool you cannot\n * reach. Give the matcher retrieval and the dump becomes optional, which is\n * where the context saving actually lives.\n *\n * The producers are deliberately not coupled to it: each one hands over a flat\n * list of documents for its own kind and knows nothing about retrieval. That is\n * what lets skills and commands join later (§6.4 leaves them eager for now)\n * without touching the search side.\n *\n * See docs/plugin-system-architecture.md §6.\n */\n\nimport { createHash } from \"node:crypto\";\n\nexport type CapabilityKind = \"mcp-tool\" | \"skill\" | \"command\" | \"agent\" | \"plugin-available\" | \"plugin-installed\";\n\nexport interface CapabilityDoc {\n\t/** Unique and stable within a session; `<kind>:<name>` by convention. */\n\tid: string;\n\tkind: CapabilityKind;\n\t/** How the model refers to it — a tool name, skill name, plugin id. */\n\tname: string;\n\tdescription: string;\n\t/** Where it came from: MCP server, plugin id, marketplace name. */\n\tsource?: string;\n\t/**\n\t * Whether the expensive part (a JSON schema, a skill body) is currently\n\t * withheld from context.\n\t *\n\t * Recorded rather than derived because it is the policy knob of §6.3: it says\n\t * which entries retrieval is actually *for*. An eager capability is already\n\t * visible to the model, so surfacing it in search results is a convenience;\n\t * a deferred one is otherwise unreachable.\n\t */\n\tdeferred: boolean;\n}\n\n/**\n * Registered documents, by kind.\n *\n * Keyed by kind rather than a flat map because a producer owns its whole kind:\n * the MCP loader knows every MCP tool there is, and on reload it should replace\n * that set, not merge into a pile where a removed server's tools linger.\n */\nconst byKind = new Map<CapabilityKind, CapabilityDoc[]>();\n\n/** Replace every document of `kind`. Producers call this on load and on reload. */\nexport function registerCapabilities(kind: CapabilityKind, docs: readonly CapabilityDoc[]): void {\n\tif (docs.length === 0) byKind.delete(kind);\n\telse byKind.set(kind, [...docs]);\n}\n\n/** Every registered document, in a stable order (kind, then id). */\nexport function getCapabilities(kinds?: readonly CapabilityKind[]): CapabilityDoc[] {\n\tconst wanted = kinds && kinds.length > 0 ? new Set(kinds) : undefined;\n\tconst out: CapabilityDoc[] = [];\n\tfor (const kind of [...byKind.keys()].sort()) {\n\t\tif (wanted && !wanted.has(kind)) continue;\n\t\tout.push(...(byKind.get(kind) ?? []).slice().sort((a, b) => a.id.localeCompare(b.id)));\n\t}\n\treturn out;\n}\n\n/** Drop everything. Tests, and a full session reset. */\nexport function clearCapabilities(): void {\n\tbyKind.clear();\n}\n\n/**\n * Content hash of the current capability set — the key a persistent index is\n * stored under.\n *\n * Hashes the text that gets embedded, not the count: two sessions with the same\n * tools should share an index, and one where a server changed a description\n * should not silently reuse vectors describing the old one.\n */\nexport function capabilitySetHash(docs: readonly CapabilityDoc[] = getCapabilities()): string {\n\tconst h = createHash(\"sha256\");\n\tfor (const d of docs) h.update(`${d.id}\u0000${d.name}\u0000${d.description}\u0000`);\n\treturn h.digest(\"hex\").slice(0, 16);\n}\n"]}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/core/capabilities/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAiCzC;;;;;;GAMG;AACH,MAAM,MAAM,GAAG,IAAI,GAAG,EAAmC,CAAC;AAE1D,mFAAmF;AACnF,MAAM,UAAU,oBAAoB,CAAC,IAAoB,EAAE,IAA8B,EAAQ;IAChG,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;;QACtC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;AAAA,CACjC;AAED,oEAAoE;AACpE,MAAM,UAAU,eAAe,CAAC,KAAiC,EAAmB;IACnF,MAAM,MAAM,GAAG,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACtE,MAAM,GAAG,GAAoB,EAAE,CAAC;IAChC,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAC9C,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QAC1C,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,GAAG,CAAC;AAAA,CACX;AAED,wDAAwD;AACxD,MAAM,UAAU,iBAAiB,GAAS;IACzC,MAAM,CAAC,KAAK,EAAE,CAAC;AAAA,CACf;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAI,GAA6B,eAAe,EAAE,EAAU;IAC7F,MAAM,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,IAAI;QAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC;IACtE,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAAA,CACpC","sourcesContent":["/**\n * One index of everything the agent can *acquire* — MCP tools, skills, slash\n * commands, subagents, and plugins available or installed.\n *\n * The problem this exists for: deferral already withholds MCP tool schemas, but\n * the model still needs some way to find a withheld tool, and the only one it\n * had was an exact name match against a catalog dumped in full into the\n * resolver's description. Those two are locked together — an exact-only matcher\n * *forces* the full dump, because a name you cannot guess is a tool you cannot\n * reach. Give the matcher retrieval and the dump becomes optional, which is\n * where the context saving actually lives.\n *\n * The producers are deliberately not coupled to it: each one hands over a flat\n * list of documents for its own kind and knows nothing about retrieval. That is\n * what lets skills and commands join later (§6.4 leaves them eager for now)\n * without touching the search side.\n *\n * See docs/plugin-system-architecture.md §6.\n */\n\nimport { createHash } from \"node:crypto\";\n\nexport type CapabilityKind =\n\t| \"mcp-tool\"\n\t| \"skill\"\n\t| \"command\"\n\t| \"agent\"\n\t| \"plugin-available\"\n\t| \"plugin-installed\"\n\t/** A heading-level slice of hoocode's own shipped documentation. */\n\t| \"doc\";\n\nexport interface CapabilityDoc {\n\t/** Unique and stable within a session; `<kind>:<name>` by convention. */\n\tid: string;\n\tkind: CapabilityKind;\n\t/** How the model refers to it — a tool name, skill name, plugin id. */\n\tname: string;\n\tdescription: string;\n\t/** Where it came from: MCP server, plugin id, marketplace name. */\n\tsource?: string;\n\t/**\n\t * Whether the expensive part (a JSON schema, a skill body) is currently\n\t * withheld from context.\n\t *\n\t * Recorded rather than derived because it is the policy knob of §6.3: it says\n\t * which entries retrieval is actually *for*. An eager capability is already\n\t * visible to the model, so surfacing it in search results is a convenience;\n\t * a deferred one is otherwise unreachable.\n\t */\n\tdeferred: boolean;\n}\n\n/**\n * Registered documents, by kind.\n *\n * Keyed by kind rather than a flat map because a producer owns its whole kind:\n * the MCP loader knows every MCP tool there is, and on reload it should replace\n * that set, not merge into a pile where a removed server's tools linger.\n */\nconst byKind = new Map<CapabilityKind, CapabilityDoc[]>();\n\n/** Replace every document of `kind`. Producers call this on load and on reload. */\nexport function registerCapabilities(kind: CapabilityKind, docs: readonly CapabilityDoc[]): void {\n\tif (docs.length === 0) byKind.delete(kind);\n\telse byKind.set(kind, [...docs]);\n}\n\n/** Every registered document, in a stable order (kind, then id). */\nexport function getCapabilities(kinds?: readonly CapabilityKind[]): CapabilityDoc[] {\n\tconst wanted = kinds && kinds.length > 0 ? new Set(kinds) : undefined;\n\tconst out: CapabilityDoc[] = [];\n\tfor (const kind of [...byKind.keys()].sort()) {\n\t\tif (wanted && !wanted.has(kind)) continue;\n\t\tout.push(...(byKind.get(kind) ?? []).slice().sort((a, b) => a.id.localeCompare(b.id)));\n\t}\n\treturn out;\n}\n\n/** Drop everything. Tests, and a full session reset. */\nexport function clearCapabilities(): void {\n\tbyKind.clear();\n}\n\n/**\n * Content hash of the current capability set — the key a persistent index is\n * stored under.\n *\n * Hashes the text that gets embedded, not the count: two sessions with the same\n * tools should share an index, and one where a server changed a description\n * should not silently reuse vectors describing the old one.\n */\nexport function capabilitySetHash(docs: readonly CapabilityDoc[] = getCapabilities()): string {\n\tconst h = createHash(\"sha256\");\n\tfor (const d of docs) h.update(`${d.id}\u0000${d.name}\u0000${d.description}\u0000`);\n\treturn h.digest(\"hex\").slice(0, 16);\n}\n"]}

package/dist/core/self-docs.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The agent's index of hoocode's *own* documentation.
+ *
+ * The startup banner promises "hoocode can explain its own features and look up
+ * its docs", and the docs really do ship with the install (`package.json`
+ * `files` includes `docs`, and `copy-binary-assets` copies them into `dist/` for
+ * the pkg binaries). What was missing is the only part that makes the promise
+ * true: telling the model they exist. `getDocsPath()` had exactly one consumer —
+ * `auth-guidance.ts`, which prints paths to the *human* — so nothing ever put a
+ * docs path into model context.
+ *
+ * That gap is not one the model can close by itself. Its cwd is the user's
+ * project, so `grep`/`find` there discover the user's docs, never hoocode's,
+ * which live in an install directory whose path it cannot derive.
+ *
+ * Descriptions come from `docs/index.md` rather than being duplicated here.
+ * That file is a curated, human-maintained table of contents, and a second
+ * hand-written list is how an index goes stale the first week nobody updates
+ * it. The directory listing stays the source of truth for *what exists*, so a
+ * new doc still shows up (described from its own first paragraph) on the day it
+ * lands, with or without an index entry.
+ */
+export interface SelfDoc {
+    /** Stable id: the filename, e.g. `skills.md`. Also how the model refers to it. */
+    id: string;
+    /** Absolute path, ready to hand to the read tool verbatim. */
+    path: string;
+    /** Human title, e.g. "Skills". */
+    title: string;
+    /** One line on what the doc covers. May be empty if nothing could be derived. */
+    description: string;
+}
+/** Drop the cached listing. Tests, and anything that relocates the package root. */
+export declare function resetSelfDocs(): void;
+/**
+ * Every shipped doc, sorted with the overview first and the rest alphabetical.
+ *
+ * Returns `[]` when the docs directory is absent rather than throwing: a source
+ * checkout, an odd packaging, or a trimmed container should degrade to "no docs
+ * section in the prompt", never to a failed session start.
+ */
+export declare function listSelfDocs(): SelfDoc[];
+/**
+ * The system-prompt section, or `""` when there is nothing to point at.
+ *
+ * Deliberately just filenames. An earlier version carried a one-line summary
+ * per doc and cost ~860 tokens on every single turn, which is a poor trade for
+ * something most turns never use — and it stopped being necessary once
+ * SearchHooCode could retrieve at the heading level. Filenames alone still let
+ * the model go straight to `themes.md` or `keybindings.md` for the obvious
+ * cases, and anything less obvious is one search away. That is ~180 tokens.
+ *
+ * Directories are printed once rather than repeated per entry, for the same
+ * reason: the path was the single largest term on every line.
+ */
+export declare function formatSelfDocsForPrompt(docs?: readonly SelfDoc[]): string;
+/**
+ * A single heading's worth of a doc.
+ *
+ * Doc-level retrieval would add nothing the prompt listing above does not
+ * already give: thirty files with a summary each are cheap enough to list in
+ * full, so a search that answers "read extensions.md" is a round trip for
+ * information the model already had. The questions that actually need
+ * retrieval are the ones inside a 1,100-line file — "how do I register a
+ * tool?" should land on `extensions.md § Custom tools` with a line number, not
+ * on the file.
+ */
+export interface SelfDocSection {
+    /** `<file>#<slug>`, unique across the corpus. */
+    id: string;
+    /** Filename, e.g. `extensions.md`. */
+    file: string;
+    /** Absolute path to the file. */
+    path: string;
+    /** Heading trail from the document title down, e.g. `["Extensions", "Custom tools"]`. */
+    headings: string[];
+    /** 1-based line of the heading, so a reader can jump straight to it. */
+    line: number;
+    /** Start of the section body, for ranking and for showing why a hit matched. */
+    excerpt: string;
+}
+/** `extensions.md § Extensions › Custom tools` — what a search result is labelled with. */
+export declare function sectionLabel(section: SelfDocSection): string;
+/**
+ * Split one markdown file into sections at its headings.
+ *
+ * Fenced code is tracked so a `#` comment inside a bash block cannot be
+ * mistaken for a heading — which would otherwise split docs at every shell
+ * comment. Code *content* still lands in the excerpt: the exact identifiers
+ * someone searches for (`pi.registerTool`) usually live in the examples, and
+ * dropping them would blind the lexical leg to the best terms in the file.
+ */
+export declare function splitIntoSections(markdown: string, file: string, path: string): SelfDocSection[];
+/** Drop the cached section index. Tests, and anything that relocates the package root. */
+export declare function resetSelfDocSections(): void;
+/**
+ * Every section of every shipped doc.
+ *
+ * Reads each file once per session and caches; the docs are read-only install
+ * content, so there is nothing to invalidate on.
+ */
+export declare function listSelfDocSections(): SelfDocSection[];
+//# sourceMappingURL=self-docs.d.ts.map

package/dist/core/self-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-docs.d.ts","sourceRoot":"","sources":["../../src/core/self-docs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAMH,MAAM,WAAW,OAAO;IACvB,kFAAkF;IAClF,EAAE,EAAE,MAAM,CAAC;IACX,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAC;CACpB;AA8GD,oFAAoF;AACpF,wBAAgB,aAAa,IAAI,IAAI,CAGpC;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,OAAO,EAAE,CA6CxC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,GAAE,SAAS,OAAO,EAAmB,GAAG,MAAM,CAsBzF;AAMD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC9B,iDAAiD;IACjD,EAAE,EAAE,MAAM,CAAC;IACX,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;CAChB;AAuBD,gGAA2F;AAC3F,wBAAgB,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAE5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,cAAc,EAAE,CAmDhG;AAsBD,0FAA0F;AAC1F,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,EAAE,CAiBtD","sourcesContent":["/**\n * The agent's index of hoocode's *own* documentation.\n *\n * The startup banner promises \"hoocode can explain its own features and look up\n * its docs\", and the docs really do ship with the install (`package.json`\n * `files` includes `docs`, and `copy-binary-assets` copies them into `dist/` for\n * the pkg binaries). What was missing is the only part that makes the promise\n * true: telling the model they exist. `getDocsPath()` had exactly one consumer —\n * `auth-guidance.ts`, which prints paths to the *human* — so nothing ever put a\n * docs path into model context.\n *\n * That gap is not one the model can close by itself. Its cwd is the user's\n * project, so `grep`/`find` there discover the user's docs, never hoocode's,\n * which live in an install directory whose path it cannot derive.\n *\n * Descriptions come from `docs/index.md` rather than being duplicated here.\n * That file is a curated, human-maintained table of contents, and a second\n * hand-written list is how an index goes stale the first week nobody updates\n * it. The directory listing stays the source of truth for *what exists*, so a\n * new doc still shows up (described from its own first paragraph) on the day it\n * lands, with or without an index entry.\n */\n\nimport { existsSync, readdirSync, readFileSync, statSync } from \"node:fs\";\nimport { basename, dirname, join } from \"node:path\";\nimport { getChangelogPath, getDocsPath, getReadmePath } from \"../config.js\";\n\nexport interface SelfDoc {\n\t/** Stable id: the filename, e.g. `skills.md`. Also how the model refers to it. */\n\tid: string;\n\t/** Absolute path, ready to hand to the read tool verbatim. */\n\tpath: string;\n\t/** Human title, e.g. \"Skills\". */\n\ttitle: string;\n\t/** One line on what the doc covers. May be empty if nothing could be derived. */\n\tdescription: string;\n}\n\n/** How much of a doc to read when deriving a fallback description. */\nconst HEAD_BYTES = 2048;\n\n/** Cap on a derived description, so one run-on opening line cannot bloat the prompt. */\nconst MAX_DESCRIPTION = 110;\n\nfunction truncate(text: string, max = MAX_DESCRIPTION): string {\n\tconst clean = text.replace(/\\s+/g, \" \").trim();\n\tif (clean.length <= max) return clean;\n\treturn `${clean.slice(0, max - 1).trimEnd()}…`;\n}\n\n/** Strip inline markdown that adds noise but no meaning in a prompt listing. */\nfunction stripInlineMarkdown(text: string): string {\n\treturn text\n\t\t.replace(/\\[([^\\]]+)\\]\\([^)]*\\)/g, \"$1\") // links → their text\n\t\t.replace(/[`*_]/g, \"\")\n\t\t.trim();\n}\n\nfunction readHead(path: string): string {\n\ttry {\n\t\t// Whole-file read: these are small, and slicing bytes off a UTF-8 file can\n\t\t// split a multi-byte character. Truncate after decoding instead.\n\t\treturn readFileSync(path, \"utf-8\").slice(0, HEAD_BYTES);\n\t} catch {\n\t\treturn \"\";\n\t}\n}\n\n/** First `# ` heading, or undefined. */\nfunction firstHeading(markdown: string): string | undefined {\n\tfor (const line of markdown.split(/\\r?\\n/)) {\n\t\tconst match = /^#\\s+(.+)$/.exec(line.trim());\n\t\tif (match?.[1]) return stripInlineMarkdown(match[1]);\n\t}\n\treturn undefined;\n}\n\n/**\n * First real prose line: not a heading, blockquote, list item, fence, or table\n * row. Used only for docs the curated index does not describe.\n */\nfunction firstParagraph(markdown: string): string | undefined {\n\tlet inFence = false;\n\tfor (const raw of markdown.split(/\\r?\\n/)) {\n\t\tconst line = raw.trim();\n\t\tif (line.startsWith(\"```\")) {\n\t\t\tinFence = !inFence;\n\t\t\tcontinue;\n\t\t}\n\t\tif (inFence || line === \"\") continue;\n\t\tif (/^[#>|-]/.test(line) || /^\\d+\\./.test(line)) continue;\n\t\treturn stripInlineMarkdown(line);\n\t}\n\treturn undefined;\n}\n\n/**\n * Titles and descriptions the docs maintain about themselves, keyed by filename.\n *\n * Matches list entries of the form `- [Title](file.md) - description`, which is\n * how every section of `index.md` is written. Anything that does not match is\n * skipped rather than guessed at.\n */\nfunction parseCuratedIndex(docsRoot: string): Map<string, { title: string; description: string }> {\n\tconst curated = new Map<string, { title: string; description: string }>();\n\tconst indexPath = join(docsRoot, \"index.md\");\n\tif (!existsSync(indexPath)) return curated;\n\n\tlet content: string;\n\ttry {\n\t\tcontent = readFileSync(indexPath, \"utf-8\");\n\t} catch {\n\t\treturn curated;\n\t}\n\n\t// `[Title](file.md)` followed by a dash of any width and the description.\n\tconst entry = /^\\s*[-*]\\s*\\[([^\\]]+)\\]\\(([^)#]+\\.md)\\)\\s*[-–—:]\\s*(.+?)\\s*$/;\n\tfor (const line of content.split(/\\r?\\n/)) {\n\t\tconst match = entry.exec(line);\n\t\tif (!match) continue;\n\t\tconst [, title, target, description] = match;\n\t\tconst file = basename(target);\n\t\tif (curated.has(file)) continue; // first mention wins\n\t\tcurated.set(file, { title: stripInlineMarkdown(title), description: truncate(stripInlineMarkdown(description)) });\n\t}\n\treturn curated;\n}\n\nfunction describe(path: string, file: string, curated: Map<string, { title: string; description: string }>): SelfDoc {\n\tconst fromIndex = curated.get(file);\n\tif (fromIndex) {\n\t\treturn { id: file, path, title: fromIndex.title, description: fromIndex.description };\n\t}\n\t// Not in the curated index — derive from the doc itself so new files are\n\t// still usable the day they land.\n\tconst head = readHead(path);\n\treturn {\n\t\tid: file,\n\t\tpath,\n\t\ttitle: firstHeading(head) ?? file.replace(/\\.md$/, \"\"),\n\t\tdescription: truncate(firstParagraph(head) ?? \"\"),\n\t};\n}\n\nlet cached: SelfDoc[] | undefined;\n\n/** Drop the cached listing. Tests, and anything that relocates the package root. */\nexport function resetSelfDocs(): void {\n\tcached = undefined;\n\tcachedSections = undefined;\n}\n\n/**\n * Every shipped doc, sorted with the overview first and the rest alphabetical.\n *\n * Returns `[]` when the docs directory is absent rather than throwing: a source\n * checkout, an odd packaging, or a trimmed container should degrade to \"no docs\n * section in the prompt\", never to a failed session start.\n */\nexport function listSelfDocs(): SelfDoc[] {\n\tif (cached) return cached;\n\n\tconst docsRoot = getDocsPath();\n\tconst docs: SelfDoc[] = [];\n\n\tif (existsSync(docsRoot)) {\n\t\tconst curated = parseCuratedIndex(docsRoot);\n\t\tlet files: string[];\n\t\ttry {\n\t\t\tfiles = readdirSync(docsRoot).filter((f) => f.endsWith(\".md\"));\n\t\t} catch {\n\t\t\tfiles = [];\n\t\t}\n\t\t// Overview first: it is the doc that explains the others.\n\t\tfiles.sort((a, b) => (a === \"index.md\" ? -1 : b === \"index.md\" ? 1 : a.localeCompare(b)));\n\t\tfor (const file of files) {\n\t\t\tconst path = join(docsRoot, file);\n\t\t\ttry {\n\t\t\t\tif (!statSync(path).isFile()) continue;\n\t\t\t} catch {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tdocs.push(describe(path, file, curated));\n\t\t}\n\t}\n\n\t// README and CHANGELOG sit beside the docs directory, not inside it, but the\n\t// model needs them for the two questions the docs do not answer: what\n\t// hoocode is, and what changed in this version.\n\tconst extras: Array<{ path: string; title: string; description: string }> = [\n\t\t{ path: getReadmePath(), title: \"README\", description: \"What hoocode is, install, and a feature overview.\" },\n\t\t{\n\t\t\tpath: getChangelogPath(),\n\t\t\ttitle: \"Changelog\",\n\t\t\tdescription: \"Released versions and what changed in each.\",\n\t\t},\n\t];\n\tfor (const extra of extras) {\n\t\tif (!existsSync(extra.path)) continue;\n\t\tdocs.push({ id: basename(extra.path), path: extra.path, title: extra.title, description: extra.description });\n\t}\n\n\tcached = docs;\n\treturn docs;\n}\n\n/**\n * The system-prompt section, or `\"\"` when there is nothing to point at.\n *\n * Deliberately just filenames. An earlier version carried a one-line summary\n * per doc and cost ~860 tokens on every single turn, which is a poor trade for\n * something most turns never use — and it stopped being necessary once\n * SearchHooCode could retrieve at the heading level. Filenames alone still let\n * the model go straight to `themes.md` or `keybindings.md` for the obvious\n * cases, and anything less obvious is one search away. That is ~180 tokens.\n *\n * Directories are printed once rather than repeated per entry, for the same\n * reason: the path was the single largest term on every line.\n */\nexport function formatSelfDocsForPrompt(docs: readonly SelfDoc[] = listSelfDocs()): string {\n\tif (docs.length === 0) return \"\";\n\n\t// Insertion order is already meaningful (overview first, then alphabetical,\n\t// then README/CHANGELOG), so group without re-sorting.\n\tconst groups = new Map<string, string[]>();\n\tfor (const doc of docs) {\n\t\tconst root = dirname(doc.path);\n\t\tconst bucket = groups.get(root);\n\t\tif (bucket) bucket.push(doc.id);\n\t\telse groups.set(root, [doc.id]);\n\t}\n\n\tconst sections = [...groups].map(([root, files]) => `${root}/: ${files.join(\", \")}`);\n\n\treturn `\n\n# About hoocode itself\n\nYou are running inside hoocode. Its own docs ship with the install, listed below; hoocode is actively developed, so answer questions about it from these files rather than from memory. They sit outside the working directory, so searching the project will not find them. Use SearchHooCode to locate a specific heading, or read a file directly.\n\n${sections.join(\"\\n\")}`;\n}\n\n// ---------------------------------------------------------------------------\n// Section index\n// ---------------------------------------------------------------------------\n\n/**\n * A single heading's worth of a doc.\n *\n * Doc-level retrieval would add nothing the prompt listing above does not\n * already give: thirty files with a summary each are cheap enough to list in\n * full, so a search that answers \"read extensions.md\" is a round trip for\n * information the model already had. The questions that actually need\n * retrieval are the ones inside a 1,100-line file — \"how do I register a\n * tool?\" should land on `extensions.md § Custom tools` with a line number, not\n * on the file.\n */\nexport interface SelfDocSection {\n\t/** `<file>#<slug>`, unique across the corpus. */\n\tid: string;\n\t/** Filename, e.g. `extensions.md`. */\n\tfile: string;\n\t/** Absolute path to the file. */\n\tpath: string;\n\t/** Heading trail from the document title down, e.g. `[\"Extensions\", \"Custom tools\"]`. */\n\theadings: string[];\n\t/** 1-based line of the heading, so a reader can jump straight to it. */\n\tline: number;\n\t/** Start of the section body, for ranking and for showing why a hit matched. */\n\texcerpt: string;\n}\n\n/**\n * How much section body to keep.\n *\n * Every character past this is invisible to retrieval, so the cap is a recall\n * limit, not just a size one: at 240 a question about `/grill` missed the\n * section that documents it, because the term sat in the fourth sentence. 400\n * covers the opening of essentially every section here for about 95KB more\n * index across the corpus, which buys back that class of miss.\n */\nconst MAX_EXCERPT = 400;\n\n/** `Custom tools` → `custom-tools`, so ids stay stable and readable. */\nfunction slugify(heading: string): string {\n\treturn (\n\t\theading\n\t\t\t.toLowerCase()\n\t\t\t.replace(/[^a-z0-9]+/g, \"-\")\n\t\t\t.replace(/^-+|-+$/g, \"\") || \"section\"\n\t);\n}\n\n/** `extensions.md § Extensions › Custom tools` — what a search result is labelled with. */\nexport function sectionLabel(section: SelfDocSection): string {\n\treturn section.headings.length > 0 ? `${section.file} § ${section.headings.join(\" › \")}` : section.file;\n}\n\n/**\n * Split one markdown file into sections at its headings.\n *\n * Fenced code is tracked so a `#` comment inside a bash block cannot be\n * mistaken for a heading — which would otherwise split docs at every shell\n * comment. Code *content* still lands in the excerpt: the exact identifiers\n * someone searches for (`pi.registerTool`) usually live in the examples, and\n * dropping them would blind the lexical leg to the best terms in the file.\n */\nexport function splitIntoSections(markdown: string, file: string, path: string): SelfDocSection[] {\n\tconst lines = markdown.split(/\\r?\\n/);\n\tconst sections: SelfDocSection[] = [];\n\tconst trail: Array<{ depth: number; text: string }> = [];\n\tconst usedIds = new Set<string>();\n\n\tlet current: SelfDocSection | undefined;\n\tlet body: string[] = [];\n\tlet inFence = false;\n\n\tconst flush = (): void => {\n\t\tif (!current) return;\n\t\tcurrent.excerpt = truncate(stripInlineMarkdown(body.join(\" \")), MAX_EXCERPT);\n\t\tsections.push(current);\n\t\tbody = [];\n\t};\n\n\tfor (let i = 0; i < lines.length; i++) {\n\t\tconst raw = lines[i] ?? \"\";\n\t\tif (raw.trimStart().startsWith(\"```\")) {\n\t\t\tinFence = !inFence;\n\t\t\tcontinue;\n\t\t}\n\t\tconst heading = inFence ? null : /^(#{1,6})\\s+(.+?)\\s*$/.exec(raw);\n\t\tif (!heading) {\n\t\t\tif (raw.trim() !== \"\") body.push(raw.trim());\n\t\t\tcontinue;\n\t\t}\n\n\t\tflush();\n\n\t\tconst depth = heading[1]?.length ?? 1;\n\t\tconst text = stripInlineMarkdown(heading[2] ?? \"\");\n\t\twhile (trail.length > 0 && (trail[trail.length - 1]?.depth ?? 0) >= depth) trail.pop();\n\t\ttrail.push({ depth, text });\n\n\t\t// Disambiguate repeated headings (\"Example\" appears eleven times in\n\t\t// extensions.md) so ids stay unique and the registry does not collapse them.\n\t\tlet id = `${file}#${slugify(trail.map((t) => t.text).join(\"-\"))}`;\n\t\tif (usedIds.has(id)) {\n\t\t\tlet n = 2;\n\t\t\twhile (usedIds.has(`${id}-${n}`)) n++;\n\t\t\tid = `${id}-${n}`;\n\t\t}\n\t\tusedIds.add(id);\n\n\t\tcurrent = { id, file, path, headings: trail.map((t) => t.text), line: i + 1, excerpt: \"\" };\n\t}\n\tflush();\n\n\treturn sections;\n}\n\n/**\n * Files kept out of the section index.\n *\n * The changelog is 40% of the corpus by section count and none of it answers\n * \"how does X work\": it is hundreds of near-identical `Added`/`Fixed`/`Changed`\n * headings under version numbers, which crowd real documentation out of the\n * ranking while matching almost any query about a feature by name.\n *\n * `index.md` is excluded for the mirror-image reason: it is a table of contents,\n * so its \"sections\" are lists of links whose text is every other doc's title and\n * summary. That makes it match any query those docs would match, while carrying\n * none of the content — a guaranteed false attractor that displaces the page it\n * is pointing at.\n *\n * Both stay in the prompt's filename listing, one read away.\n */\nconst SECTION_INDEX_EXCLUDED = new Set([\"CHANGELOG.md\", \"index.md\"]);\n\nlet cachedSections: SelfDocSection[] | undefined;\n\n/** Drop the cached section index. Tests, and anything that relocates the package root. */\nexport function resetSelfDocSections(): void {\n\tcachedSections = undefined;\n}\n\n/**\n * Every section of every shipped doc.\n *\n * Reads each file once per session and caches; the docs are read-only install\n * content, so there is nothing to invalidate on.\n */\nexport function listSelfDocSections(): SelfDocSection[] {\n\tif (cachedSections) return cachedSections;\n\n\tconst sections: SelfDocSection[] = [];\n\tfor (const doc of listSelfDocs()) {\n\t\tif (SECTION_INDEX_EXCLUDED.has(doc.id)) continue;\n\t\tlet content: string;\n\t\ttry {\n\t\t\tcontent = readFileSync(doc.path, \"utf-8\");\n\t\t} catch {\n\t\t\tcontinue;\n\t\t}\n\t\tsections.push(...splitIntoSections(content, doc.id, doc.path));\n\t}\n\n\tcachedSections = sections;\n\treturn sections;\n}\n"]}

package/dist/core/self-docs.js

@@ -0,0 +1,351 @@
+/**
+ * The agent's index of hoocode's *own* documentation.
+ *
+ * The startup banner promises "hoocode can explain its own features and look up
+ * its docs", and the docs really do ship with the install (`package.json`
+ * `files` includes `docs`, and `copy-binary-assets` copies them into `dist/` for
+ * the pkg binaries). What was missing is the only part that makes the promise
+ * true: telling the model they exist. `getDocsPath()` had exactly one consumer —
+ * `auth-guidance.ts`, which prints paths to the *human* — so nothing ever put a
+ * docs path into model context.
+ *
+ * That gap is not one the model can close by itself. Its cwd is the user's
+ * project, so `grep`/`find` there discover the user's docs, never hoocode's,
+ * which live in an install directory whose path it cannot derive.
+ *
+ * Descriptions come from `docs/index.md` rather than being duplicated here.
+ * That file is a curated, human-maintained table of contents, and a second
+ * hand-written list is how an index goes stale the first week nobody updates
+ * it. The directory listing stays the source of truth for *what exists*, so a
+ * new doc still shows up (described from its own first paragraph) on the day it
+ * lands, with or without an index entry.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { getChangelogPath, getDocsPath, getReadmePath } from "../config.js";
+/** How much of a doc to read when deriving a fallback description. */
+const HEAD_BYTES = 2048;
+/** Cap on a derived description, so one run-on opening line cannot bloat the prompt. */
+const MAX_DESCRIPTION = 110;
+function truncate(text, max = MAX_DESCRIPTION) {
+    const clean = text.replace(/\s+/g, " ").trim();
+    if (clean.length <= max)
+        return clean;
+    return `${clean.slice(0, max - 1).trimEnd()}…`;
+}
+/** Strip inline markdown that adds noise but no meaning in a prompt listing. */
+function stripInlineMarkdown(text) {
+    return text
+        .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") // links → their text
+        .replace(/[`*_]/g, "")
+        .trim();
+}
+function readHead(path) {
+    try {
+        // Whole-file read: these are small, and slicing bytes off a UTF-8 file can
+        // split a multi-byte character. Truncate after decoding instead.
+        return readFileSync(path, "utf-8").slice(0, HEAD_BYTES);
+    }
+    catch {
+        return "";
+    }
+}
+/** First `# ` heading, or undefined. */
+function firstHeading(markdown) {
+    for (const line of markdown.split(/\r?\n/)) {
+        const match = /^#\s+(.+)$/.exec(line.trim());
+        if (match?.[1])
+            return stripInlineMarkdown(match[1]);
+    }
+    return undefined;
+}
+/**
+ * First real prose line: not a heading, blockquote, list item, fence, or table
+ * row. Used only for docs the curated index does not describe.
+ */
+function firstParagraph(markdown) {
+    let inFence = false;
+    for (const raw of markdown.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line.startsWith("```")) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence || line === "")
+            continue;
+        if (/^[#>|-]/.test(line) || /^\d+\./.test(line))
+            continue;
+        return stripInlineMarkdown(line);
+    }
+    return undefined;
+}
+/**
+ * Titles and descriptions the docs maintain about themselves, keyed by filename.
+ *
+ * Matches list entries of the form `- [Title](file.md) - description`, which is
+ * how every section of `index.md` is written. Anything that does not match is
+ * skipped rather than guessed at.
+ */
+function parseCuratedIndex(docsRoot) {
+    const curated = new Map();
+    const indexPath = join(docsRoot, "index.md");
+    if (!existsSync(indexPath))
+        return curated;
+    let content;
+    try {
+        content = readFileSync(indexPath, "utf-8");
+    }
+    catch {
+        return curated;
+    }
+    // `[Title](file.md)` followed by a dash of any width and the description.
+    const entry = /^\s*[-*]\s*\[([^\]]+)\]\(([^)#]+\.md)\)\s*[-–—:]\s*(.+?)\s*$/;
+    for (const line of content.split(/\r?\n/)) {
+        const match = entry.exec(line);
+        if (!match)
+            continue;
+        const [, title, target, description] = match;
+        const file = basename(target);
+        if (curated.has(file))
+            continue; // first mention wins
+        curated.set(file, { title: stripInlineMarkdown(title), description: truncate(stripInlineMarkdown(description)) });
+    }
+    return curated;
+}
+function describe(path, file, curated) {
+    const fromIndex = curated.get(file);
+    if (fromIndex) {
+        return { id: file, path, title: fromIndex.title, description: fromIndex.description };
+    }
+    // Not in the curated index — derive from the doc itself so new files are
+    // still usable the day they land.
+    const head = readHead(path);
+    return {
+        id: file,
+        path,
+        title: firstHeading(head) ?? file.replace(/\.md$/, ""),
+        description: truncate(firstParagraph(head) ?? ""),
+    };
+}
+let cached;
+/** Drop the cached listing. Tests, and anything that relocates the package root. */
+export function resetSelfDocs() {
+    cached = undefined;
+    cachedSections = undefined;
+}
+/**
+ * Every shipped doc, sorted with the overview first and the rest alphabetical.
+ *
+ * Returns `[]` when the docs directory is absent rather than throwing: a source
+ * checkout, an odd packaging, or a trimmed container should degrade to "no docs
+ * section in the prompt", never to a failed session start.
+ */
+export function listSelfDocs() {
+    if (cached)
+        return cached;
+    const docsRoot = getDocsPath();
+    const docs = [];
+    if (existsSync(docsRoot)) {
+        const curated = parseCuratedIndex(docsRoot);
+        let files;
+        try {
+            files = readdirSync(docsRoot).filter((f) => f.endsWith(".md"));
+        }
+        catch {
+            files = [];
+        }
+        // Overview first: it is the doc that explains the others.
+        files.sort((a, b) => (a === "index.md" ? -1 : b === "index.md" ? 1 : a.localeCompare(b)));
+        for (const file of files) {
+            const path = join(docsRoot, file);
+            try {
+                if (!statSync(path).isFile())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            docs.push(describe(path, file, curated));
+        }
+    }
+    // README and CHANGELOG sit beside the docs directory, not inside it, but the
+    // model needs them for the two questions the docs do not answer: what
+    // hoocode is, and what changed in this version.
+    const extras = [
+        { path: getReadmePath(), title: "README", description: "What hoocode is, install, and a feature overview." },
+        {
+            path: getChangelogPath(),
+            title: "Changelog",
+            description: "Released versions and what changed in each.",
+        },
+    ];
+    for (const extra of extras) {
+        if (!existsSync(extra.path))
+            continue;
+        docs.push({ id: basename(extra.path), path: extra.path, title: extra.title, description: extra.description });
+    }
+    cached = docs;
+    return docs;
+}
+/**
+ * The system-prompt section, or `""` when there is nothing to point at.
+ *
+ * Deliberately just filenames. An earlier version carried a one-line summary
+ * per doc and cost ~860 tokens on every single turn, which is a poor trade for
+ * something most turns never use — and it stopped being necessary once
+ * SearchHooCode could retrieve at the heading level. Filenames alone still let
+ * the model go straight to `themes.md` or `keybindings.md` for the obvious
+ * cases, and anything less obvious is one search away. That is ~180 tokens.
+ *
+ * Directories are printed once rather than repeated per entry, for the same
+ * reason: the path was the single largest term on every line.
+ */
+export function formatSelfDocsForPrompt(docs = listSelfDocs()) {
+    if (docs.length === 0)
+        return "";
+    // Insertion order is already meaningful (overview first, then alphabetical,
+    // then README/CHANGELOG), so group without re-sorting.
+    const groups = new Map();
+    for (const doc of docs) {
+        const root = dirname(doc.path);
+        const bucket = groups.get(root);
+        if (bucket)
+            bucket.push(doc.id);
+        else
+            groups.set(root, [doc.id]);
+    }
+    const sections = [...groups].map(([root, files]) => `${root}/: ${files.join(", ")}`);
+    return `
+
+# About hoocode itself
+
+You are running inside hoocode. Its own docs ship with the install, listed below; hoocode is actively developed, so answer questions about it from these files rather than from memory. They sit outside the working directory, so searching the project will not find them. Use SearchHooCode to locate a specific heading, or read a file directly.
+
+${sections.join("\n")}`;
+}
+/**
+ * How much section body to keep.
+ *
+ * Every character past this is invisible to retrieval, so the cap is a recall
+ * limit, not just a size one: at 240 a question about `/grill` missed the
+ * section that documents it, because the term sat in the fourth sentence. 400
+ * covers the opening of essentially every section here for about 95KB more
+ * index across the corpus, which buys back that class of miss.
+ */
+const MAX_EXCERPT = 400;
+/** `Custom tools` → `custom-tools`, so ids stay stable and readable. */
+function slugify(heading) {
+    return (heading
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "section");
+}
+/** `extensions.md § Extensions › Custom tools` — what a search result is labelled with. */
+export function sectionLabel(section) {
+    return section.headings.length > 0 ? `${section.file} § ${section.headings.join(" › ")}` : section.file;
+}
+/**
+ * Split one markdown file into sections at its headings.
+ *
+ * Fenced code is tracked so a `#` comment inside a bash block cannot be
+ * mistaken for a heading — which would otherwise split docs at every shell
+ * comment. Code *content* still lands in the excerpt: the exact identifiers
+ * someone searches for (`pi.registerTool`) usually live in the examples, and
+ * dropping them would blind the lexical leg to the best terms in the file.
+ */
+export function splitIntoSections(markdown, file, path) {
+    const lines = markdown.split(/\r?\n/);
+    const sections = [];
+    const trail = [];
+    const usedIds = new Set();
+    let current;
+    let body = [];
+    let inFence = false;
+    const flush = () => {
+        if (!current)
+            return;
+        current.excerpt = truncate(stripInlineMarkdown(body.join(" ")), MAX_EXCERPT);
+        sections.push(current);
+        body = [];
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i] ?? "";
+        if (raw.trimStart().startsWith("```")) {
+            inFence = !inFence;
+            continue;
+        }
+        const heading = inFence ? null : /^(#{1,6})\s+(.+?)\s*$/.exec(raw);
+        if (!heading) {
+            if (raw.trim() !== "")
+                body.push(raw.trim());
+            continue;
+        }
+        flush();
+        const depth = heading[1]?.length ?? 1;
+        const text = stripInlineMarkdown(heading[2] ?? "");
+        while (trail.length > 0 && (trail[trail.length - 1]?.depth ?? 0) >= depth)
+            trail.pop();
+        trail.push({ depth, text });
+        // Disambiguate repeated headings ("Example" appears eleven times in
+        // extensions.md) so ids stay unique and the registry does not collapse them.
+        let id = `${file}#${slugify(trail.map((t) => t.text).join("-"))}`;
+        if (usedIds.has(id)) {
+            let n = 2;
+            while (usedIds.has(`${id}-${n}`))
+                n++;
+            id = `${id}-${n}`;
+        }
+        usedIds.add(id);
+        current = { id, file, path, headings: trail.map((t) => t.text), line: i + 1, excerpt: "" };
+    }
+    flush();
+    return sections;
+}
+/**
+ * Files kept out of the section index.
+ *
+ * The changelog is 40% of the corpus by section count and none of it answers
+ * "how does X work": it is hundreds of near-identical `Added`/`Fixed`/`Changed`
+ * headings under version numbers, which crowd real documentation out of the
+ * ranking while matching almost any query about a feature by name.
+ *
+ * `index.md` is excluded for the mirror-image reason: it is a table of contents,
+ * so its "sections" are lists of links whose text is every other doc's title and
+ * summary. That makes it match any query those docs would match, while carrying
+ * none of the content — a guaranteed false attractor that displaces the page it
+ * is pointing at.
+ *
+ * Both stay in the prompt's filename listing, one read away.
+ */
+const SECTION_INDEX_EXCLUDED = new Set(["CHANGELOG.md", "index.md"]);
+let cachedSections;
+/** Drop the cached section index. Tests, and anything that relocates the package root. */
+export function resetSelfDocSections() {
+    cachedSections = undefined;
+}
+/**
+ * Every section of every shipped doc.
+ *
+ * Reads each file once per session and caches; the docs are read-only install
+ * content, so there is nothing to invalidate on.
+ */
+export function listSelfDocSections() {
+    if (cachedSections)
+        return cachedSections;
+    const sections = [];
+    for (const doc of listSelfDocs()) {
+        if (SECTION_INDEX_EXCLUDED.has(doc.id))
+            continue;
+        let content;
+        try {
+            content = readFileSync(doc.path, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        sections.push(...splitIntoSections(content, doc.id, doc.path));
+    }
+    cachedSections = sections;
+    return sections;
+}
+//# sourceMappingURL=self-docs.js.map

package/dist/core/self-docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-docs.js","sourceRoot":"","sources":["../../src/core/self-docs.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The agent's index of hoocode's *own* documentation.\n *\n * The startup banner promises \"hoocode can explain its own features and look up\n * its docs\", and the docs really do ship with the install (`package.json`\n * `files` includes `docs`, and `copy-binary-assets` copies them into `dist/` for\n * the pkg binaries). What was missing is the only part that makes the promise\n * true: telling the model they exist. `getDocsPath()` had exactly one consumer —\n * `auth-guidance.ts`, which prints paths to the *human* — so nothing ever put a\n * docs path into model context.\n *\n * That gap is not one the model can close by itself. Its cwd is the user's\n * project, so `grep`/`find` there discover the user's docs, never hoocode's,\n * which live in an install directory whose path it cannot derive.\n *\n * Descriptions come from `docs/index.md` rather than being duplicated here.\n * That file is a curated, human-maintained table of contents, and a second\n * hand-written list is how an index goes stale the first week nobody updates\n * it. The directory listing stays the source of truth for *what exists*, so a\n * new doc still shows up (described from its own first paragraph) on the day it\n * lands, with or without an index entry.\n */\n\nimport { existsSync, readdirSync, readFileSync, statSync } from \"node:fs\";\nimport { basename, dirname, join } from \"node:path\";\nimport { getChangelogPath, getDocsPath, getReadmePath } from \"../config.js\";\n\nexport interface SelfDoc {\n\t/** Stable id: the filename, e.g. `skills.md`. Also how the model refers to it. */\n\tid: string;\n\t/** Absolute path, ready to hand to the read tool verbatim. */\n\tpath: string;\n\t/** Human title, e.g. \"Skills\". */\n\ttitle: string;\n\t/** One line on what the doc covers. May be empty if nothing could be derived. */\n\tdescription: string;\n}\n\n/** How much of a doc to read when deriving a fallback description. */\nconst HEAD_BYTES = 2048;\n\n/** Cap on a derived description, so one run-on opening line cannot bloat the prompt. */\nconst MAX_DESCRIPTION = 110;\n\nfunction truncate(text: string, max = MAX_DESCRIPTION): string {\n\tconst clean = text.replace(/\\s+/g, \" \").trim();\n\tif (clean.length <= max) return clean;\n\treturn `${clean.slice(0, max - 1).trimEnd()}…`;\n}\n\n/** Strip inline markdown that adds noise but no meaning in a prompt listing. */\nfunction stripInlineMarkdown(text: string): string {\n\treturn text\n\t\t.replace(/\\[([^\\]]+)\\]\\([^)]*\\)/g, \"$1\") // links → their text\n\t\t.replace(/[`*_]/g, \"\")\n\t\t.trim();\n}\n\nfunction readHead(path: string): string {\n\ttry {\n\t\t// Whole-file read: these are small, and slicing bytes off a UTF-8 file can\n\t\t// split a multi-byte character. Truncate after decoding instead.\n\t\treturn readFileSync(path, \"utf-8\").slice(0, HEAD_BYTES);\n\t} catch {\n\t\treturn \"\";\n\t}\n}\n\n/** First `# ` heading, or undefined. */\nfunction firstHeading(markdown: string): string | undefined {\n\tfor (const line of markdown.split(/\\r?\\n/)) {\n\t\tconst match = /^#\\s+(.+)$/.exec(line.trim());\n\t\tif (match?.[1]) return stripInlineMarkdown(match[1]);\n\t}\n\treturn undefined;\n}\n\n/**\n * First real prose line: not a heading, blockquote, list item, fence, or table\n * row. Used only for docs the curated index does not describe.\n */\nfunction firstParagraph(markdown: string): string | undefined {\n\tlet inFence = false;\n\tfor (const raw of markdown.split(/\\r?\\n/)) {\n\t\tconst line = raw.trim();\n\t\tif (line.startsWith(\"```\")) {\n\t\t\tinFence = !inFence;\n\t\t\tcontinue;\n\t\t}\n\t\tif (inFence || line === \"\") continue;\n\t\tif (/^[#>|-]/.test(line) || /^\\d+\\./.test(line)) continue;\n\t\treturn stripInlineMarkdown(line);\n\t}\n\treturn undefined;\n}\n\n/**\n * Titles and descriptions the docs maintain about themselves, keyed by filename.\n *\n * Matches list entries of the form `- [Title](file.md) - description`, which is\n * how every section of `index.md` is written. Anything that does not match is\n * skipped rather than guessed at.\n */\nfunction parseCuratedIndex(docsRoot: string): Map<string, { title: string; description: string }> {\n\tconst curated = new Map<string, { title: string; description: string }>();\n\tconst indexPath = join(docsRoot, \"index.md\");\n\tif (!existsSync(indexPath)) return curated;\n\n\tlet content: string;\n\ttry {\n\t\tcontent = readFileSync(indexPath, \"utf-8\");\n\t} catch {\n\t\treturn curated;\n\t}\n\n\t// `[Title](file.md)` followed by a dash of any width and the description.\n\tconst entry = /^\\s*[-*]\\s*\\[([^\\]]+)\\]\\(([^)#]+\\.md)\\)\\s*[-–—:]\\s*(.+?)\\s*$/;\n\tfor (const line of content.split(/\\r?\\n/)) {\n\t\tconst match = entry.exec(line);\n\t\tif (!match) continue;\n\t\tconst [, title, target, description] = match;\n\t\tconst file = basename(target);\n\t\tif (curated.has(file)) continue; // first mention wins\n\t\tcurated.set(file, { title: stripInlineMarkdown(title), description: truncate(stripInlineMarkdown(description)) });\n\t}\n\treturn curated;\n}\n\nfunction describe(path: string, file: string, curated: Map<string, { title: string; description: string }>): SelfDoc {\n\tconst fromIndex = curated.get(file);\n\tif (fromIndex) {\n\t\treturn { id: file, path, title: fromIndex.title, description: fromIndex.description };\n\t}\n\t// Not in the curated index — derive from the doc itself so new files are\n\t// still usable the day they land.\n\tconst head = readHead(path);\n\treturn {\n\t\tid: file,\n\t\tpath,\n\t\ttitle: firstHeading(head) ?? file.replace(/\\.md$/, \"\"),\n\t\tdescription: truncate(firstParagraph(head) ?? \"\"),\n\t};\n}\n\nlet cached: SelfDoc[] | undefined;\n\n/** Drop the cached listing. Tests, and anything that relocates the package root. */\nexport function resetSelfDocs(): void {\n\tcached = undefined;\n\tcachedSections = undefined;\n}\n\n/**\n * Every shipped doc, sorted with the overview first and the rest alphabetical.\n *\n * Returns `[]` when the docs directory is absent rather than throwing: a source\n * checkout, an odd packaging, or a trimmed container should degrade to \"no docs\n * section in the prompt\", never to a failed session start.\n */\nexport function listSelfDocs(): SelfDoc[] {\n\tif (cached) return cached;\n\n\tconst docsRoot = getDocsPath();\n\tconst docs: SelfDoc[] = [];\n\n\tif (existsSync(docsRoot)) {\n\t\tconst curated = parseCuratedIndex(docsRoot);\n\t\tlet files: string[];\n\t\ttry {\n\t\t\tfiles = readdirSync(docsRoot).filter((f) => f.endsWith(\".md\"));\n\t\t} catch {\n\t\t\tfiles = [];\n\t\t}\n\t\t// Overview first: it is the doc that explains the others.\n\t\tfiles.sort((a, b) => (a === \"index.md\" ? -1 : b === \"index.md\" ? 1 : a.localeCompare(b)));\n\t\tfor (const file of files) {\n\t\t\tconst path = join(docsRoot, file);\n\t\t\ttry {\n\t\t\t\tif (!statSync(path).isFile()) continue;\n\t\t\t} catch {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tdocs.push(describe(path, file, curated));\n\t\t}\n\t}\n\n\t// README and CHANGELOG sit beside the docs directory, not inside it, but the\n\t// model needs them for the two questions the docs do not answer: what\n\t// hoocode is, and what changed in this version.\n\tconst extras: Array<{ path: string; title: string; description: string }> = [\n\t\t{ path: getReadmePath(), title: \"README\", description: \"What hoocode is, install, and a feature overview.\" },\n\t\t{\n\t\t\tpath: getChangelogPath(),\n\t\t\ttitle: \"Changelog\",\n\t\t\tdescription: \"Released versions and what changed in each.\",\n\t\t},\n\t];\n\tfor (const extra of extras) {\n\t\tif (!existsSync(extra.path)) continue;\n\t\tdocs.push({ id: basename(extra.path), path: extra.path, title: extra.title, description: extra.description });\n\t}\n\n\tcached = docs;\n\treturn docs;\n}\n\n/**\n * The system-prompt section, or `\"\"` when there is nothing to point at.\n *\n * Deliberately just filenames. An earlier version carried a one-line summary\n * per doc and cost ~860 tokens on every single turn, which is a poor trade for\n * something most turns never use — and it stopped being necessary once\n * SearchHooCode could retrieve at the heading level. Filenames alone still let\n * the model go straight to `themes.md` or `keybindings.md` for the obvious\n * cases, and anything less obvious is one search away. That is ~180 tokens.\n *\n * Directories are printed once rather than repeated per entry, for the same\n * reason: the path was the single largest term on every line.\n */\nexport function formatSelfDocsForPrompt(docs: readonly SelfDoc[] = listSelfDocs()): string {\n\tif (docs.length === 0) return \"\";\n\n\t// Insertion order is already meaningful (overview first, then alphabetical,\n\t// then README/CHANGELOG), so group without re-sorting.\n\tconst groups = new Map<string, string[]>();\n\tfor (const doc of docs) {\n\t\tconst root = dirname(doc.path);\n\t\tconst bucket = groups.get(root);\n\t\tif (bucket) bucket.push(doc.id);\n\t\telse groups.set(root, [doc.id]);\n\t}\n\n\tconst sections = [...groups].map(([root, files]) => `${root}/: ${files.join(\", \")}`);\n\n\treturn `\n\n# About hoocode itself\n\nYou are running inside hoocode. Its own docs ship with the install, listed below; hoocode is actively developed, so answer questions about it from these files rather than from memory. They sit outside the working directory, so searching the project will not find them. Use SearchHooCode to locate a specific heading, or read a file directly.\n\n${sections.join(\"\\n\")}`;\n}\n\n// ---------------------------------------------------------------------------\n// Section index\n// ---------------------------------------------------------------------------\n\n/**\n * A single heading's worth of a doc.\n *\n * Doc-level retrieval would add nothing the prompt listing above does not\n * already give: thirty files with a summary each are cheap enough to list in\n * full, so a search that answers \"read extensions.md\" is a round trip for\n * information the model already had. The questions that actually need\n * retrieval are the ones inside a 1,100-line file — \"how do I register a\n * tool?\" should land on `extensions.md § Custom tools` with a line number, not\n * on the file.\n */\nexport interface SelfDocSection {\n\t/** `<file>#<slug>`, unique across the corpus. */\n\tid: string;\n\t/** Filename, e.g. `extensions.md`. */\n\tfile: string;\n\t/** Absolute path to the file. */\n\tpath: string;\n\t/** Heading trail from the document title down, e.g. `[\"Extensions\", \"Custom tools\"]`. */\n\theadings: string[];\n\t/** 1-based line of the heading, so a reader can jump straight to it. */\n\tline: number;\n\t/** Start of the section body, for ranking and for showing why a hit matched. */\n\texcerpt: string;\n}\n\n/**\n * How much section body to keep.\n *\n * Every character past this is invisible to retrieval, so the cap is a recall\n * limit, not just a size one: at 240 a question about `/grill` missed the\n * section that documents it, because the term sat in the fourth sentence. 400\n * covers the opening of essentially every section here for about 95KB more\n * index across the corpus, which buys back that class of miss.\n */\nconst MAX_EXCERPT = 400;\n\n/** `Custom tools` → `custom-tools`, so ids stay stable and readable. */\nfunction slugify(heading: string): string {\n\treturn (\n\t\theading\n\t\t\t.toLowerCase()\n\t\t\t.replace(/[^a-z0-9]+/g, \"-\")\n\t\t\t.replace(/^-+|-+$/g, \"\") || \"section\"\n\t);\n}\n\n/** `extensions.md § Extensions › Custom tools` — what a search result is labelled with. */\nexport function sectionLabel(section: SelfDocSection): string {\n\treturn section.headings.length > 0 ? `${section.file} § ${section.headings.join(\" › \")}` : section.file;\n}\n\n/**\n * Split one markdown file into sections at its headings.\n *\n * Fenced code is tracked so a `#` comment inside a bash block cannot be\n * mistaken for a heading — which would otherwise split docs at every shell\n * comment. Code *content* still lands in the excerpt: the exact identifiers\n * someone searches for (`pi.registerTool`) usually live in the examples, and\n * dropping them would blind the lexical leg to the best terms in the file.\n */\nexport function splitIntoSections(markdown: string, file: string, path: string): SelfDocSection[] {\n\tconst lines = markdown.split(/\\r?\\n/);\n\tconst sections: SelfDocSection[] = [];\n\tconst trail: Array<{ depth: number; text: string }> = [];\n\tconst usedIds = new Set<string>();\n\n\tlet current: SelfDocSection | undefined;\n\tlet body: string[] = [];\n\tlet inFence = false;\n\n\tconst flush = (): void => {\n\t\tif (!current) return;\n\t\tcurrent.excerpt = truncate(stripInlineMarkdown(body.join(\" \")), MAX_EXCERPT);\n\t\tsections.push(current);\n\t\tbody = [];\n\t};\n\n\tfor (let i = 0; i < lines.length; i++) {\n\t\tconst raw = lines[i] ?? \"\";\n\t\tif (raw.trimStart().startsWith(\"```\")) {\n\t\t\tinFence = !inFence;\n\t\t\tcontinue;\n\t\t}\n\t\tconst heading = inFence ? null : /^(#{1,6})\\s+(.+?)\\s*$/.exec(raw);\n\t\tif (!heading) {\n\t\t\tif (raw.trim() !== \"\") body.push(raw.trim());\n\t\t\tcontinue;\n\t\t}\n\n\t\tflush();\n\n\t\tconst depth = heading[1]?.length ?? 1;\n\t\tconst text = stripInlineMarkdown(heading[2] ?? \"\");\n\t\twhile (trail.length > 0 && (trail[trail.length - 1]?.depth ?? 0) >= depth) trail.pop();\n\t\ttrail.push({ depth, text });\n\n\t\t// Disambiguate repeated headings (\"Example\" appears eleven times in\n\t\t// extensions.md) so ids stay unique and the registry does not collapse them.\n\t\tlet id = `${file}#${slugify(trail.map((t) => t.text).join(\"-\"))}`;\n\t\tif (usedIds.has(id)) {\n\t\t\tlet n = 2;\n\t\t\twhile (usedIds.has(`${id}-${n}`)) n++;\n\t\t\tid = `${id}-${n}`;\n\t\t}\n\t\tusedIds.add(id);\n\n\t\tcurrent = { id, file, path, headings: trail.map((t) => t.text), line: i + 1, excerpt: \"\" };\n\t}\n\tflush();\n\n\treturn sections;\n}\n\n/**\n * Files kept out of the section index.\n *\n * The changelog is 40% of the corpus by section count and none of it answers\n * \"how does X work\": it is hundreds of near-identical `Added`/`Fixed`/`Changed`\n * headings under version numbers, which crowd real documentation out of the\n * ranking while matching almost any query about a feature by name.\n *\n * `index.md` is excluded for the mirror-image reason: it is a table of contents,\n * so its \"sections\" are lists of links whose text is every other doc's title and\n * summary. That makes it match any query those docs would match, while carrying\n * none of the content — a guaranteed false attractor that displaces the page it\n * is pointing at.\n *\n * Both stay in the prompt's filename listing, one read away.\n */\nconst SECTION_INDEX_EXCLUDED = new Set([\"CHANGELOG.md\", \"index.md\"]);\n\nlet cachedSections: SelfDocSection[] | undefined;\n\n/** Drop the cached section index. Tests, and anything that relocates the package root. */\nexport function resetSelfDocSections(): void {\n\tcachedSections = undefined;\n}\n\n/**\n * Every section of every shipped doc.\n *\n * Reads each file once per session and caches; the docs are read-only install\n * content, so there is nothing to invalidate on.\n */\nexport function listSelfDocSections(): SelfDocSection[] {\n\tif (cachedSections) return cachedSections;\n\n\tconst sections: SelfDocSection[] = [];\n\tfor (const doc of listSelfDocs()) {\n\t\tif (SECTION_INDEX_EXCLUDED.has(doc.id)) continue;\n\t\tlet content: string;\n\t\ttry {\n\t\t\tcontent = readFileSync(doc.path, \"utf-8\");\n\t\t} catch {\n\t\t\tcontinue;\n\t\t}\n\t\tsections.push(...splitIntoSections(content, doc.id, doc.path));\n\t}\n\n\tcachedSections = sections;\n\treturn sections;\n}\n"]}

package/dist/core/system-prompt.d.ts

@@ -29,6 +29,18 @@ export interface BuildSystemPromptOptions {
      * agents exist without re-reading the agent registry each turn.
      */
     agents?: AgentDefinition[];
+    /**
+     * Point the model at hoocode's own shipped docs so it can answer questions
+     * about hoocode itself.
+     *
+     * Defaults to true for the built-in prompt and false when `customPrompt`
+     * replaces it. Every other appended section (context files, skills, agents)
+     * only appears because the caller passed the content in; this one
+     * materializes on its own, so a caller who has taken over the system prompt
+     * gets it only by asking. That also keeps it out of light mode, whose whole
+     * point is a minimal fixed per-turn surface. Needs the read tool either way.
+     */
+    includeSelfDocs?: boolean;
 }
 /** Build the system prompt with tools, guidelines, and context */
 export declare function buildSystemPrompt(options: BuildSystemPromptOptions): string;