@hraness/kb 0.18.0 → 0.19.0

package/dist/{index-s2gw5aw9.js → index-qwgsmtsz.js}

@@ -1,7 +1,7 @@
 // @bun
 import {
   fuseRankedCandidates
-} from "./index-cv6fh7z5.js";
+} from "./index-gm9t95d9.js";
 
 // src/benchmark.ts
 var MAX_BENCHMARK_CASES = 500;

package/dist/{index-zzhgcwyt.js → index-vxmf14m1.js}

@@ -8,7 +8,7 @@ import {
   openSemanticSearchSession,
   recommendedEmbeddingModel,
   scanVault
-} from "./index-zxdy5pby.js";
+} from "./index-5m2ydj5q.js";
 import {
   UntrustedContentBudgetError,
   createUntrustedToolResult
@@ -27,7 +27,7 @@ import {
   fuseRankedCandidates,
   searchExactVault,
   validateSearchQuery
-} from "./index-cv6fh7z5.js";
+} from "./index-gm9t95d9.js";
 import {
   NavigationBudgetError,
   navigateLinks
@@ -37,7 +37,7 @@ import {
 } from "./index-48pz4jpc.js";
 import {
   lookupNote
-} from "./index-cxfrakt7.js";
+} from "./index-ekpwvbra.js";
 
 // src/sdk.ts
 import { resolve } from "path";

package/dist/{index-n5dd7r0v.js → index-xw9ac71d.js}

@@ -2,10 +2,10 @@
 import {
   MAX_SEARCH_RESULTS,
   openKnowledgeBase
-} from "./index-zzhgcwyt.js";
+} from "./index-vxmf14m1.js";
 import {
   scanVault
-} from "./index-zxdy5pby.js";
+} from "./index-5m2ydj5q.js";
 import {
   runGitCommand
 } from "./index-1gwbassd.js";

package/dist/{index-1vrd1rmn.js → index-ykvvkd77.js}

