Working in a hraness/wordcell vault

This guide gives coding agents a conservative workflow for reading and maintaining a vault. Markdown is the durable record. Tool output, catalogs, backlinks, traversed paths, semantic indexes, and percolation candidates are views over that record.

Customize before preparing a runtime

When the request is to set up or evolve a Wordcell, design the boundary before discovering or installing the CLI. Inspect the explicitly proposed repository and vault location without mutation. A new location does not need an existing index.md. Interview the user about the recurring questions the Wordcell should answer, then present the exact read and write targets in a proposal.

The approved proposal may choose the standard Markdown layout, no change, or zero to three companion skills for recurring rituals. A companion skill must name its inputs, surfaces, authority, approval boundary, durable outputs, idempotence, failure behavior, and verification. Skill discovery and ambient application or account sessions grant no authority. A changed target, repository, skill, account, or integration requires renewed approval.

After approval, scaffold only the allowlisted paths. Matching existing bytes are a no-op. Stop on divergent content, path escape, a symbolic link, partial failure, or an unapproved external surface. Prepare the runtime only when the approved operation needs it. Installation never authorizes initialization, indexing, QMD state, account access, or vault mutation.

Orient before editing

  1. For a repository-path question, run wordcell context, read the returned AGENTS.md files from root to nearest, and inspect its bounded current-memory groups before opening optional hubs or running a broad search.
  2. Read index.md, then search filenames, frontmatter titles, aliases, and note text before creating a new identity.
  3. Read the notes that already own the concept or source in question.
  4. Use the narrowest view that answers the question:
    • wordcell list for exact frontmatter or tag filters.
    • wordcell links <note>, wordcell backlinks <note>, or wordcell relation list <note> for authored relationships.
    • wordcell history for direct note or repository-path provenance.
    • wordcell search for a fused exact, full-text, and semantic view with visible evidence.
    • wordcell graph for whole-vault diagnostics.

Update an existing note when the identity is unambiguous. Create a new note when the subject has a distinct durable identity, not merely because a search phrase differs.

Load repository context by path

When the question concerns a repository file or directory, start from the repository root:

wordcell context src/index.ts --root kb --repo .

The command lists inherited guides from the repository root toward the nearest scope, verified Wordcell hubs from the nearest scope back toward the root, and authored records whose exact repository_scopes declaration contains the target. It keeps maintained knowledge, active plans, dated research, reports, and terminal plans in separate bounded groups. Every record reports why it matched and whether its declared path exists. It prints summaries, not bodies. Read every returned guide; they are the normative, always-loaded source for ownership, required commands, prohibitions, invariants, and edit gates. Open only the records whose summaries apply, then expand through a bounded command:

wordcell links scopes/src--25a6634263c1 --root kb --depth 1 --limit 25
wordcell backlinks scopes/src--25a6634263c1 --root kb
wordcell list --root kb --scope src --where area=source --json
wordcell search "why source errors retain source ranges" --root kb --scope src --json

Use the exact hub ID returned by wordcell context. Use --kind file or --kind directory when a missing path cannot be classified reliably by --kind auto.

A mapped scope hub carries pull-based rationale, history, examples, evidence, and links. It cannot override its guide or become the only home of a load-bearing edit rule. A guide does not need a hub.

Add repository_scopes to a plan, maintained note, dated research record, or report when that record explains work under specific code paths:

repository_scopes:
  - src/parser
  - tests/parser.test.ts

Use exact canonical repository-relative paths without globs. Directory scopes match descendants, while file scopes match only that file. Future paths are valid and appear as absent until created. Update active or maintained records when code moves; preserve retired paths on terminal plans when they remain useful history.

Path-context research is a dated snapshot, not a generic note with a date. Put it under projects/<domain>/market/ with type: market-research, status: snapshot, and a valid as_of date. A path-context report declares type: report and a valid generated date. Both need repository_scopes; other records remain searchable without appearing in those current-memory groups.

Query before reading broadly

Use typed metadata for exact selection and sorting:

wordcell list --where type=plan --where status=in-progress --sort metadata.updated --order desc
wordcell list --tag retrieval --scope packages/kb --sort inbound --order desc --json

Filters can address nested fields with dotted paths. Repeat --where, --has, or --tag to require every condition. Unquoted true, false, null, and numeric values are typed; retain inner quotes to select a string with the same spelling, as in --where 'external_id="9007199254740993"'. JSON output includes the live metadata, tags, backlinks, and inbound and outbound contextual counts for each result.

