@hraness/kb 0.17.1

package/skills/kb/references/percolate.md

@@ -0,0 +1,144 @@
+# Percolate concepts and relationships
+
+Keep the graph authored, local, and reviewable. `kb percolate` proposes
+candidates from deterministic evidence; it never changes a note. Backlinks,
+graph reports, and QMD results are derived views, while Markdown remains the
+authority.
+
+## Locate the vault
+
+- Resolve `<vault>` to the directory containing its authored or managed
+  `index.md` front door.
+- Read the applicable repository and vault instructions before editing.
+- Pass the resolved path to every `--root`.
+- Identify the note or small neighborhood changed by the current task. Prefer a
+  bounded review to a vault-wide cleanup during parallel work.
+
+## Inspect candidates
+
+Run percolation on the changed note when possible:
+
+```sh
+kb percolate notes/example --root "$KB_ROOT" --limit 25 --json
+```
+
+Run it without a note only when reviewing the whole vault:
+
+```sh
+kb percolate --root "$KB_ROOT" --min-support 2 --limit 50 --json
+```
+
+Treat each result as a prompt to open the cited notes and read the relevant
+prose. Candidate kinds may include:
+
+- a recurring tag with no maintained `type: concept` note;
+- notes that share a concept or tag but have no explicit relationship;
+- an exact title or alias mentioned without a contextual link;
+- a self, reciprocal, malformed, broken, or ambiguous authored relationship.
+
+For missing relationships, `support` counts independent shared tags or concept
+neighbors; the evidence array shows the participating notes. The default
+minimum of two therefore requires two shared signals, not merely both endpoints
+of one tag match. Other candidate kinds count their natural unit: supporting
+notes, mention occurrences, or authored hygiene evidence.
+
+For a missing concept, use `suggestedId`. When `collidesWith` is non-null, the
+natural ID is already an ordinary note, so KB chooses an unoccupied
+`*-concept` ID. Read the occupied note before deciding whether to create the
+suggested concept or promote and improve the existing note instead.
+
+Semantic search may help discover evidence, but similarity is never enough to
+author an edge.
+
+## Promote durable concepts
+
+Create a concept only when the idea is likely to be reused and its definition
+can be stated from the source material:
+
+```sh
+kb note create notes/local-first \
+  --root "$KB_ROOT" \
+  --title "Local-first" \
+  --type concept \
+  --tag architecture \
+  --body '# Local-first
+
+A concise reviewed definition grounded in the cited notes.'
+```
+
+Write a concise definition and cite or link the notes that establish it.
+Concepts are ordinary Markdown notes, so they can carry aliases, evidence,
+context, and their own outbound relationships. Do not create a concept merely
+to mirror every tag.
+
+After promotion, rerun percolation on the cited non-concept notes. The new
+concept may support relationships among its neighbors even when a run scoped to
+the concept itself has no candidate:
+
+```sh
+kb percolate notes/write-path --root "$KB_ROOT" --limit 25 --json
+```
+
+## Author typed relationships
+
+Add a relationship from the note that owns the assertion:
+
+```sh
+kb relation add notes/write-path supports notes/durable-agent-memory \
+  --root "$KB_ROOT"
+```
+
+Use a specific lower-kebab-case predicate. A local target is an exact
+vault-root note ID without `.md`. A reviewed cross-vault target is its stable
+qualified identity, such as `kb://hraness/kb/document-id`; never use a checkout
+path as cross-vault identity. Ground the assertion in nearby prose or evidence;
+the frontmatter is an indexable statement, not a substitute for explanation.
+
+List or remove relationships without editing reciprocal notes:
+
+```sh
+kb relation list notes/write-path --root "$KB_ROOT" --json
+kb relation remove notes/write-path supports notes/durable-agent-memory \
+  --root "$KB_ROOT"
+```
+
+Never write inverse edges, generated backlinks, inferred transitive
+relationships, or semantic-search scores into Markdown. Those are derived
+views.
+
+## Query before concluding
+
+Use exact structure to verify that the promoted graph says what the prose says:
+
+```sh
+kb links notes/write-path --root "$KB_ROOT" --direction both --depth 2 --json
+kb relation list notes/write-path --root "$KB_ROOT" --json
+kb graph --root "$KB_ROOT" --json
+```
+
+Prefer the note-scoped commands first. Use the whole-vault graph only when the
+question spans several neighborhoods, and confirm returned IDs against their
+Markdown notes before reporting a conclusion.
+
+## Finish under the vault's catalog mode
+
+When working alone or integrating several lanes:
+
+```sh
+kb refresh --root "$KB_ROOT"
+kb check --root "$KB_ROOT"
+```
+
+When several agents are editing different notes in a managed-catalog vault,
+each lane should validate authored structure and local attachments without
+rewriting the shared catalog:
+
+```sh
+kb check --root "$KB_ROOT" --no-catalog
+```
+
+The integrating agent runs one final managed refresh and normal check. In an
+authored-catalog vault, refresh and check leave the front door untouched, while
+`kb catalog --root "$KB_ROOT"` renders an exhaustive disposable inventory.
+Resolve same-note Git conflicts from the prose and evidence; do not accept one
+side's frontmatter mechanically.

