@hraness/wordcell 0.20.0-bootstrap.1

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

@@ -0,0 +1,96 @@
+# Companion skill contracts
+
+A companion skill handles one recurring Wordcell ritual that benefits from a
+discriminating trigger and an explicit operating contract. It composes with
+the public `wordcell` 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 `wordcell` 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 Wordcell state. Generated
+catalogs, indexes, embeddings, and graph reports stay rebuildable. Exclude
+credentials, session material, and unrelated account data.
+
+## Verification and Wordcell maintenance
+
+Define the narrow checks that establish the intended result. After material Wordcell
+edits, review percolation candidates and run the appropriate catalog-aware
+check. Parallel lanes use `wordcell check --no-catalog`; one integrating agent owns a
+managed catalog refresh.
+
+## Composition boundary
+
+Call the installed `wordcell` 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
+  Wordcell 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.

package/skills/wordcell/references/customize.md

@@ -0,0 +1,123 @@
+# Customize a Wordcell setup
+
+Design the smallest Wordcell arrangement that answers the user's recurring memory
+questions. Begin with an interview and read-only inspection. Do not install a
+runtime, initialize a vault, build an index, access an account, or write a file
+before the proposal has the user's approval.
+
+## Establish the boundary
+
+Identify the repositories, vaults, people, agents, and time horizons in scope.
+Ask what the Wordcell must help a future agent recover, which information must remain
+outside it, and which existing instructions govern the target paths. Treat the
+user's explicit request as authorization for the named work. Do not extend it
+to another path, repository, account, application, or integration.
+
+For a new vault, ask for or propose an exact location. Do not require an
+existing `index.md`. For an existing vault, resolve its front door and read the
+applicable `AGENTS.md` files before proposing changes.
+
+## Inspect without mutation
+
+Inspect only the surfaces needed to understand the current setup. Typical
+evidence includes directory structure, existing Markdown conventions, scoped
+agent guides, active plans, source records, repository paths, and available
+local commands. Keep filesystem, application, account, network, and
+integration access within the user's stated scope and the host's actual
+permissions.
+
+Do not run `wordcell doctor`, `wordcell init`, `wordcell index`, QMD, hybrid or semantic search,
+an installer, or a command that may create a cache during this phase. Do not
+create a hidden profile such as `.context/me.md` or infer personal context from
+an ambient account.
+
+## Interview in small batches
+
+Ask only questions whose answers change the proposed structure. Prefer a small
+batch about one decision at a time:
+
+- Which recurring questions should the Wordcell answer?
+- Which sources, maintained explanations, plans, and repository rules already
+  exist?
+- Which writes should happen automatically, require review, or never happen?
+- Which recurring action is common enough to justify a companion skill?
+
+Summarize each resolved decision before moving to the next uncertain one. A
+short interview may conclude that the standard profile or no change is best.
+
+## Propose the smallest useful change
+
+Describe the exact files and surfaces before editing. Use this table:
+
+| Surface | Exact target | Read | Write | Purpose | Approval |
+| --- | --- | --- | --- | --- | --- |
+| Vault | `<path>` | `<bounded inputs>` | `<files or none>` | `<memory question>` | `<approved or pending>` |
+
+Propose zero to three companion skills. Each proposed skill must own a distinct
+recurring request that the main `wordcell` router cannot express clearly enough. Do
+not add a skill only to restate repository policy or wrap one command.
+
+State the verification, idempotence, retry, and failure behavior for every
+write. Keep Markdown and Git authoritative. Treat indexes, embeddings,
+catalogs, graph reports, and caches as replaceable views.
+
+## Obtain approval
+
+Present the proposal and wait when its writes are not already authorized by
+the user's explicit request. Approval applies to the exact targets and
+operations shown. A changed path, expanded repository, additional skill,
+account surface, network action, or broader write requires renewed approval.
+
+Silence, a denial, or an ambiguous response is not approval. Inspection does
+not grant write authority. Discovery of a command, application, account, or
+integration does not authorize its use.
+
+## Scaffold within the approved boundary
+
+Create only approved paths. For a companion skill, read [Companion skill
+contracts](companion-skills.md) and copy
+[`companion-skill.template.md`](../templates/companion-skill.template.md) to
+`<explicit-skill-root>/<name>/SKILL.md`. Never edit the template inside an
+installed package or `node_modules`.
+
+If approved execution needs the Wordcell CLI, prepare the runtime now using the main
+skill's pinned installation instructions. Installation does not authorize
+`wordcell init`, indexing, semantic search, or vault writes. Run only the approved
+commands and exact allowlisted writes.
+
+The scaffold executor writes filesystem targets only. It never performs an
+application, account, network, or integration write. A companion skill may
+describe one of those later actions, but its execution is a separate runtime
+request with its own exact proposal, approval, tool boundary, and result.
+
+On a repeated request, compare the desired bytes with the approved targets.
+Treat an exact match as a no-op. Stop on divergent existing content, a symlink,
+a path that escapes the approved root, an unapproved external surface, or a
+partial write. Report the retained state instead of overwriting, silently
+retrying, or widening the boundary.
+
+## Start with real material
+
+Use a small amount of material that exercises the agreed structure: one saved
+source, one maintained explanation, one plan, or one repository-context
+mapping. Do not manufacture empty directories, placeholder notes, a complete
+ontology, or speculative metadata merely to make the vault look populated.
+
+## Verify and hand off
+
+Verify every approved file and record the exact paths changed. Run the
+narrowest applicable Wordcell checks only when they were approved and the runtime is
+available. State what remains unconfigured, which views are rebuildable, and
+which action would require separate authority.
+
+Keep durable output free of credentials, session material, account exports,
+and hidden ambient context. Record source provenance and the boundary of any
+incomplete acquisition.
+
+## Evolve an existing setup
+
+Re-run the boundary, inspection, interview, proposal, and approval steps when
+the vault's recurring questions change. Prefer a focused convention or skill
+revision to a migration. Preserve authored Markdown and Git history, and do not
+mass-rewrite metadata to fit a new taxonomy unless a measured retrieval or
+maintenance problem justifies that work.