Use bounded traversal to understand explicit context around a note:

wordcell links plans/improve-ingestion --direction both --depth 2 --limit 25

Traversal defaults to at most 50 notes and reports when either the node or combined-connection cap truncates a high-degree neighborhood. Lower the limit for agent context discipline; raise it deliberately when the structural question requires a wider view.

Use the whole-vault graph only when the question spans several note neighborhoods:

wordcell graph --root . --json

The report is rebuilt from current Markdown and returns canonical note IDs, resolved wikilinks, typed relationships, and diagnostics. Prefer wordcell links, wordcell backlinks, or wordcell relation list when a known note provides a narrower starting point. Open returned notes and inspect edge provenance before treating a relationship as supported. If a recurring structural question is awkward to answer from the JSON report, add a focused command with a bounded contract rather than a second graph store.

Use hybrid search for broad recall while preserving exact evidence:

wordcell search "capturing a signed-in virtualized page"
wordcell search "capture" --tag ingestion --where status=accepted
wordcell search "notes/write-path" --mode exact
wordcell search "browser profile" --mode keyword

The default combines a live exact scan with QMD's local full-text and compact embedding rankings, then reports each lane's evidence. It skips query expansion and reranking models. The first hybrid or semantic query downloads the embedding model and builds a local cache; subsequent queries incrementally index changed Markdown. Wordcell validates a bounded immutable Markdown projection before QMD indexes it. Shared-database mutations are serialized across local agent processes, same-generation readers can overlap, and a projection change waits for older readers to close. wordcell index can prewarm that cache. --mode exact requires no model.

Reranking is opt-in through --rerank typesafe. It uses jev-1.13.0 and sends the query plus each candidate's identifier, title, vault-relative path, and at most 512 UTF-8 bytes of snippet text to TypeSafe. Enable it only for vaults approved for external processing and provider input-token charges. Use --rerank-limit 25 to bound the window (2–25 candidates); four requests run concurrently under one eight-second deadline with no retries. Exact identities remain first. Results retain their original scores and retrieval evidence.

The CLI reads TYPESAFE_API_KEY, an explicit TYPESAFE_API_KEY_FILE, or the owner-only file ~/.config/wordcell/typesafe-api-key (honoring XDG_CONFIG_HOME). Keep credentials outside the repository. A missing key or provider failure retains baseline ordering and marks the rerank lane unavailable or degraded. Inspect its structured rerank receipt for attempted requests, known usage, elapsed time, and whether usage is complete; an unknown charge is never reported as zero. A successful exit alone does not establish that reranking occurred. Omit --rerank for local-only retrieval.

For a repository's ordinary KB searches, prefer its approved, pinned kb:search script when present. That script declares the vault and processing choice. Read returned notes before acting; model probabilities are ranking signals, not proof of truth. Explicit priority rules still run last.

Graph neighbors and Git provenance are returned separately from the primary rank. Use --related <note> to seed a bounded explicit neighborhood, --no-graph when it is unnecessary, and --history when recent note provenance helps. Omitted history performs no Git work. Use --require-history when a result without Git provenance is not usable; the command then fails instead of returning an unavailable or incomplete Git lane. Automatic history keeps normal commits usable when one commit exceeds its changed-path detail limit. The affected note retains that commit's identity and vault-local association, while diagnostics and packed context identify the incomplete co-change evidence. These views explain a result; they do not create links or establish that a claim is correct.

Ask Git directly when text retrieval is unnecessary:

wordcell history notes/write-path --root kb --repo . --json
wordcell history search src/parser.ts --root kb --repo . --json

The second command searches bounded commit subjects, note paths, and co-change paths. Co-change is evidence of historical association, not causation, and it never writes repository scopes or graph edges.

For several related operations, open one read-only SDK session and reuse its single vault scan:

import { openKnowledgeBase } from "@hraness/wordcell/sdk";

const kb = await openKnowledgeBase({ root: "kb", repository: "." });
try {
  const plans = kb.list({
    filters: [{ kind: "equals", path: "type", value: "plan" }],
  });
  const context = await kb.search({
    query: "current ingestion plan",
    history: "auto",
  });
  const source = kb.read(context.results[0]?.id ?? plans[0]?.id ?? "index");
  console.log(source.content);
} finally {
  await kb.close();
}