package/skills/kb/references/plan-structure.md

@@ -0,0 +1,105 @@
+# Durable KB plan structure
+
+Use the smallest version that still makes execution and verification
+unambiguous. Omit empty optional sections; do not pad a small change into a
+program document.
+
+## Frontmatter
+
+```yaml
+---
+title: Descriptive outcome
+description: One sentence naming the change and dominant result.
+type: plan
+area: product-or-system
+status: proposed
+repository_scopes:
+  - packages/example
+aliases:
+  - Short plan name
+tags:
+  - migration
+---
+```
+
+`type`, `area`, `status`, and a non-empty description are the stable plan query
+surface. Use a kebab-case `area`. Add `repository_scopes` when the plan owns
+repository work; each entry is one exact canonical repository-relative file or
+directory path, without globs. Omit the field for plans with no code-path
+ownership. Tags are optional facets, not a replacement for prose or links.
+
+## Core sections
+
+```md
+# Descriptive outcome
+
+## Outcome
+
+What will be true when this plan succeeds. Prefer observable behavior over a
+list of files to edit.
+
+## Context
+
+The present state, evidence, and reason the change is needed. Link the notes,
+captures, code, or prior plans that carry necessary context.
+
+## Scope
+
+### In scope
+
+- Work required for the outcome.
+
+### Non-goals
+
+- Adjacent work deliberately excluded.
+
+## Constraints and decisions
+
+- Constraints that shape the implementation.
+- Decisions already made and why.
+- Open questions whose answers can change the plan.
+
+## Plan
+
+1. A dependency-ordered phase with its concrete output.
+2. The next phase and its gate from the prior phase.
+
+## Verification
+
+- Behavior or invariant → exact check, test, observation, or evidence.
+
+## Risks and recovery
+
+- Failure mode → prevention, detection, and rollback or recovery.
+```
+
+## Sections that grow with the work
+
+Add these when execution starts:
+
+```md
+## Execution evidence
+
+- YYYY-MM-DD — Result, command or artifact, and what it proved.
+
+## Review findings
+
+- Finding, disposition, and resulting plan or implementation change.
+
+## Result
+
+What shipped or why work stopped, what was verified, and what intentionally
+remains.
+
+## Durable memory
+
+Link each reusable conclusion to the maintained note, guide, documentation, or
+checked code contract that now owns it. If no conclusion warrants promotion,
+state that no durable promotion was needed and explain why.
+```
+
+Keep evidence compact but reproducible. A test name, checked invariant, or link
+to an artifact is stronger than “validation passed.” Preserve superseded
+decisions when they explain the final shape; mark their disposition instead of
+silently deleting them. Require both Result and Durable memory when the status
+becomes `completed`, `superseded`, or `cancelled`.

package/skills/kb/references/plan.md