package/skills/wordcell/references/pdf-review.md

@@ -0,0 +1,51 @@
+# Review PDF image-derived text
+
+Read this guide when a PDF contains screenshots, scans, or mixed text and
+visual media.
+
+## Keep the source inspectable
+
+- Retain every extracted image in `assets/`.
+- Embed primarily visual images.
+- Keep a source-image link beside OCR-derived or manually corrected text.
+- Preserve page number, image index, bounding box, extraction method, and
+  confidence in `capture.json`.
+- Never replace a mixed image with text alone. Screenshots can contain a
+  message, chart, photograph, code sample, or UI state at the same time.
+- The renderer embeds the source image and adds its metadata and “Text visible
+  in…” heading. Annotation `markdown` should contain only the transcription.
+
+## Structure conversations
+
+When the surface is recognizable, use available metadata rather than flattening
+the screenshot into one paragraph:
+
+```markdown
+> bg @ Oct 15, 2024 at 4:26 PM
+> Substrate did look very well designed and ambitious from the outside...
+```
+
+Use the platform's visible display name. Include channel, thread, or reply
+context only when the screenshot shows it. Split a multi-message screenshot
+into distinct message blocks, including each visible message author and
+timestamp in that message's Markdown header. Annotation metadata describes
+shared or whole-image context: use its scalar `author` or `timestamp` only when
+one value accurately characterizes the image, and use `participants` for
+multiple visible authors. The generated image embed is the shared source-image
+reference.
+
+Do not invent missing authors, dates, channels, or thread relationships. Mark
+uncertain OCR as `[unclear]`; do not silently turn a plausible guess into source
+text.
+
+## Distinguish image roles
+
+- `text`: a scan or crop is adequately represented by its prose, code, table,
+  or labels, although the source asset is still retained.
+- `visual`: the image remains meaningful without recognized text.
+- `mixed`: both recognized text and non-text visual or spatial context matter.
+  Use this for most message and application screenshots because avatars,
+  grouping, thread layout, reactions, and UI state can remain evidentiary.
+
+When classification is uncertain, choose `mixed`, keep the image visible, and
+preserve the OCR warning.

