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 wordcell 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 wordcell list.
• Known note title, path, or alias: use wordcell links or wordcell backlinks, which resolve note identities before returning authored relationships.
• A whole-vault structural question or relationship audit: use wordcell graph --json, then inspect the smallest relevant portion of its canonical output.
• A phrase, identity, or concept expressed with different vocabulary: use wordcell search, whose default hybrid result preserves exact and QMD evidence separately.
• Direct provenance for one note or repository path: use wordcell history or wordcell history search without changing authored metadata or links.
• Recent captures awaiting maintained disposition: use the advisory wordcell inbox view.
• Broad orientation: read index.md, then follow the smallest useful link trail. Use wordcell catalog when an exhaustive disposable inventory is actually needed.

wordcell context src/parser.ts --root "$KB_ROOT" --repo "$KB_REPO"
wordcell list --root "$KB_ROOT" --scope src/parser --where type=plan --json
wordcell list --root "$KB_ROOT" --where type=plan --where status=in-progress --sort area --json
wordcell list --root "$KB_ROOT" --tag retrieval --sort title --json
wordcell backlinks "Plan title or path" --root "$KB_ROOT" --json
wordcell links "Plan title or path" --root "$KB_ROOT" --direction both --depth 1 --limit 25 --json
wordcell relation list "Plan title or path" --root "$KB_ROOT" --json
wordcell graph --root "$KB_ROOT" --json
wordcell search "why browser capture uses the current tab" --root "$KB_ROOT" --json
wordcell search "accepted ingestion plans" --root "$KB_ROOT" --where type=plan --where status=accepted --tag ingestion --json
wordcell search "notes/write-path" --root "$KB_ROOT" --mode exact --no-history --json
wordcell history "notes/write-path" --root "$KB_ROOT" --repo "$KB_REPO" --json
wordcell history search src/parser.ts --root "$KB_ROOT" --repo "$KB_REPO" --json
wordcell inbox --root "$KB_ROOT" --limit 25 --json

wordcell 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

wordcell 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:

wordcell 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.

wordcell history <note> returns the bounded commit history already associated with one resolved note. wordcell 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:

import { openKnowledgeBase, packSearchContext } from "@hraness/wordcell/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(packSearchContext(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.

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

wordcell 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 wordcell relation list, wordcell backlinks, or wordcell links when a known note gives you a narrower starting point.

wordcell links is cycle-safe and requires an explicit traversal depth and result limit. wordcell 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 wordcell 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 wordcell list to narrow by authored metadata such as type, status, area, or tags.
4. Use wordcell links at depth 1 to inspect immediate explicit relationships and wordcell 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 wordcell 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 wordcell refresh --root "$KB_ROOT" and wordcell 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. wordcell 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.