@@ -0,0 +1,115 @@
+# Write a durable plan
+
+Keep the plan useful before, during, and after execution. It is the coordination
+record, not a disposable answer or a duplicate task tracker.
+
+## Find the plan's owner
+
+1. Resolve `<vault>` to the directory containing its authored or managed
+   `index.md` front door, then
+   set the shell-local `KB_ROOT` to that path (`KB_ROOT=kb` from a typical
+   repository root, or `KB_ROOT=.` from inside the vault). Read the vault's
+   `AGENTS.md` and the nearest guide under `<vault>/plans/`. Pass that resolved
+   root to every command; do not assume the starting directory is the vault.
+2. When the plan owns a repository path, resolve the repository root as
+   `KB_REPO` and load that path's current memory before a whole-vault search:
+
+```sh
+kb context "<repository-path>" --root "$KB_ROOT" --repo "$KB_REPO"
+```
+
+Use `--kind file` or `--kind directory` when an absent future path cannot be
+classified from the filesystem. Read the inherited guides first, then the
+applicable maintained knowledge, active plans, dated research, reports, and
+separate historical-plan group.
+
+3. Search existing plans before creating one:
+
+```sh
+kb list --root "$KB_ROOT" --where type=plan --sort area --json
+kb search "the intended outcome" --root "$KB_ROOT" --json
+```
+
+If `kb` is not installed, do not let retrieval tooling block the plan: use
+`rg` or the available file search over `<vault>/plans/`, titles, aliases, and relevant
+terms. If the directory is not an initialized hraness/kb vault, follow the
+repository's existing planning convention instead of initializing one without
+being asked. Semantic search writes only a derived local cache; when that cache
+location is not writable, use exact search or point `XDG_CACHE_HOME` at a
+writable cache directory.
+
+4. Update an existing plan when it already owns the outcome. Create a new file
+   only for independently executable work.
+5. Use `<vault>/plans/<descriptive-kebab-name>.md` unless the local guide already groups
+   plans by area. Do not reorganize older plans merely to impose a new tree.
+
+## Write from evidence
+
+Read [the plan structure reference](plan-structure.md), then tailor it to
+the work. Preserve these invariants:
+
+- State one concrete outcome and the current status.
+- Record what is known, what is assumed, and what remains to discover.
+- Separate in-scope work from non-goals.
+- Put constraints and decisions before the steps they shape.
+- Make dependencies and ordering visible.
+- Give each acceptance claim a verification method.
+- Include rollback or recovery when a change can leave durable state behind.
+
+Turn a missing implementation detail into an ordered discovery gate when the
+outcome and authorization are already clear and the decision can be made from
+in-scope evidence. Stop and request direction when the unknown would change the
+intended outcome, expand authority or external coordination, or choose between
+materially different products.
+
+Use small frontmatter. Start with `type: plan`, a descriptive title and
+one-sentence description, a kebab-case `area`, and one of `proposed`,
+`accepted`, `in-progress`, `blocked`, `completed`, `superseded`, or `cancelled`.
+When the plan owns work in a code repository, add `repository_scopes` with the
+few exact canonical repository-relative files or directories it explains. Use
+no globs. A future path is valid; update an active plan deliberately when code
+moves instead of relying on inferred Git renames. Add aliases or tags only when
+they help humans or structured queries.
+
+## Grow the same file during execution
+
+- Change status when reality changes, not in anticipation.
+- Check off completed work without deleting the original intent.
+- Incorporate decisions, review findings, deviations, and command or test
+  evidence where a future reader can understand their consequence.
+- When blocked, name the exact missing condition and the safe work already
+  completed.
+- When a plan becomes `completed`, `superseded`, or `cancelled`, write a
+  non-empty `## Result` and `## Durable memory`. State what shipped or why work
+  stopped in Result. In Durable memory, link each reusable conclusion to the
+  maintained note, guide, documentation, or checked code contract that now owns
+  it. When nothing warrants promotion, say so explicitly and give the reason.
+  Retain the terminal plan as history.
+- Do not create separate progress, review, or completion files for the same
+  plan.
+
+## Connect and verify
+
+Add wikilinks or typed relationships only where the prose and evidence explain
+a useful connection. Review the changed plan for reusable concepts before
+refreshing:
+
+```sh
+kb percolate "<plan-note-id>" --root "$KB_ROOT" --limit 25 --json
+kb refresh --root "$KB_ROOT"
+kb check --root "$KB_ROOT"
+```
+
+Run those commands when the plan lives in an initialized hraness/kb vault. In a
+repository-native planning directory, use that repository's own validation
+instead. Review broken links first, then inspect orphan and mention advisories
+in context. Promote only concepts likely to be reused, and ground every typed
+relationship in the plan's prose. An independently useful plan may legitimately
+remain an orphan in a new or sparse vault. Record that disposition mentally or
+in the task handoff; do not manufacture links or relations merely to improve
+graph counts.
+
+In an authored-catalog vault, refresh leaves the front door unchanged and `kb
+catalog --root "$KB_ROOT"` renders an exhaustive disposable inventory. In a
+managed vault, independent edit lanes use `kb check --root "$KB_ROOT"
+--no-catalog`; the integrating lane performs the single catalog refresh.