The session does not watch the filesystem. Close and reopen it after any note write, authoring command, capture, refresh, or Git update that should appear in later results. Use the bounded defineWorkflow and runWorkflow API when independent retrieval branches can run concurrently; QMD work remains serialized by default. Import decisionContextWorkflow, explainChangeWorkflow, or planRadarWorkflow from @hraness/wordcell/workflows when one of those common DAGs matches the task.

decisionContextWorkflow returns a bounded untrusted context envelope. explainChangeWorkflow and planRadarWorkflow return raw Wordcell and Git result objects for application-side inspection; their source-derived strings remain untrusted data. Never execute those fields or insert them into an instruction channel. Select and project the needed fields through packUntrustedSearchContext or @hraness/wordcell/untrusted-content before an agent handoff.

Use history: "required" when provenance is mandatory, or history: { policy: "required", noteLimit: 5 } when the same requirement needs custom bounds. Custom workflows use a staged builder so every node sees a typed Wordcell session and only its declared dependency results:

import { openKnowledgeBase } from "@hraness/wordcell/sdk";
import { defineWorkflow, runWorkflow } from "@hraness/wordcell/workflow";

type Input = { readonly query: string };

const kb = await openKnowledgeBase({ root: "kb", repository: "." });
const research = defineWorkflow<Input>("research")
  .node({
    id: "search",
    resource: "qmd",
    run: ({ input, kb }) => kb.search({ query: input.query }),
  })
  .node({
    id: "pack",
    needs: ["search"],
    run: ({ result }) => result("search").results.map(({ path }) => path),
  })
  .output("pack");

const execution = await runWorkflow(research, {
  kb,
  input: { query: "current ingestion plan" },
});
console.log(execution.output);
await kb.close();

Evaluate retrieval changes on a frozen corpus

Use a versioned evaluation manifest when a ranking, filter, graph, context, or history change needs empirical evidence. Author query prose, structured lane inputs, and 0–3 relevance judgments before inspecting the candidate run. Keep development and test queries distinct.

wordcell evaluate kb/evaluations/repository-memory-v1.json \
  --root kb --repo . --split test \
  --model-file /path/to/the/recommended-model.gguf \
  --cache-state warm --json > kb/reports/repository-memory-v1.json

The command verifies the manifest's exact Git commit and vault tree and rejects dirty vault content before opening retrieval. It runs the selected built-in exact, keyword, semantic, hybrid, metadata, graph, path-context, and Git adapters through one bounded snapshot. Use repeated --retriever values for an ablation. Semantic and hybrid runs verify the file against the pinned model SHA-256, give those exact bytes to QMD, and verify them again after retrieval. The report retains the stable model URI, revision, and digest without storing the local path.

Read per-query rankings, unavailable or degraded lanes, timings, raw resource counters, per-class metrics, and paired intervals together. A small frozen corpus is a regression and harness proof. It is not evidence about another vault, machine, scale, cache state, or end-to-end agent outcome.

Preserve authority boundaries

Do not silently rewrite a capture to match a later conclusion. Link the source to the maintained interpretation instead.

Grow durable plans

Before creating a plan, use wordcell list --where type=plan and search the vault for an existing artifact that owns the outcome. Prefer extending that file to creating a parallel progress log.

A durable plan records an observable outcome, context, scope and non-goals, constraints, decisions, dependency-ordered work, verification, and recovery. Keep its frontmatter easy to query, including type: plan, a description, an area, applicable repository_scopes, and one status from proposed, accepted, in-progress, blocked, completed, superseded, or cancelled. Add dated findings, decisions, review evidence, and the final result to the same file as the work develops. Before setting a terminal status, fill ## Result and ## Durable memory: link each reusable conclusion to the maintained note, guide, documentation, or checked code contract that now owns it, or state that no durable promotion was needed.

The packaged wordcell Agent Skill routes plan requests to the complete authoring workflow. It treats a plan as a growing implementation record, not a disposable checklist or a directory of satellite status documents.

Use vault-root wikilinks without .md, for example:

The capture strategy follows [[notes/bounded-acquisition|bounded acquisition]] so incomplete threads remain visible as incomplete.

Use ordinary Markdown links for external URLs. Add an internal link where the relationship helps a reader understand the sentence. Do not add bare reciprocal links, manufactured Related lists, or links whose only purpose is to improve graph counts.

Backlinks are derived from explicit wikilinks. Never paste generated backlink sections into notes. Catalog links in index.md are navigation and do not establish contextual relationships. Mention candidates are prompts for review, not instructions to edit.

Promote a reusable idea into an ordinary concept note:

wordcell note create notes/local-first --title "Local-first" --type concept --tag architecture

Author a typed relationship from the note that owns the assertion:

wordcell relation add notes/write-path supports notes/durable-agent-memory

Predicates use lower-kebab-case and targets use exact vault-root IDs without .md. Recommended predicates for common Wordcell claims are synthesizes, evidenced-by, informed-by, supersedes, and contradicts. The list is advisory; a vault may use another canonical predicate whose meaning its prose establishes. Explain the assertion in prose or evidence. Do not author inverse, reciprocal, transitive, or similarity-derived edges. External or unclassified material does not gain a relationship automatically.

Capture a source

Check the local environment and the installed adapters before relying on optional capabilities:

wordcell doctor
wordcell adapters

Inspect an unfamiliar source before writing it:

wordcell inspect https://example.com/article
wordcell inspect https://example.com/article --json

Capture a URL or the page already open in the signed-in browser:

wordcell clip https://example.com/article --output articles
wordcell clip current --browser-live --output articles

Review the Markdown and capture.json together. Preserve the recorded status, warnings, counts, acquisition attempts, and artifact outcomes. partial is a useful result, not a defect to hide. Do not infer thread completeness from visible prose alone.

The capture command reads content and writes a local bundle. It does not post, like, follow, send, delete, or submit on the source service.

Capture a local or public remote PDF through its separate ingestion path:

wordcell pdf "/absolute/path/to/document.pdf" --output articles
wordcell pdf "https://example.com/document.pdf" --output articles

Review native headings, OCR-derived text, and retained source images together. The bundle keeps source.pdf byte-for-byte and never records its original absolute path. A text-bearing screenshot still needs its source-image reference; a useful native-text result does not hide an unprocessed image or page.

Use the source inbox to find recent captures that have not yet been linked from maintained knowledge:

wordcell inbox --root kb --limit 25 --json

The inbox is advisory. A source can remain an intentional leaf; review it and record a disposition only when it changes maintained understanding.

Finish every change

After adding, renaming, moving, or materially revising notes:

wordcell percolate "<changed-note-id>" --root . --limit 25 --json
wordcell refresh --root .
wordcell graph --root .
wordcell check --root .

Any code-mode session opened before those writes is now stale. Close it before the write and open a new session after the final check.

Open the evidence cited by each percolation candidate. Promote only concepts likely to be reused and relationships established by the source material. In Percolation Result V2, a missing relationship is an unordered endpoint pair with a required predicate. It does not choose a source, direction, or related-to fallback. Read both endpoints and author the directed assertion only when their prose and evidence establish it. Parse historical unversioned V1 results explicitly; do not silently transform their suggested predicate into a V2 claim. Review broken and ambiguous links, typed relationships, local attachments, and repository-scope advisories first. Then inspect orphans and high-confidence title or alias mentions in context. Add a suggested link only when it improves the prose. Finish with a clean wordcell check. In a managed vault, inspect the catalog diff; in an authored vault, refresh leaves the front door unchanged and wordcell catalog --root . provides an exhaustive disposable inventory.

When multiple agents are editing different notes, each lane runs:

wordcell check --root . --no-catalog

The integrating agent runs one final refresh and normal check after the lanes join. Managed vaults serialize their one catalog write. Authored vaults declare kb_catalog: authored in index.md and avoid that write entirely. No shared graph database or generated fact log exists to contend on.

If the change adds, removes, renames, or moves a scope hub, changes its type or scope, or edits an kb:context marker, also run:

wordcell agents identity packages/parser --json
wordcell agents check --root kb --repo .

Use wordcell agents identity when creating or moving a mapping; it derives the canonical path and marker without writing either file. The gate checks canonical content-derived IDs, exact repository-relative scopes, collisions, real confined scope directories and guide files, guide shape, and reciprocal markers. A scope move changes identity, so rename the hub and marker together. Unmapped AGENTS.md files are valid.

Use the audit when reviewing instruction size or inheritance:

wordcell agents audit --root kb --repo .
wordcell agents audit --root kb --repo . --json

The audit adds deterministic per-guide and per-section measurements, inherited-chain totals, long-bullet advisories, and exact duplicate-rule advisories. Inspect them as refactoring leads. Length is not correctness, and a rule that must be known before editing stays in AGENTS.md even when it is long. Guide discovery skips common generated and vendor directories and never follows symbolic-link directories.

Source: docs/agent-workflow.md on GitHub