package/skills/wordcell/references/percolate.md

@@ -0,0 +1,176 @@
+# Percolate concepts and relationships
+
+Keep the graph authored, local, and reviewable. `wordcell 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
+wordcell percolate notes/example --root "$KB_ROOT" --limit 25 --json
+```
+
+Run it without a note only when reviewing the whole vault:
+
+```sh
+wordcell 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.
+
+Percolation Result V2 reports a missing relationship as an unordered pair of
+endpoints with `predicate: { "kind": "required" }`. The output does not choose
+which note owns the assertion, its direction, or its predicate. In particular,
+it never inserts `related-to` as a fallback. Read both notes and their evidence,
+then choose a source, target, and predicate only when the prose establishes that
+claim. Historical unversioned V1 results may contain a suggested predicate;
+parse them through the explicit V1 compatibility surface and do not treat that
+suggestion as an authored fact or silently upgrade it to V2. V1 remains
+available through the 0.19 release line and is not removed before 0.20.0.
+
+For a missing concept, use `suggestedId`. When `collidesWith` is non-null, the
+natural ID is already an ordinary note, so Wordcell 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
+wordcell 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
+wordcell percolate notes/write-path --root "$KB_ROOT" --limit 25 --json
+```
+
+## Author typed relationships
+
+Add a relationship from the note that owns the assertion:
+
+```sh
+wordcell relation add notes/write-path supports notes/durable-agent-memory \
+  --root "$KB_ROOT"
+```
+
+Use a specific lower-kebab-case predicate. Recommended predicates for common
+Wordcell evidence and maintenance claims are:
+
+- `synthesizes` when the source combines and maintains conclusions from the
+  target material;
+- `evidenced-by` when the target directly supports a claim in the source;
+- `informed-by` when the target influenced the source without serving as its
+  direct evidence;
+- `supersedes` when the source deliberately replaces the target as the current
+  account;
+- `contradicts` when the source records a supported incompatible claim.
+
+This vocabulary is advisory. A vault may use any canonical custom predicate
+whose meaning its prose establishes. Do not assign a recommended predicate by
+directory, note type, shared tags, chronology, or similarity alone. 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
+wordcell relation list notes/write-path --root "$KB_ROOT" --json
+wordcell relation remove notes/write-path supports notes/durable-agent-memory \
+  --root "$KB_ROOT"
+```
+
+Never write inverse edges, generated backlinks, inferred transitive
+relationships, reciprocal edges, similarity-derived relationships, or
+semantic-search scores into Markdown. External or unclassified material is
+outside this vocabulary evaluation and remains unresolved. Those are derived
+views or review work.
+
+The interview-first setup and relationship-review pattern builds on Frank
+Chen's public notes about [designing a personal knowledge base with an
+agent](https://gist.github.com/fxchen/773397095d7a6bffda621e4237da0da9)
+and [extending it with skills](https://gist.github.com/fxchen/09cb410b22c9c5256d80243ee925b57e).
+
+## Query before concluding
+
+Use exact structure to verify that the promoted graph says what the prose says:
+
+```sh
+wordcell links notes/write-path --root "$KB_ROOT" --direction both --depth 2 --json
+wordcell relation list notes/write-path --root "$KB_ROOT" --json
+wordcell 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
+wordcell refresh --root "$KB_ROOT"
+wordcell 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
+wordcell 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
+`wordcell 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/wordcell/references/plan-structure.md

@@ -0,0 +1,105 @@
+# Durable Wordcell 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/wordcell/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
+wordcell 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
+wordcell list --root "$KB_ROOT" --where type=plan --sort area --json
+wordcell search "the intended outcome" --root "$KB_ROOT" --json
+```
+
+If `wordcell` 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/wordcell 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
+wordcell percolate "<plan-note-id>" --root "$KB_ROOT" --limit 25 --json
+wordcell refresh --root "$KB_ROOT"
+wordcell check --root "$KB_ROOT"
+```
+
+Run those commands when the plan lives in an initialized hraness/wordcell 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 `wordcell check --root "$KB_ROOT"
+--no-catalog`; the integrating lane performs the single catalog refresh.