package/skills/kb/references/query.md

@@ -0,0 +1,231 @@
+# Query the knowledge base
+
+Use the cheapest precise view first, then broaden. Markdown files remain the
+authority; search scores, metadata rows, and graph results are derived views.
+
+## Locate the vault
+
+- Resolve `<vault>` to the directory containing its managed or authored `index.md`, then
+  set the shell-local `KB_ROOT` to that path (`KB_ROOT=kb` from a typical
+  repository root, or `KB_ROOT=.` from inside the vault).
+- Resolve `<repository>` to the repository root when the question concerns a
+  repository path (`KB_REPO=.` from that root).
+- Read the vault's applicable agent instructions and note conventions.
+- Pass the resolved path to every `--root`; do not scan a repository root merely
+  because that is where the agent session started.
+
+## Choose the retrieval lane
+
+- Repository file or directory: run `kb context` first. Read its inherited
+  guides root to nearest, then inspect its maintained knowledge, active plans,
+  dated research, reports, and separate historical-plan group. Open only useful
+  context hubs or records.
+- Known frontmatter field or tag such as type, status, or area: use `kb list`.
+- Known note title, path, or alias: use `kb links` or `kb backlinks`, which
+  resolve note identities before returning authored relationships.
+- A whole-vault structural question or relationship audit: use `kb graph --json`,
+  then inspect the smallest relevant portion of its canonical output.
+- A phrase, identity, or concept expressed with different vocabulary: use `kb search`, whose default hybrid result preserves exact and QMD evidence separately.
+- Direct provenance for one note or repository path: use `kb history` or
+  `kb history search` without changing authored metadata or links.
+- Recent captures awaiting maintained disposition: use the advisory `kb inbox` view.
+- Broad orientation: read `index.md`, then follow the smallest useful link trail. Use `kb catalog` when an exhaustive disposable inventory is actually needed.
+- A question spanning registered vaults: use `kb portfolio search` with a reviewed registry and explicit authorization. Use `kb portfolio audit` to assess IDs, duplicate authority, links, attachments, and provenance without repairing content.
+
+```sh
+kb context src/parser.ts --root "$KB_ROOT" --repo "$KB_REPO"
+kb list --root "$KB_ROOT" --scope src/parser --where type=plan --json
+kb list --root "$KB_ROOT" --where type=plan --where status=in-progress --sort area --json
+kb list --root "$KB_ROOT" --tag retrieval --sort title --json
+kb backlinks "Plan title or path" --root "$KB_ROOT" --json
+kb links "Plan title or path" --root "$KB_ROOT" --direction both --depth 1 --limit 25 --json
+kb relation list "Plan title or path" --root "$KB_ROOT" --json
+kb graph --root "$KB_ROOT" --json
+kb search "why browser capture uses the current tab" --root "$KB_ROOT" --json
+kb search "accepted ingestion plans" --root "$KB_ROOT" --where type=plan --where status=accepted --tag ingestion --json
+kb search "notes/write-path" --root "$KB_ROOT" --mode exact --no-history --json
+kb history "notes/write-path" --root "$KB_ROOT" --repo "$KB_REPO" --json
+kb history search src/parser.ts --root "$KB_ROOT" --repo "$KB_REPO" --json
+kb inbox --root "$KB_ROOT" --limit 25 --json
+kb portfolio search "durable memory" --registry ./kb-portfolio.json --workspace .. --shared --json
+kb portfolio audit --registry ./kb-portfolio.json --workspace .. --vault hraness/kb --vault 0thernet/jungle --strict --json
+```
+
+Portfolio selection is an access decision. Prefer repeated `--vault owner/id`
+for deliberate private or personal scope. `--shared` selects only public and
+organization entries; `--all` exists only for audit. One operation is bounded
+to 32 vaults and never silently truncates a larger registry-derived selection.
+Open returned notes before concluding. Cross-vault scores are not compared;
+federation uses deterministic reciprocal local rank and stable logical IDs.
+
+When a reviewed consumer policy needs repeatable query shorthand, pass a strict
+v1 rules file. An alias is recognized only as the first token and can add a
+query, mode, metadata filters, tags, or repository scopes without discarding
+caller constraints. Priority ordering is a separate opt-in:
+
+```sh
+kb search "@active-plans parser" --root "$KB_ROOT" \
+  --rules ./search-rules.json --priority --json
+kb portfolio search "@active-plans parser" \
+  --registry ./kb-portfolio.json --workspace .. --shared \
+  --rules ./search-rules.json --priority --json
+```
+
+`--rules` alone enables aliases but retains relevance order. `--priority`
+requires a rules file and requests `priority-then-relevance`; exact identities
+still come first, and matching selected hits carry a rule trace. Keep this
+policy beside the registry or repository that owns it. Rules do not grant
+access, choose authority, author links, or mutate Markdown.
+
+`kb context` prints hub and record summaries, not their bodies. Each record
+states the exact `repository_scopes` declaration that matched, the match depth,
+and whether that declaration currently names a file, directory, or absent
+future or retired path. Current memory and terminal plans stay in separate
+groups. Guides remain
+the normative, always-loaded home for ownership, required commands,
+prohibitions, invariants, and edit gates. Scope hubs are optional pull-based
+rationale, history, examples, evidence, and links; they cannot override a guide
+or become the only home of a load-bearing rule. Use `--kind file` or
+`--kind directory` when `auto` cannot classify a missing target reliably.
+
+Repeated filters use AND semantics. Metadata paths may be dotted. String and
+tag comparisons are case-insensitive; array metadata matches by membership.
+Missing sort values come last, with path as the deterministic tie-breaker.
+`--where` addresses authored frontmatter only; it does not filter derived H1
+titles or file paths. Unquoted `true`, `false`, `null`, and numeric filter
+values are typed. Keep quotes inside the argument to match a string with the
+same spelling, for example `--where 'external_id="9007199254740993"'`.
+`--scope` is an exact, case-sensitive repository-scope filter rather than a
+substring or area match. Use it when the desired authored path declaration is
+known.
+
+## Use hybrid search as discovery
+
+`kb search` first scans current Markdown for identity, phrase, metadata, tag,
+and prose matches. By default it runs that exact lane alongside QMD's local
+full-text and vector rankings, then combines the ranked lists while retaining
+each lane's evidence. Exact title and alias identities stay ahead of broader
+matches. The QMD path avoids query expansion and reranking models by default.
+
+The first hybrid or semantic query downloads QMD's compact local embedding
+model; later queries reuse the local cache. Prewarm explicitly when useful:
+
+```sh
+kb index --root "$KB_ROOT"
+```
+
+Use `--mode exact` for live model-free search, `--mode keyword` for QMD
+full-text retrieval, or `--mode semantic` for its vector lane. Repeated
+`--where`, `--has`, and `--tag` constraints are checked against the live
+Markdown snapshot. QMD has no path-allowlist search in the pinned release, so a
+selective semantic query over-fetches a bounded global window and reports a
+degraded partial lane when that window cannot prove completeness. Treat every
+retrieval rank as a lead, not a fact. Open the returned Markdown, read enough
+surrounding context, and confirm claims against linked sources or capture
+manifests.
+
+Default search also returns bounded explicit graph context around the strongest
+results. Supply `--related <note>` to seed a known neighborhood or `--no-graph`
+when structure does not help. Search does no Git work unless provenance is
+requested. Use `--history --repo <repository>` for optional recent per-note
+provenance or `--require-history --repo <repository>` when the task cannot
+proceed with a partial Git lane. `--no-history` remains an explicit compatibility
+form. Graph neighbors and Git history remain separate from primary
+text rank. They explain and expand candidates without becoming authored facts,
+links, or recency boosts.
+
+`kb history <note>` returns the bounded commit history already associated with
+one resolved note. `kb history search <query-or-path>` searches the bounded Git
+projection directly and retains hashes, subjects, matched paths, co-change
+paths, and incomplete-detail diagnostics. Git co-change is historical evidence,
+not permission to write a scope or relationship.
+
+## Reuse one snapshot in code mode
+
+For several related queries, prefer one SDK session to repeated CLI process
+startup:
+
+```ts
+import { openKnowledgeBase, packUntrustedSearchContext } from "@hraness/kb/sdk";
+
+const kb = await openKnowledgeBase({ root: "kb", repository: "." });
+try {
+  const result = await kb.search({
+    query: "why browser capture uses the current tab",
+    graph: { depth: 1 },
+    history: "auto",
+  });
+  console.log(packUntrustedSearchContext(result).content);
+} finally {
+  await kb.close();
+}
+```
+
+`grep`, `list`, `read`, `links`, `backlinks`, `search`, `history`, and
+`searchHistory` share one confined read-only scan. QMD and Git initialize
+lazily. The session does not watch Markdown or repository changes. Close it
+before a write and open a new session after the final refresh and check.
+
+Pass only ordinary plain objects and arrays from KB or parsed JSON into
+`packUntrustedSearchContext`. A same-realm JavaScript `Proxy` is executable
+code, not inert data; isolate or serialize it before projection.
+
+When independent queries can run concurrently, compose them with
+`defineWorkflow` and `runWorkflow` or import a packaged workflow. The runner
+validates a finite acyclic graph, caps global concurrency, serializes QMD nodes,
+and keeps Git concurrency bounded. Do not bypass those resource groups with
+unbounded `Promise.all` calls. Custom workflows use the staged
+`defineWorkflow<Input>("id").node(...).output(...)` builder so dependency
+results and the final output remain typed.
+
+## Use focused structural views
+
+`kb graph --json` returns the current resolved wikilinks, typed relationships,
+diagnostics, and note-level connection counts without creating a second graph
+store. Use it when a question spans the vault. Prefer `kb relation list`,
+`kb backlinks`, or `kb links` when a known note gives you a narrower starting
+point.
+
+`kb links` is cycle-safe and requires an explicit traversal depth and result
+limit. `kb relation list` separates authored outbound assertions from derived
+inbound relationships while retaining canonical note IDs and source
+provenance. Open the returned Markdown before treating an edge as correct: a
+typed relationship records an authored assertion, not proof.
+
+If a structural question is not covered by a named command, inspect the
+bounded JSON graph in the agent or a short task-local script. Do not create or
+commit a parallel graph database merely to answer one query. A recurring query
+is evidence for a focused, tested command with an explicit output contract.
+
+## Combine meaning with structure
+
+1. For a repository-path question, use `kb context` before broader retrieval.
+2. Use default hybrid search to discover candidate identities when exact
+   structure does not answer the question. Read its lane evidence and partial
+   diagnostics before relying on the order.
+3. Use `kb list` to narrow by authored metadata such as `type`, `status`,
+   `area`, or `tags`.
+4. Use `kb links` at depth 1 to inspect immediate explicit relationships and
+   `kb backlinks` for a focused inbound view. Increase depth only when the
+   first neighborhood is insufficient. Traversal defaults to 50 notes and
+   reports truncation; lower `--limit` for tighter agent context or raise it
+   deliberately when a high-degree hub is genuinely relevant.
+5. Use `kb graph --json` only when the question genuinely spans multiple
+   neighborhoods; keep one-off processing task-local.
+6. Read the authoritative notes and cited captures before synthesizing.
+
+A title match may identify a prerequisite, prior version, or supporting note
+rather than the artifact that owns the current outcome. Confirm status and
+ownership in the candidate Markdown before answering or editing it.
+
+Do not infer an edge from semantic similarity, or a conclusion from a tag. Do
+not write generated backlink sections into notes. If the query exposes stale
+metadata or a broken link, repair the authored Markdown and finish with
+`kb refresh --root "$KB_ROOT"` and `kb check --root "$KB_ROOT"`.
+Close any open SDK session before that repair and reopen it after validation.
+
+An authored `index.md` may declare `kb_catalog: authored`; refresh and check
+then leave it untouched. `kb catalog --root "$KB_ROOT"` renders the exhaustive
+inventory on demand. A managed vault keeps the original generated-catalog
+behavior. Neither mode changes scanning, graph analysis, semantic indexing, or
+attachment validation.