@@ -4,7 +4,7 @@ import {
 } from "./index-3v2z4f0q.js";
 import {
   packUntrustedSearchContext
-} from "./index-zzhgcwyt.js";
+} from "./index-vxmf14m1.js";
 
 // src/workflows/decision-context.ts
 var decisionContextWorkflow = defineWorkflow({

package/dist/index.js

@@ -29,15 +29,25 @@ import {
   MAX_PERCOLATION_MENTIONS,
   MAX_PERCOLATION_MENTION_PAIRS,
   MAX_PERCOLATION_NOTES,
+  MAX_PERCOLATION_RESULT_NODES,
+  MAX_PERCOLATION_RESULT_UTF8_BYTES,
+  MAX_PERCOLATION_TEXT_UTF8_BYTES,
   MAX_SCOPED_PERCOLATION_MENTION_PAIRS,
+  PERCOLATION_RESULT_SCHEMA_VERSION,
+  parsePercolationCliOutput,
+  parsePercolationCliOutputV1,
+  parsePercolationCliOutputV2,
+  parsePercolationResult,
+  parsePercolationResultV1,
+  parsePercolationResultV2,
   percolateVault
-} from "./index-dyqwejk5.js";
+} from "./index-nd6nynv2.js";
 import {
   FrozenEvaluationSnapshotError,
   knowledgeBaseEvaluationRetrieverIds,
   openKnowledgeBaseEvaluation,
   verifyFrozenEvaluationSnapshot
-} from "./index-n5dd7r0v.js";
+} from "./index-xw9ac71d.js";
 import {
   DEFAULT_SEARCH_RESULTS,
   MAX_SEARCH_CANDIDATES,
@@ -49,7 +59,7 @@ import {
   packSearchContext,
   packUntrustedSearchContext,
   validateKnowledgeBaseSearchHistory
-} from "./index-zzhgcwyt.js";
+} from "./index-vxmf14m1.js";
 import"./index-adx6khj5.js";
 import {
   MAX_EMBEDDING_MODEL_BYTES,
@@ -75,7 +85,7 @@ import {
   searchSemanticVault,
   semanticDatabasePath,
   sha256EmbeddingModelFile
-} from "./index-zxdy5pby.js";
+} from "./index-5m2ydj5q.js";
 import"./index-4j3tt0c3.js";
 import {
   GitHistoryError,
@@ -144,14 +154,14 @@ import {
   normalizeRelationPredicate,
   noteRevision,
   removeNoteRelation
-} from "./index-01jj6rbv.js";
+} from "./index-gxr0fctd.js";
 import"./index-3rm7cz6h.js";
 import {
   createRepresentativeRetrievalFixture,
   createSyntheticRankFusionFixture,
   evaluateRanking,
   evaluateRetrievalBenchmark
-} from "./index-s2gw5aw9.js";
+} from "./index-qwgsmtsz.js";
 import {
   MAX_SEARCH_QUERY_BYTES,
   MAX_SEARCH_QUERY_TERMS,
@@ -159,7 +169,7 @@ import {
   fuseRankedCandidates,
   searchExactVault,
   validateSearchQuery
-} from "./index-cv6fh7z5.js";
+} from "./index-gm9t95d9.js";
 import {
   MAX_NAVIGATION_INDEXED_CONNECTIONS,
   MAX_NAVIGATION_RETURNED_CONNECTIONS,
@@ -235,6 +245,7 @@ import {
   catalogEnd,
   catalogStart,
   isCanonicalNoteId,
+  isCanonicalRelationPredicate,
   lookupNote,
   metadataValueFromUnknown,
   normalizeVaultPath,
@@ -243,7 +254,7 @@ import {
   replaceCatalog,
   searchableMarkdown,
   wikiLinks
-} from "./index-cxfrakt7.js";
+} from "./index-ekpwvbra.js";
 import"./index-1xxnjn0d.js";
 // src/oh-adoption.ts
 import { createHash } from "crypto";
@@ -593,6 +604,12 @@ export {
   planStatuses,
   percolateVault,
   parseRetrievalEvaluationCorpus,
+  parsePercolationResultV2,
+  parsePercolationResultV1,
+  parsePercolationResult,
+  parsePercolationCliOutputV2,
+  parsePercolationCliOutputV1,
+  parsePercolationCliOutput,
   parseNote,
   parseLocalAttachmentReferences,
   parseGitHistoryOutput,
@@ -618,6 +635,7 @@ export {
   knowledgeBaseEvaluationRetrieverIds,
   isTerminalPlanStatus,
   isPlanStatus,
+  isCanonicalRelationPredicate,
   isCanonicalNoteId,
   isActivePlanStatus,
   inspectRepositoryScopeState,
@@ -677,6 +695,7 @@ export {
   RepositoryScopeError,
   RETRIEVAL_EVALUATION_SCHEMA_VERSION,
   RETRIEVAL_EVALUATION_REPORT_VERSION,
+  PERCOLATION_RESULT_SCHEMA_VERSION,
   NoteRevisionConflictError,
   NoteRecoveryRequiredError,
   NoteAlreadyExistsError,
@@ -714,6 +733,9 @@ export {
   MAX_QUERY_METADATA_PATH_SEGMENTS,
   MAX_QUERY_FILTER_VALUES,
   MAX_QUERY_FILTERS,
+  MAX_PERCOLATION_TEXT_UTF8_BYTES,
+  MAX_PERCOLATION_RESULT_UTF8_BYTES,
+  MAX_PERCOLATION_RESULT_NODES,
   MAX_PERCOLATION_NOTES,
   MAX_PERCOLATION_MENTION_PAIRS,
   MAX_PERCOLATION_MENTIONS,

package/dist/percolate.js

@@ -7,13 +7,33 @@ import {
   MAX_PERCOLATION_MENTIONS,
   MAX_PERCOLATION_MENTION_PAIRS,
   MAX_PERCOLATION_NOTES,
+  MAX_PERCOLATION_RESULT_NODES,
+  MAX_PERCOLATION_RESULT_UTF8_BYTES,
+  MAX_PERCOLATION_TEXT_UTF8_BYTES,
   MAX_SCOPED_PERCOLATION_MENTION_PAIRS,
+  PERCOLATION_RESULT_SCHEMA_VERSION,
+  parsePercolationCliOutput,
+  parsePercolationCliOutputV1,
+  parsePercolationCliOutputV2,
+  parsePercolationResult,
+  parsePercolationResultV1,
+  parsePercolationResultV2,
   percolateVault
-} from "./index-dyqwejk5.js";
-import"./index-cxfrakt7.js";
+} from "./index-nd6nynv2.js";
+import"./index-ekpwvbra.js";
 export {
   percolateVault,
+  parsePercolationResultV2,
+  parsePercolationResultV1,
+  parsePercolationResult,
+  parsePercolationCliOutputV2,
+  parsePercolationCliOutputV1,
+  parsePercolationCliOutput,
+  PERCOLATION_RESULT_SCHEMA_VERSION,
   MAX_SCOPED_PERCOLATION_MENTION_PAIRS,
+  MAX_PERCOLATION_TEXT_UTF8_BYTES,
+  MAX_PERCOLATION_RESULT_UTF8_BYTES,
+  MAX_PERCOLATION_RESULT_NODES,
   MAX_PERCOLATION_NOTES,
   MAX_PERCOLATION_MENTION_PAIRS,
   MAX_PERCOLATION_MENTIONS,

package/dist/portfolio.js

@@ -20,14 +20,14 @@ import {
   selectAuthorizedVaults,
   snapshotPortfolioRegistry,
   validateResolvedPortfolioVaults
-} from "./index-jsmvyyvf.js";
-import"./index-zzhgcwyt.js";
+} from "./index-ey46z1zf.js";
+import"./index-vxmf14m1.js";
 import"./index-adx6khj5.js";
-import"./index-zxdy5pby.js";
+import"./index-5m2ydj5q.js";
 import"./index-4j3tt0c3.js";
 import"./index-1gwbassd.js";
 import"./index-x3fthpsc.js";
-import"./index-cv6fh7z5.js";
+import"./index-gm9t95d9.js";
 import"./index-d13v9ckt.js";
 import"./index-48pz4jpc.js";
 import"./index-06c9ctr6.js";
@@ -42,7 +42,7 @@ import {
   parseVaultKey,
   portfolioDocumentIdentity,
   portfolioVaultIdentity
-} from "./index-cxfrakt7.js";
+} from "./index-ekpwvbra.js";
 import"./index-1xxnjn0d.js";
 export {
   validateResolvedPortfolioVaults,

package/dist/sdk.js

@@ -10,17 +10,17 @@ import {
   packSearchContext,
   packUntrustedSearchContext,
   validateKnowledgeBaseSearchHistory
-} from "./index-zzhgcwyt.js";
+} from "./index-vxmf14m1.js";
 import"./index-adx6khj5.js";
-import"./index-zxdy5pby.js";
+import"./index-5m2ydj5q.js";
 import"./index-4j3tt0c3.js";
 import"./index-1gwbassd.js";
-import"./index-cv6fh7z5.js";
+import"./index-gm9t95d9.js";
 import"./index-d13v9ckt.js";
 import"./index-48pz4jpc.js";
 import"./index-06c9ctr6.js";
 import"./index-5vwpzb5a.js";
-import"./index-cxfrakt7.js";
+import"./index-ekpwvbra.js";
 import"./index-1xxnjn0d.js";
 export {
   validateKnowledgeBaseSearchHistory,

package/dist/search.js

@@ -6,12 +6,12 @@ import {
   fuseRankedCandidates,
   searchExactVault,
   validateSearchQuery
-} from "./index-cv6fh7z5.js";
+} from "./index-gm9t95d9.js";
 import"./index-d13v9ckt.js";
 import"./index-48pz4jpc.js";
 import"./index-06c9ctr6.js";
 import"./index-5vwpzb5a.js";
-import"./index-cxfrakt7.js";
+import"./index-ekpwvbra.js";
 export {
   validateSearchQuery,
   searchExactVault,

package/dist/semantic.js

@@ -14,13 +14,13 @@ import {
   searchSemanticVault,
   semanticDatabasePath,
   sha256EmbeddingModelFile
-} from "./index-zxdy5pby.js";
-import"./index-cv6fh7z5.js";
+} from "./index-5m2ydj5q.js";
+import"./index-gm9t95d9.js";
 import"./index-d13v9ckt.js";
 import"./index-48pz4jpc.js";
 import"./index-06c9ctr6.js";
 import"./index-5vwpzb5a.js";
-import"./index-cxfrakt7.js";
+import"./index-ekpwvbra.js";
 export {
   sha256EmbeddingModelFile,
   semanticDatabasePath,

package/dist/workflows/decision-context.js

@@ -1,19 +1,19 @@
 // @bun
 import {
   decisionContextWorkflow
-} from "../index-1vrd1rmn.js";
+} from "../index-ykvvkd77.js";
 import"../index-3v2z4f0q.js";
-import"../index-zzhgcwyt.js";
+import"../index-vxmf14m1.js";
 import"../index-adx6khj5.js";
-import"../index-zxdy5pby.js";
+import"../index-5m2ydj5q.js";
 import"../index-4j3tt0c3.js";
 import"../index-1gwbassd.js";
-import"../index-cv6fh7z5.js";
+import"../index-gm9t95d9.js";
 import"../index-d13v9ckt.js";
 import"../index-48pz4jpc.js";
 import"../index-06c9ctr6.js";
 import"../index-5vwpzb5a.js";
-import"../index-cxfrakt7.js";
+import"../index-ekpwvbra.js";
 import"../index-1xxnjn0d.js";
 export {
   decisionContextWorkflow

package/dist/workflows/index.js

@@ -1,7 +1,7 @@
 // @bun
 import {
   decisionContextWorkflow
-} from "../index-1vrd1rmn.js";
+} from "../index-ykvvkd77.js";
 import {
   explainChangeWorkflow
 } from "../index-zr53sf63.js";
@@ -9,17 +9,17 @@ import {
   planRadarWorkflow
 } from "../index-vvdj6kca.js";
 import"../index-3v2z4f0q.js";
-import"../index-zzhgcwyt.js";
+import"../index-vxmf14m1.js";
 import"../index-adx6khj5.js";
-import"../index-zxdy5pby.js";
+import"../index-5m2ydj5q.js";
 import"../index-4j3tt0c3.js";
 import"../index-1gwbassd.js";
-import"../index-cv6fh7z5.js";
+import"../index-gm9t95d9.js";
 import"../index-d13v9ckt.js";
 import"../index-48pz4jpc.js";
 import"../index-06c9ctr6.js";
 import"../index-5vwpzb5a.js";
-import"../index-cxfrakt7.js";
+import"../index-ekpwvbra.js";
 import"../index-1xxnjn0d.js";
 export {
   planRadarWorkflow,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/kb",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "A knowledge base for coding agents, built from Markdown, backlinks, semantic search, and Git context.",
   "license": "MIT",
   "contentPolicy": {

package/skills/kb/AGENTS.md

@@ -2,10 +2,12 @@
 
 - `SKILL.md` – public entrypoint, runtime contract, and intent router for all hraness/kb agent workflows.
 - `references/query.md` – scoped retrieval through exact metadata, hybrid search, graph structure, and Git provenance.
+- `references/customize.md` and `companion-skills.md` – interview-first KB setup, explicit approval boundaries, and contracts for optional recurring rituals.
 - `references/save-url.md`, `url-authentication.md`, and `url-platforms.md` – auditable web capture, signed-in source handling, and platform-specific completeness boundaries.
 - `references/save-pdf.md` and `pdf-review.md` – PDF ingestion, OCR, image evidence, and mixed-media review.
 - `references/plan.md` and `plan-structure.md` – durable plan authoring and its adaptable Markdown contract.
 - `references/percolate.md` and `refresh.md` – evidence-backed graph edits, catalog maintenance, and vault validation.
+- `templates/companion-skill.template.md` – inert, copyable starting point for an approved companion skill.
 - `agents/openai.yaml` – user-facing skill metadata and invocation prompt.
 
 # Guidelines
@@ -14,6 +16,7 @@
 - Keep discovery language grounded in real user requests for knowledge bases, coding-agent memory, Markdown or Obsidian vaults, source capture, repository context, plans, and knowledge graphs. Exclude generic research, PDF reading, and planning outside hraness/kb.
 - Invoke the installed `kb` CLI without depending on a source checkout. Check for an existing command first, require Bun when installation is needed, and pin installation to the current immutable repository tag.
 - Never initialize or mutate a vault as part of skill or CLI installation.
+- Route setup, evolution, and custom-ritual requests before runtime discovery. Keep inspection non-mutating until the exact proposal is approved, and never treat skill discovery or an ambient account as authority.
 - Keep Markdown authoritative. Preserve incomplete source boundaries, read cited evidence before graph edits, and never generate reciprocal, inferred, transitive, or similarity-derived relationships.
 - In parallel managed-catalog work, defer refresh to the integrating agent and use the catalog-skipping check in each edit lane. Authored-catalog refreshes leave the front door unchanged.
 - Update `agents/openai.yaml`, README installation text, package inventory checks, and the pinned CLI tag together when the skill identity or package release changes.

package/skills/kb/SKILL.md

@@ -1,14 +1,16 @@
 ---
 name: kb
 description: >-
-  Operate a hraness/kb local-first Markdown knowledge base for coding-agent
-  memory. Use when a user asks to search or query a KB or Obsidian vault; load
+  Set up, evolve, or operate a hraness/kb local-first Markdown knowledge base
+  for coding-agent memory. Use when a user asks to design KB conventions or a
+  recurring KB ritual; search or query a KB or Obsidian vault; load or recover
   repository context, plans, decisions, concepts, backlinks, semantic search,
-  or Git provenance; save, clip, scrape, or archive a URL, article, social
-  thread, signed-in browser page, or PDF as auditable Markdown; create or
-  update a durable plan in the vault; or refresh, check, percolate, and
-  maintain its knowledge graph. Do not use for generic web research, generic
-  PDF reading, or ordinary planning that will not use a hraness/kb vault.
+  or Git provenance from an earlier coding session; save, clip, scrape, or
+  archive a URL, article, social thread, signed-in browser page, or PDF as
+  auditable Markdown; create or update a durable plan in the vault; or refresh,
+  check, percolate, and maintain its knowledge graph. Do not use for generic
+  web research, generic PDF reading, or ordinary planning that will not use a
+  hraness/kb vault.
 ---
 
 # Work with KB
@@ -17,7 +19,29 @@ Use hraness/kb to preserve and retrieve inspectable agent memory in Markdown
 and Git. Select the smallest workflow that matches the request, then load only
 its references.
 
-## Prepare the runtime
+## Route the request
+
+Route the request before discovering, installing, or running the CLI. A setup,
+evolution, or custom-ritual request begins with read-only inspection and an
+approved proposal; it does not require a runtime merely because this skill was
+selected.
+
+| User intent | Read |
+| --- | --- |
+| Design, set up, or evolve a KB; choose its boundaries and conventions; or define a recurring KB ritual | [Customize a KB setup](references/customize.md); add [Companion skill contracts](references/companion-skills.md) only when the proposal includes a new or revised skill |
+| Recover work from an earlier session, find notes, search one vault or an authorized portfolio, load repository-path context, inspect plans or decisions, follow backlinks or relationships, audit vault organization, or retrieve Git provenance | [Query the knowledge base](references/query.md) |
+| Save, clip, scrape, or archive a URL, article, social post or thread, GitHub or Discourse discussion, signed-in page, feed, inbox, private document, WhatsApp conversation, or YouTube page | [Capture web content](references/save-url.md); add [browser authentication](references/url-authentication.md) for signed-in sources and [platform routing](references/url-platforms.md) when route choice or completeness matters |
+| Import, extract, archive, OCR, or convert a local or public PDF into Markdown | [Save a PDF](references/save-pdf.md); add [PDF image review](references/pdf-review.md) for scans, screenshots, conversations, charts, or mixed media |
+| Create or update an implementation plan, proposal, RFC, migration plan, execution audit, or phased checklist in the vault | [Write a durable plan](references/plan.md) and [use its structure](references/plan-structure.md) |
+| Review recurring ideas, promote concepts, or add and verify typed relationships | [Percolate concepts and relationships](references/percolate.md) |
+| Refresh or validate the catalog, graph, attachments, repository scopes, context mappings, or overall vault health | [Refresh and check the knowledge base](references/refresh.md) |
+
+Read more than one primary reference only when the request spans those
+workflows. For example, saving a source and linking it from a maintained note
+uses the capture workflow followed by the relevant percolation and refresh
+steps.
+
+## Prepare the runtime when execution needs it
 
 Use an existing `kb` command when one is available. Do not reinstall or upgrade
 it merely because this skill loaded.
@@ -31,7 +55,7 @@ missing:
 ```sh
 command -v kb >/dev/null 2>&1 || {
   command -v bun >/dev/null 2>&1 || exit 1
-  bun add --global @hraness/kb@0.18.0
+  bun add --global @hraness/kb@0.19.0
 }
 kb --help
 ```
@@ -46,28 +70,13 @@ Installation ends after command verification. Never run `kb init`, create a
 vault, refresh a catalog, or edit Markdown as an installation side effect.
 Initialize or mutate a vault only when the user's request requires that change.
 
-## Route the request
-
-| User intent | Read |
-| --- | --- |
-| Find notes, search one vault or an authorized portfolio, load repository-path context, inspect plans or decisions, follow backlinks or relationships, audit vault organization, or retrieve Git provenance | [Query the knowledge base](references/query.md) |
-| Save, clip, scrape, or archive a URL, article, social post or thread, GitHub or Discourse discussion, signed-in page, feed, inbox, private document, WhatsApp conversation, or YouTube page | [Capture web content](references/save-url.md); add [browser authentication](references/url-authentication.md) for signed-in sources and [platform routing](references/url-platforms.md) when route choice or completeness matters |
-| Import, extract, archive, OCR, or convert a local or public PDF into Markdown | [Save a PDF](references/save-pdf.md); add [PDF image review](references/pdf-review.md) for scans, screenshots, conversations, charts, or mixed media |
-| Create or update an implementation plan, proposal, RFC, migration plan, execution audit, or phased checklist in the vault | [Write a durable plan](references/plan.md) and [use its structure](references/plan-structure.md) |
-| Review recurring ideas, promote concepts, or add and verify typed relationships | [Percolate concepts and relationships](references/percolate.md) |
-| Refresh or validate the catalog, graph, attachments, repository scopes, context mappings, or overall vault health | [Refresh and check the knowledge base](references/refresh.md) |
-
-Read more than one primary reference only when the request spans those
-workflows. For example, saving a source and linking it from a maintained note
-uses the capture workflow followed by the relevant percolation and refresh
-steps.
-
 ## Preserve the KB contract
 
-- Resolve `KB_ROOT` to the existing vault directory that contains its managed
-  or authored `index.md`. Read the applicable repository and vault
-  `AGENTS.md` files before writing. Do not assume the session started in the
-  vault.
+- For an existing vault, resolve `KB_ROOT` to the directory that contains its
+  managed or authored `index.md`. During setup, inspect the explicitly proposed
+  location without assuming that `index.md` or any KB directory exists. Read
+  the applicable repository and vault `AGENTS.md` files before writing. Do not
+  assume the session started in the vault.
 - Treat authored Markdown and Git as the record. Catalogs, backlinks, graph
   reports, search indexes, embeddings, and percolation candidates are derived
   views.

package/skills/kb/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "KB"
-  short_description: "Query, capture, plan, and maintain Markdown memory"
-  default_prompt: "Use $kb to work with this hraness/kb knowledge base and load only the workflow references needed for the request."
+  short_description: "Set up, query, capture, and maintain Markdown memory"
+  default_prompt: "Use $kb to set up or work with this hraness/kb knowledge base, routing the request before any runtime preparation and loading only the references needed."

package/skills/kb/references/companion-skills.md

@@ -0,0 +1,96 @@
+# Companion skill contracts
+
+A companion skill handles one recurring KB ritual that benefits from a
+discriminating trigger and an explicit operating contract. It composes with
+the public `kb` skill. It does not register code at runtime, execute vault
+metadata, or gain authority by being installed.
+
+## Identity and routing
+
+Give the skill a lowercase action-oriented name and a description that states
+the concrete request that should select it. Keep generic querying, capture,
+planning, percolation, refresh, and validation in the main `kb` skill. Propose
+at most three companions, and prefer zero when the standard router is enough.
+
+## Inputs and preconditions
+
+List the exact inputs that must be supplied or resolved before work starts.
+Distinguish an existing vault from a proposed location. State required local
+commands, repository state, source availability, and authorization without
+installing or probing them as a side effect of skill discovery.
+
+## Surfaces and authority
+
+List each filesystem, repository, application, account, network, and
+integration surface the workflow may read or write. Skill discovery,
+installation, or an existing signed-in session grants no authority. The user's
+scope, the applicable repository instructions, host permissions, and the
+selected tool's own approval boundary remain controlling.
+
+Do not infer that an account operation is read-only from its HTTP method. Do
+not place secrets, cookies, tokens, session data, or ambient personal context
+in durable output.
+
+The shipped customization executor proves filesystem scaffolding only. It
+does not execute an application, account, network, or integration write. A
+companion skill that later needs such an action must treat it as a separate
+runtime request with its own exact proposal, approval, capable tool, and
+inspectable result.
+
+## Approval boundary
+
+Separate read-only inspection from mutation. Present exact targets and writes
+before approval unless the user's request already authorizes them. A denial,
+no response, changed proposal, path expansion, added account, or new external
+surface requires stopping or renewed approval.
+
+## Execution semantics
+
+Define deterministic behavior for the first run and an exact repeat. Require
+path confinement, reject symbolic-link targets, and preserve divergent
+existing content. Name each effect explicitly instead of granting a broad
+filesystem or application capability.
+
+## Durable outputs and provenance
+
+Name the files or records that persist, their authority, and the provenance
+they retain. Markdown and Git remain authoritative KB state. Generated
+catalogs, indexes, embeddings, and graph reports stay rebuildable. Exclude
+credentials, session material, and unrelated account data.
+
+## Verification and KB maintenance
+
+Define the narrow checks that establish the intended result. After material KB
+edits, review percolation candidates and run the appropriate catalog-aware
+check. Parallel lanes use `kb check --no-catalog`; one integrating agent owns a
+managed catalog refresh.
+
+## Composition boundary
+
+Call the installed `kb` command or its public package interfaces only when the
+approved workflow needs them. Do not add a plugin registry, hook loader,
+background process, executable vault metadata, or implicit account bridge. A
+companion skill is an instruction boundary, not runtime extensibility.
+
+## Review checklist
+
+The repository's fake-capability suite is a tested contract example. It checks
+the expected approval and failure transitions, but it does not prove that every
+agent or host integration complies. Review the executing agent's actual tool
+and permission boundaries as well.
+
+- Does the trigger identify one recurring request without attracting generic
+  KB work?
+- Are inputs, preconditions, read surfaces, write surfaces, and exact targets
+  explicit?
+- Can inspection finish without installing, indexing, caching, or mutating?
+- Does approval cover every effect, with renewed approval for any change?
+- Is an exact repeat a no-op, while divergence, path escape, symlinks, partial
+  failure, and unapproved external access stop safely?
+- Do durable outputs preserve useful provenance without secrets or session
+  data?
+- Does the skill compose with the public router without copying its general
+  instructions?
+
+Start from [`companion-skill.template.md`](../templates/companion-skill.template.md)
+only after the proposal's target skill root and name are approved.