From 3b6b82393524fb879b4cc64140f104ad8ad0cfa8 Mon Sep 17 00:00:00 2001 From: 0thernet <894119+0thernet@users.noreply.github.com> Date: Mon, 28 Sep 2026 03:19:44 -0400 Subject: [PATCH] Update vendored KB skills and guides to Wordcell commands The vendored .agents/skills/*-kb bundles and KB guides still used the retired `kb` CLI name and `@hraness/kb` package references. Wordcell is the same project renamed; update live command examples and prose to the `wordcell` binary and `@hraness/wordcell` package so the vendored instructions match the pinned tooling. KB_ROOT, kb_catalog frontmatter, `kb:` package script names, `kb:context` markers, vault `kb/` paths, and `*-kb` skill identities are unchanged. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .agents/skills/percolate-kb/AGENTS.md | 4 +- .agents/skills/percolate-kb/SKILL.md | 32 +++---- .agents/skills/plan-kb/AGENTS.md | 2 +- .agents/skills/plan-kb/SKILL.md | 24 +++--- .agents/skills/query-kb/SKILL.md | 84 +++++++++---------- .agents/skills/refresh-kb/AGENTS.md | 6 +- .agents/skills/refresh-kb/SKILL.md | 22 ++--- .agents/skills/save-pdf-kb/AGENTS.md | 2 +- .agents/skills/save-pdf-kb/SKILL.md | 20 ++--- .agents/skills/save-url-kb/AGENTS.md | 4 +- .agents/skills/save-url-kb/SKILL.md | 56 ++++++------- .../save-url-kb/references/authentication.md | 26 +++--- .../save-url-kb/references/platforms.md | 2 +- kb/AGENTS.md | 6 +- kb/scopes/AGENTS.md | 4 +- 15 files changed, 147 insertions(+), 147 deletions(-) diff --git a/.agents/skills/percolate-kb/AGENTS.md b/.agents/skills/percolate-kb/AGENTS.md index 37b638f..3a7c914 100644 --- a/.agents/skills/percolate-kb/AGENTS.md +++ b/.agents/skills/percolate-kb/AGENTS.md @@ -1,11 +1,11 @@ # Contents -- `SKILL.md` – reusable concept-and-relationship percolation workflow for a hraness/kb vault. +- `SKILL.md` – reusable concept-and-relationship percolation workflow for a hraness/wordcell vault. - `agents/openai.yaml` – user-facing skill metadata and invocation prompt. # Guidelines -- Keep this bundle self-contained under the public hraness/kb identity and free of repository-specific policy, paths, names, or provenance. +- Keep this bundle self-contained under the public hraness/wordcell identity and free of repository-specific policy, paths, names, or provenance. - Keep percolation read-only until an agent reviews the cited Markdown and chooses a specific concept or relationship edit. - Treat concepts as ordinary notes and outbound relationships as source-owned assertions; never direct agents to write reciprocal, inferred, or similarity-derived edges. - During parallel work in a managed-catalog vault, defer the shared catalog refresh to the integrating agent and use the catalog-skipping check in each edit lane. In authored mode, refresh and check must leave the front door untouched. diff --git a/.agents/skills/percolate-kb/SKILL.md b/.agents/skills/percolate-kb/SKILL.md index 77fd3d9..3847d78 100644 --- a/.agents/skills/percolate-kb/SKILL.md +++ b/.agents/skills/percolate-kb/SKILL.md @@ -1,11 +1,11 @@ --- name: percolate-kb -description: Review a hraness/kb Markdown vault for recurring ideas and missing structural connections, then promote evidence-backed concepts and typed relationships with the KB CLI. Use after materially adding or revising notes, when organizing an accumulated vault, or when an agent needs to turn repeated tags and prose references into an explicit queryable knowledge graph. +description: Review a hraness/wordcell Markdown vault for recurring ideas and missing structural connections, then promote evidence-backed concepts and typed relationships with the Wordcell CLI. Use after materially adding or revising notes, when organizing an accumulated vault, or when an agent needs to turn repeated tags and prose references into an explicit queryable knowledge graph. --- # Percolate concepts and relationships -Keep the graph authored, local, and reviewable. `kb percolate` proposes +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. @@ -24,13 +24,13 @@ authority. Run percolation on the changed note when possible: ```sh -kb percolate notes/example --root "$KB_ROOT" --limit 25 --json +wordcell 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 +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 @@ -61,7 +61,7 @@ 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 \ +wordcell note create notes/local-first \ --root "$KB_ROOT" \ --title "Local-first" \ --type concept \ @@ -81,7 +81,7 @@ 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 +wordcell percolate notes/write-path --root "$KB_ROOT" --limit 25 --json ``` ## Author typed relationships @@ -89,7 +89,7 @@ kb percolate notes/write-path --root "$KB_ROOT" --limit 25 --json Add a relationship from the note that owns the assertion: ```sh -kb relation add notes/write-path supports notes/durable-agent-memory \ +wordcell relation add notes/write-path supports notes/durable-agent-memory \ --root "$KB_ROOT" ``` @@ -100,8 +100,8 @@ 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 \ +wordcell relation list notes/write-path --root "$KB_ROOT" --json +wordcell relation remove notes/write-path supports notes/durable-agent-memory \ --root "$KB_ROOT" ``` @@ -114,9 +114,9 @@ views. 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 +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 @@ -128,8 +128,8 @@ Markdown notes before reporting a conclusion. When working alone or integrating several lanes: ```sh -kb refresh --root "$KB_ROOT" -kb check --root "$KB_ROOT" +wordcell refresh --root "$KB_ROOT" +wordcell check --root "$KB_ROOT" ``` When several agents are editing different notes in a managed-catalog vault, @@ -137,11 +137,11 @@ each lane should validate authored structure and local attachments without rewriting the shared catalog: ```sh -kb check --root "$KB_ROOT" --no-catalog +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 -`kb catalog --root "$KB_ROOT"` renders an exhaustive disposable inventory. +`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. diff --git a/.agents/skills/plan-kb/AGENTS.md b/.agents/skills/plan-kb/AGENTS.md index 20e4d4e..9934bea 100644 --- a/.agents/skills/plan-kb/AGENTS.md +++ b/.agents/skills/plan-kb/AGENTS.md @@ -9,4 +9,4 @@ - Keep the skill portable across repositories and independent of a specific product taxonomy. - Require outcome, status, constraints, ordered work, and verification while allowing small plans to stay small. - Evolve one plan in place; do not prescribe satellite progress or review files. -- Keep examples compatible with Obsidian, ordinary Markdown, and the installed `kb` command. +- Keep examples compatible with Obsidian, ordinary Markdown, and the installed `wordcell` command. diff --git a/.agents/skills/plan-kb/SKILL.md b/.agents/skills/plan-kb/SKILL.md index d2123d8..116f12b 100644 --- a/.agents/skills/plan-kb/SKILL.md +++ b/.agents/skills/plan-kb/SKILL.md @@ -1,6 +1,6 @@ --- name: plan-kb -description: Create or evolve a durable Markdown plan inside a hraness/kb vault. Use when a user asks for an implementation plan, proposal, RFC, migration plan, execution audit, phased checklist, or an update to an existing plan's decisions, progress, review findings, verification evidence, or final result. +description: Create or evolve a durable Markdown plan inside a hraness/wordcell vault. Use when a user asks for an implementation plan, proposal, RFC, migration plan, execution audit, phased checklist, or an update to an existing plan's decisions, progress, review findings, verification evidence, or final result. --- # Write a durable plan @@ -20,7 +20,7 @@ record, not a disposable answer or a duplicate task tracker. `KB_REPO` and load that path's current memory before a whole-vault search: ```sh -kb context "" --root "$KB_ROOT" --repo "$KB_REPO" +wordcell context "" --root "$KB_ROOT" --repo "$KB_REPO" ``` Use `--kind file` or `--kind directory` when an absent future path cannot be @@ -31,13 +31,13 @@ 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 +wordcell list --root "$KB_ROOT" --where type=plan --sort area --json +wordcell search "the intended outcome" --root "$KB_ROOT" --json ``` -If `kb` is not installed, do not let retrieval tooling block the plan: use +If `wordcell` is not installed, do not let retrieval tooling block the plan: use `rg` or the available file search over `/plans/`, titles, aliases, and relevant -terms. If the directory is not an initialized hraness/kb vault, follow the +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 @@ -100,12 +100,12 @@ a useful connection. Review the changed plan for reusable concepts before refreshing: ```sh -kb percolate "" --root "$KB_ROOT" --limit 25 --json -kb refresh --root "$KB_ROOT" -kb check --root "$KB_ROOT" +wordcell percolate "" --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/kb vault. In a +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 @@ -114,7 +114,7 @@ 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 +In an authored-catalog vault, refresh leaves the front door unchanged and `wordcell catalog --root "$KB_ROOT"` renders an exhaustive disposable inventory. In a -managed vault, independent edit lanes use `kb check --root "$KB_ROOT" +managed vault, independent edit lanes use `wordcell check --root "$KB_ROOT" --no-catalog`; the integrating lane performs the single catalog refresh. diff --git a/.agents/skills/query-kb/SKILL.md b/.agents/skills/query-kb/SKILL.md index fefd2f3..463727c 100644 --- a/.agents/skills/query-kb/SKILL.md +++ b/.agents/skills/query-kb/SKILL.md @@ -1,6 +1,6 @@ --- name: query-kb -description: Load scoped repository context, then search and navigate a hraness/kb Markdown vault with hybrid text retrieval, exact metadata, bounded links and typed relationships, backlinks, whole-vault graph reports, and optional Git provenance. Use when an agent needs the applicable repository instructions, rationale, prior knowledge, plans, captures, decisions, concepts, relationships, or evidence before answering, planning, or changing code. +description: Load scoped repository context, then search and navigate a hraness/wordcell Markdown vault with hybrid text retrieval, exact metadata, bounded links and typed relationships, backlinks, whole-vault graph reports, and optional Git provenance. Use when an agent needs the applicable repository instructions, rationale, prior knowledge, plans, captures, decisions, concepts, relationships, or evidence before answering, planning, or changing code. --- # Query the knowledge base @@ -21,39 +21,39 @@ authority; search scores, metadata rows, and graph results are derived views. ## Choose the retrieval lane -- Repository file or directory: run `kb context` first. Read its inherited +- 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 `kb list`. -- Known note title, path, or alias: use `kb links` or `kb backlinks`, which +- 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 `kb graph --json`, +- 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 `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 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. ```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 +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 ``` -`kb context` prints hub and record summaries, not their bodies. Each record +`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 @@ -77,7 +77,7 @@ known. ## Use hybrid search as discovery -`kb search` first scans current Markdown for identity, phrase, metadata, tag, +`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 @@ -87,7 +87,7 @@ 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" +wordcell index --root "$KB_ROOT" ``` Use `--mode exact` for live model-free search, `--mode keyword` for QMD @@ -110,8 +110,8 @@ 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 ` returns the bounded commit history already associated with -one resolved note. `kb history search ` searches the bounded Git +`wordcell history ` returns the bounded commit history already associated with +one resolved note. `wordcell history search ` 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. @@ -122,7 +122,7 @@ For several related queries, prefer one SDK session to repeated CLI process startup: ```ts -import { openKnowledgeBase, packSearchContext } from "@hraness/kb/sdk"; +import { openKnowledgeBase, packSearchContext } from "@hraness/wordcell/sdk"; const kb = await openKnowledgeBase({ root: "kb", repository: "." }); try { @@ -152,14 +152,14 @@ results and the final output remain typed. ## Use focused structural views -`kb graph --json` returns the current resolved wikilinks, typed relationships, +`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 `kb relation list`, -`kb backlinks`, or `kb links` when a known note gives you a narrower starting +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. -`kb links` is cycle-safe and requires an explicit traversal depth and result -limit. `kb relation list` separates authored outbound assertions from derived +`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. @@ -171,18 +171,18 @@ 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. +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 `kb list` to narrow by authored metadata such as `type`, `status`, +3. Use `wordcell 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 +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 `kb graph --json` only when the question genuinely spans multiple +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. @@ -193,11 +193,11 @@ 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"`. +`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. `kb catalog --root "$KB_ROOT"` renders the exhaustive +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. diff --git a/.agents/skills/refresh-kb/AGENTS.md b/.agents/skills/refresh-kb/AGENTS.md index c25c60f..d6fa919 100644 --- a/.agents/skills/refresh-kb/AGENTS.md +++ b/.agents/skills/refresh-kb/AGENTS.md @@ -1,12 +1,12 @@ # Contents -- `SKILL.md` – reusable refresh-review-check workflow for a hraness/kb vault. +- `SKILL.md` – reusable refresh-review-check workflow for a hraness/wordcell vault. - `agents/openai.yaml` – user-facing skill metadata and invocation prompt. # Guidelines -- Keep this bundle self-contained under the public hraness/kb identity and free of repository-specific policy, paths, names, or provenance. -- Keep the primary workflow aligned with catalog-skipping parallel-lane checks, bounded percolation, one integrating managed-catalog `kb refresh --root `, contextual review, and `kb check --root `. Authored mode leaves the front door untouched. +- Keep this bundle self-contained under the public hraness/wordcell identity and free of repository-specific policy, paths, names, or provenance. +- Keep the primary workflow aligned with catalog-skipping parallel-lane checks, bounded percolation, one integrating managed-catalog `wordcell refresh --root `, contextual review, and `wordcell check --root `. Authored mode leaves the front door untouched. - Describe catalog links as navigation and backlinks, inverse relationships, orphans, mentions, and percolation candidates as derived graph analysis. - Never direct agents to inject reciprocal, transitive, or similarity-derived relationships, generate backlink sections, or mutate authored prose automatically. - Keep the skill concise, imperative, and usable without loading files outside this directory. diff --git a/.agents/skills/refresh-kb/SKILL.md b/.agents/skills/refresh-kb/SKILL.md index d38ed85..73a58a9 100644 --- a/.agents/skills/refresh-kb/SKILL.md +++ b/.agents/skills/refresh-kb/SKILL.md @@ -1,6 +1,6 @@ --- name: refresh-kb -description: Refresh and validate a hraness/kb Markdown knowledge graph after notes, concepts, typed relationships, attachments, repository scopes, or context mappings change. Use when an agent needs to maintain a managed or authored catalog, inspect graph and lifecycle findings, validate local artifacts and scope hubs, or complete a vault health check. +description: Refresh and validate a hraness/wordcell Markdown knowledge graph after notes, concepts, typed relationships, attachments, repository scopes, or context mappings change. Use when an agent needs to maintain a managed or authored catalog, inspect graph and lifecycle findings, validate local artifacts and scope hubs, or complete a vault health check. --- # Refresh a knowledge base @@ -24,7 +24,7 @@ When several agents are still editing a managed vault, do not refresh its shared catalog in each lane. Validate the lane's Markdown and graph facts with: ```sh -kb check --root "$KB_ROOT" --no-catalog +wordcell check --root "$KB_ROOT" --no-catalog ``` The integrating agent performs the managed refresh once after the lanes join. @@ -34,12 +34,12 @@ no catalog write and is safe from that shared generated-file hotspot. Run: ```sh -kb refresh --root "$KB_ROOT" +wordcell refresh --root "$KB_ROOT" ``` In managed mode this command atomically updates only the marked catalog region in `index.md`. In authored mode it reports the index as authored and leaves the -file unchanged. Use `kb catalog --root "$KB_ROOT"` for a disposable exhaustive +file unchanged. Use `wordcell catalog --root "$KB_ROOT"` for a disposable exhaustive inventory in either mode. Catalog links are navigation, so they do not count as contextual graph edges. @@ -62,7 +62,7 @@ Open every reported source line and the relevant target notes before deciding wh - When a repository-owned scope audit reports an absent active or maintained scope, inspect it as possible stale routing. Future paths may intentionally be absent; terminal records may intentionally retain retired paths. The - portable `kb refresh` and `kb check` commands do not impose this lifecycle + portable `wordcell refresh` and `wordcell check` commands do not impose this lifecycle policy by themselves. Backlinks are derived from explicit contextual wikilinks and typed @@ -74,7 +74,7 @@ automatically or apply suggestions mechanically in bulk. Run a bounded percolation review for each materially changed note: ```sh -kb percolate "" --root "$KB_ROOT" --limit 25 --json +wordcell percolate "" --root "$KB_ROOT" --limit 25 --json ``` Open the cited notes before deciding whether to create a reusable @@ -85,7 +85,7 @@ Intentional orphans and unlinked mentions may remain. Record the reason instead Review recent captures without maintained disposition when useful: ```sh -kb inbox --root "$KB_ROOT" --limit 25 --json +wordcell inbox --root "$KB_ROOT" --limit 25 --json ``` The inbox ignores source-to-source and catalog links. It is advisory; an @@ -97,8 +97,8 @@ If the change adds, removes, renames, or moves a scope hub, changes its `type` or `scope`, or edits an `kb:context` marker, run: ```sh -kb agents identity "" --json -kb agents check --root "$KB_ROOT" --repo "$KB_REPO" +wordcell agents identity "" --json +wordcell agents check --root "$KB_ROOT" --repo "$KB_REPO" ``` Use the non-mutating identity command to derive the hub path and exact marker @@ -113,7 +113,7 @@ Use the audit when the change affects guide structure, inheritance, or repeated rules: ```sh -kb agents audit --root "$KB_ROOT" --repo "$KB_REPO" +wordcell agents audit --root "$KB_ROOT" --repo "$KB_REPO" ``` The audit runs the correctness checks and adds deterministic per-guide, @@ -128,7 +128,7 @@ generated and vendor directories and never follows symbolic-link directories. After any note or link edit, run the refresh command again so derived state and advisories reflect the final content. Then run the read-only gate: ```sh -kb check --root "$KB_ROOT" +wordcell check --root "$KB_ROOT" ``` Finish only when the graph check and any required agent-context check succeed, diff --git a/.agents/skills/save-pdf-kb/AGENTS.md b/.agents/skills/save-pdf-kb/AGENTS.md index cd8b52c..8f0e6ba 100644 --- a/.agents/skills/save-pdf-kb/AGENTS.md +++ b/.agents/skills/save-pdf-kb/AGENTS.md @@ -6,7 +6,7 @@ # Guidelines -- Invoke the installed `kb` CLI; do not depend on a source checkout or implementation path. +- Invoke the installed `wordcell` CLI; do not depend on a source checkout or implementation path. - Preserve the source PDF byte-for-byte, record sanitized remote URL provenance when present, and never persist its original absolute path. - Keep native text, image text, and visual assets as independent evidence surfaces. - Retain every extracted image even when its text is converted to Markdown. diff --git a/.agents/skills/save-pdf-kb/SKILL.md b/.agents/skills/save-pdf-kb/SKILL.md index 25fa9b7..5c32313 100644 --- a/.agents/skills/save-pdf-kb/SKILL.md +++ b/.agents/skills/save-pdf-kb/SKILL.md @@ -11,23 +11,23 @@ description: >- # Save a PDF to the knowledge base -Use the installed `kb` CLI. Resolve `` to the directory containing its +Use the installed `wordcell` CLI. Resolve `` 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). Check the local conversion routes, then capture the PDF: ```sh -kb doctor -kb pdf "/absolute/path/to/document.pdf" --output "$KB_ROOT/articles" -kb pdf "https://example.com/document.pdf" --output "$KB_ROOT/articles" +wordcell doctor +wordcell pdf "/absolute/path/to/document.pdf" --output "$KB_ROOT/articles" +wordcell pdf "https://example.com/document.pdf" --output "$KB_ROOT/articles" ``` Pass a stable slug or replace a prior tool-owned bundle only when needed: ```sh -kb pdf "/absolute/path/to/document.pdf" --slug ben-leaves-zo --output "$KB_ROOT/articles" -kb pdf "/absolute/path/to/document.pdf" --output "$KB_ROOT/articles" --force +wordcell pdf "/absolute/path/to/document.pdf" --slug ben-leaves-zo --output "$KB_ROOT/articles" +wordcell pdf "/absolute/path/to/document.pdf" --output "$KB_ROOT/articles" --force ``` The command installs one atomic bundle: @@ -86,7 +86,7 @@ and rerun the capture: ``` ```sh -kb pdf "/absolute/path/to/document.pdf" \ +wordcell pdf "/absolute/path/to/document.pdf" \ --output "$KB_ROOT/articles" \ --annotations /tmp/pdf-image-annotations.json \ --force @@ -130,7 +130,7 @@ Review: After adding or linking the capture, run the vault's normal refresh and check: ```sh -kb percolate "" --root "$KB_ROOT" --limit 25 --json -kb refresh --root "$KB_ROOT" -kb check --root "$KB_ROOT" +wordcell percolate "" --root "$KB_ROOT" --limit 25 --json +wordcell refresh --root "$KB_ROOT" +wordcell check --root "$KB_ROOT" ``` diff --git a/.agents/skills/save-url-kb/AGENTS.md b/.agents/skills/save-url-kb/AGENTS.md index 8638426..8cbed08 100644 --- a/.agents/skills/save-url-kb/AGENTS.md +++ b/.agents/skills/save-url-kb/AGENTS.md @@ -6,11 +6,11 @@ # Guidelines -- Invoke the installed `kb` CLI; do not depend on a source checkout or implementation path. +- Invoke the installed `wordcell` CLI; do not depend on a source checkout or implementation path. - Preserve missing, blocked, deleted, cyclic, paginated, and limit-boundary states in every report. - Keep public APIs, HTTP, cookies, browser rendering, media, and evidence as independent fallbacks with auditable attempts. - Never claim a thread or discussion is complete when declared counts, cursors, pagination nodes, or configured bounds disagree. - Keep credentials in memory, user-owned private files, or short-lived mode-`0600` operating-system temporary files. Never place cookies, authorization values, browser state, authenticated raw DOM, or HARs in capture artifacts. - Capture only public or user-entitled content. Do not bypass access controls, CAPTCHA, rate limits, DRM, or platform policy. - Treat screenshots as potentially private evidence because pixels are not structurally sanitized. -- Verify the installed environment with `kb doctor` and the current platform matrix with `kb adapters`. +- Verify the installed environment with `wordcell doctor` and the current platform matrix with `wordcell adapters`. diff --git a/.agents/skills/save-url-kb/SKILL.md b/.agents/skills/save-url-kb/SKILL.md index b80c243..697b296 100644 --- a/.agents/skills/save-url-kb/SKILL.md +++ b/.agents/skills/save-url-kb/SKILL.md @@ -12,11 +12,11 @@ description: >- # Capture web content -Use the installed `kb` CLI. Check the available local routes when the capture may need a browser or optional media tools: +Use the installed `wordcell` CLI. Check the available local routes when the capture may need a browser or optional media tools: ```sh -kb doctor -kb adapters +wordcell doctor +wordcell adapters ``` Resolve `` to the directory containing its authored or managed @@ -30,7 +30,7 @@ to captures and read the vault's applicable agent instructions before writing. Start ordinary URL capture with the layered default: ```sh -kb clip https://example.com/article --output "$KB_ROOT/articles" +wordcell clip https://example.com/article --output "$KB_ROOT/articles" ``` The command tries stable structured data, bounded HTTP extraction, and rendered-browser fallback as needed. If those routes produce no usable source material, URL capture may perform one read-only lookup for an existing Archive.today-family snapshot. It never submits the source for archival. A useful structured provider result, including a partial Hacker News result, remains authoritative over the archive fallback. @@ -38,8 +38,8 @@ The command tries stable structured data, bounded HTTP extraction, and rendered- When the source is already open in a signed-in browser, read the current tab in place: ```sh -kb clip current --browser-live --output "$KB_ROOT/articles" -kb clip current --cdp 9222 --output "$KB_ROOT/articles" +wordcell clip current --browser-live --output "$KB_ROOT/articles" +wordcell clip current --cdp 9222 --output "$KB_ROOT/articles" ``` For `--browser-live`, first enable Chrome's local debugging connection at `chrome://inspect/#remote-debugging` (Chrome 144+). If Chrome was launched with an explicit loopback debugging port, pass that numeric port to `--cdp` instead. @@ -49,16 +49,16 @@ Current-tab capture derives the source URL from the attached tab. It does not na To open a URL with existing browser state, select a profile. A path-backed profile is copied into a temporary snapshot for the capture, so the source profile remains unchanged: ```sh -kb clip https://example.com/member/article --browser-profile "$KB_CAPTURE_PROFILE" --output "$KB_ROOT/articles" +wordcell clip https://example.com/member/article --browser-profile "$KB_CAPTURE_PROFILE" --output "$KB_ROOT/articles" ``` Use cookie-backed HTTP when the page does not require browser-only local state, or import a page already saved from any browser: ```sh -kb clip https://example.com/member/article --cookie-source chrome --cookie-profile "Default" --output "$KB_ROOT/articles" -kb clip https://example.com/member/article --cookies-file "$KB_COOKIES_FILE" --output "$KB_ROOT/articles" -kb clip https://example.com/article --html "$KB_SAVED_HTML" --output "$KB_ROOT/articles" -kb clip https://example.com/article --html - --output "$KB_ROOT/articles" < page.html +wordcell clip https://example.com/member/article --cookie-source chrome --cookie-profile "Default" --output "$KB_ROOT/articles" +wordcell clip https://example.com/member/article --cookies-file "$KB_COOKIES_FILE" --output "$KB_ROOT/articles" +wordcell clip https://example.com/article --html "$KB_SAVED_HTML" --output "$KB_ROOT/articles" +wordcell clip https://example.com/article --html - --output "$KB_ROOT/articles" < page.html ``` Read [references/authentication.md](references/authentication.md) for current-tab, profile, cookie, and saved-page selection details. @@ -72,18 +72,18 @@ If a new surface needs support, add an extraction route, fixture coverage, or a ## Choose scope and artifacts ```sh -kb clip https://example.com/post --scope page --output "$KB_ROOT/articles" -kb clip https://example.com/post --scope thread --output "$KB_ROOT/articles" -kb clip https://example.com/discussion --scope comments --output "$KB_ROOT/articles" -kb clip https://example.com/post --media none --output "$KB_ROOT/articles" -kb clip https://example.com/post --media all --output "$KB_ROOT/articles" -kb clip https://example.com/post --evidence source --output "$KB_ROOT/articles" -kb clip https://example.com/post --evidence all --output "$KB_ROOT/articles" -kb clip https://example.com/post --output "$KB_CAPTURE_OUTPUT" -kb clip https://example.com/post --force --output "$KB_ROOT/articles" +wordcell clip https://example.com/post --scope page --output "$KB_ROOT/articles" +wordcell clip https://example.com/post --scope thread --output "$KB_ROOT/articles" +wordcell clip https://example.com/discussion --scope comments --output "$KB_ROOT/articles" +wordcell clip https://example.com/post --media none --output "$KB_ROOT/articles" +wordcell clip https://example.com/post --media all --output "$KB_ROOT/articles" +wordcell clip https://example.com/post --evidence source --output "$KB_ROOT/articles" +wordcell clip https://example.com/post --evidence all --output "$KB_ROOT/articles" +wordcell clip https://example.com/post --output "$KB_CAPTURE_OUTPUT" +wordcell clip https://example.com/post --force --output "$KB_ROOT/articles" ``` -With the resolved output path, `kb clip` installs one atomic bundle under +With the resolved output path, `wordcell clip` installs one atomic bundle under `$KB_ROOT/articles//`: ```text @@ -120,15 +120,15 @@ Source evidence is stored as sanitized inert HTML. Screenshots are viewport pixe With KB installed, build the pinned Rust metadata-search helper and backfill every saved external URL into a separate tool-owned sidecar: ```sh -kb url-metadata tool build -kb url-metadata backfill --root "$KB_ROOT" --json +wordcell url-metadata tool build +wordcell url-metadata backfill --root "$KB_ROOT" --json ``` The backfill runs serially with bounded output and time, resumes compatible sidecars by default, and searches for exact source matches plus existing Archive.today-family snapshots. It never rewrites the saved Markdown or adopts the search library's URL normalization, accepts descriptive metadata only from an exact source match, records partial or failed engines literally, and never promotes search output into `capture.json`. Use `--refresh` for an explicit replacement run after reviewing the provider and archive disclosure policy. ## Report completeness literally -Read [references/platforms.md](references/platforms.md) when selecting or explaining a route. Use `kb adapters --json` when software needs the installed capability matrix. +Read [references/platforms.md](references/platforms.md) when selecting or explaining a route. Use `wordcell adapters --json` when software needs the installed capability matrix. Interpret status as follows: @@ -147,15 +147,15 @@ Preserve missing, deleted, blocked, cyclic, depth-limited, item-limited, and pag Treat the captured Markdown and manifest as the source record. Put summaries, comparisons, decisions, and changing interpretations in a maintained note rather than rewriting the capture to match a later conclusion. Connect the maintained note to the capture with an explicit wikilink. Let -`kb backlinks` derive incoming relationships; do not insert reciprocal links or +`wordcell backlinks` derive incoming relationships; do not insert reciprocal links or generated backlink sections into authored notes. After adding or linking a capture, review the maintained note for reusable concepts and relationships, then run the vault's normal refresh and check loop: ```sh -kb percolate "" --root "$KB_ROOT" --limit 25 --json -kb refresh --root "$KB_ROOT" -kb check --root "$KB_ROOT" +wordcell percolate "" --root "$KB_ROOT" --limit 25 --json +wordcell refresh --root "$KB_ROOT" +wordcell check --root "$KB_ROOT" ``` ## Review the result diff --git a/.agents/skills/save-url-kb/references/authentication.md b/.agents/skills/save-url-kb/references/authentication.md index 00bcafa..3d6ea8c 100644 --- a/.agents/skills/save-url-kb/references/authentication.md +++ b/.agents/skills/save-url-kb/references/authentication.md @@ -9,8 +9,8 @@ These examples assume `KB_ROOT` is the resolved vault directory containing its a When the desired page is already open and signed in, capture it in place: ```sh -kb clip current --browser-live --output "$KB_ROOT/articles" -kb clip current --cdp 9222 --output "$KB_ROOT/articles" +wordcell clip current --browser-live --output "$KB_ROOT/articles" +wordcell clip current --cdp 9222 --output "$KB_ROOT/articles" ``` For `--browser-live`, first enable Chrome's local debugging connection at `chrome://inspect/#remote-debugging` (Chrome 144+). If Chrome was launched with an explicit loopback debugging port, pass that numeric port to `--cdp` instead. Both routes read the current HTTP or HTTPS tab, derive its URL and platform, and leave the external browser open. @@ -22,8 +22,8 @@ Current-tab capture does not navigate, click, type, submit, upload, or scroll. U Use `--browser-profile` when the tool should open a URL with existing cookies, local storage, IndexedDB, and related browser state: ```sh -kb clip https://example.com/member/article --browser-profile "$KB_CAPTURE_PROFILE" --output "$KB_ROOT/articles" -kb clip https://example.com/member/article --browser-profile "Work" --output "$KB_ROOT/articles" +wordcell clip https://example.com/member/article --browser-profile "$KB_CAPTURE_PROFILE" --output "$KB_ROOT/articles" +wordcell clip https://example.com/member/article --browser-profile "Work" --output "$KB_ROOT/articles" ``` A path-backed profile is copied to a private temporary browser snapshot before navigation. The copy keeps the selected profile data and Chromium `Local State`, omits caches and lock files, runs as the owned capture session, and is deleted afterward. Page activity therefore does not change the source profile. @@ -37,20 +37,20 @@ URL-based browser capture can navigate to the requested page and scroll within f When an existing browser should navigate to a specific URL instead of preserving the current tab, use the URL form: ```sh -kb clip https://example.com/member/article --browser-live --output "$KB_ROOT/articles" -kb clip https://example.com/member/article --cdp 9222 --output "$KB_ROOT/articles" +wordcell clip https://example.com/member/article --browser-live --output "$KB_ROOT/articles" +wordcell clip https://example.com/member/article --cdp 9222 --output "$KB_ROOT/articles" ``` -The external browser remains open. Choose `kb clip current` instead when the already-open view is the source of truth. +The external browser remains open. Choose `wordcell clip current` instead when the already-open view is the source of truth. ## Use cookies for HTTP, assets, or media Cookie-backed HTTP capture is useful when the source does not depend on browser-only state: ```sh -kb clip https://example.com/member/article --cookie-source chrome --cookie-profile "Default" --output "$KB_ROOT/articles" -kb clip https://example.com/member/article --cookie-source firefox --cookie-profile "work" --output "$KB_ROOT/articles" -kb clip https://example.com/member/article --cookies-file "$KB_COOKIES_FILE" --output "$KB_ROOT/articles" +wordcell clip https://example.com/member/article --cookie-source chrome --cookie-profile "Default" --output "$KB_ROOT/articles" +wordcell clip https://example.com/member/article --cookie-source firefox --cookie-profile "work" --output "$KB_ROOT/articles" +wordcell clip https://example.com/member/article --cookies-file "$KB_COOKIES_FILE" --output "$KB_ROOT/articles" ``` Supported cookie sources include Chrome, Arc, Brave, Chromium, Edge, Firefox, and Safari. Select one cookie source or one cookie file per command. Cookie-Editor JSON and Netscape files retain domain and path metadata; a bare Cookie header or Copy-as-cURL file is narrowed to the captured host and path. @@ -58,7 +58,7 @@ Supported cookie sources include Chrome, Arc, Brave, Chromium, Edge, Firefox, an An attached browser's session state stays in that browser. Combine its capture with one explicit cookie input when later image or media downloads also need the same signed-in access: ```sh -kb clip current --browser-live --cookie-source chrome --cookie-profile "Default" --media all --output "$KB_ROOT/articles" +wordcell clip current --browser-live --cookie-source chrome --cookie-profile "Default" --media all --output "$KB_ROOT/articles" ``` The output bundle records which acquisition lanes ran, but it does not include cookie values, browser-profile files, or attached browser state. @@ -68,8 +68,8 @@ The output bundle records which acquisition lanes ran, but it does not include c Saved HTML is a useful fallback for any page the browser can render: ```sh -kb clip https://example.com/member/article --html "$KB_SAVED_HTML" --output "$KB_ROOT/articles" -kb clip https://example.com/member/article --html - --output "$KB_ROOT/articles" < page.html +wordcell clip https://example.com/member/article --html "$KB_SAVED_HTML" --output "$KB_ROOT/articles" +wordcell clip https://example.com/member/article --html - --output "$KB_ROOT/articles" < page.html ``` The URL remains the provenance anchor while the saved file supplies the page representation. Review the resulting manifest because a saved document cannot prove whether unloaded or virtualized content existed outside that representation. diff --git a/.agents/skills/save-url-kb/references/platforms.md b/.agents/skills/save-url-kb/references/platforms.md index c400190..b568117 100644 --- a/.agents/skills/save-url-kb/references/platforms.md +++ b/.agents/skills/save-url-kb/references/platforms.md @@ -18,7 +18,7 @@ Use the strongest available read route, then describe exactly what it retained. | Instagram, Facebook, LinkedIn, and TikTok | Current tab, rendered profile, or saved HTML; yt-dlp for accessible media | Preserves the loaded post, caption, visible discussion, inline images, and exposed video poster or thumbnail | Lazy loading, collapsed branches, and virtualization remain partial | | Other signed-in pages, feeds, inboxes, and private documents | Current tab first; temporary path-backed profile copy when the tool should open a URL; cookie-backed HTTP or saved HTML when sufficient | Preserves the content rendered by the selected source surface | Content outside the current loaded representation is not inferred | -Run `kb adapters --json` when software needs the installed capability matrix. Platform markup and routes change; a successful rendered fallback does not upgrade a partial tree to `complete` unless declared counts, cursors, and boundaries agree. +Run `wordcell adapters --json` when software needs the installed capability matrix. Platform markup and routes change; a successful rendered fallback does not upgrade a partial tree to `complete` unless declared counts, cursors, and boundaries agree. For foreign structured data, parse from `unknown`. Keep missing, deleted, blocked, cyclic, depth-limited, item-limited, and pagination-boundary nodes visible instead of dropping them. For generic rendered discussions, retain the visible prose but use conservative item counts rather than inventing a thread structure. diff --git a/kb/AGENTS.md b/kb/AGENTS.md index 86210c5..adb3461 100644 --- a/kb/AGENTS.md +++ b/kb/AGENTS.md @@ -16,6 +16,6 @@ - Never write reciprocal, transitive, similarity-derived, or otherwise inferred relationships into notes. Backlinks, graph traversal, and percolation candidates are disposable views. - Preserve source authority: article bodies are captures, riffs retain the speaker's claims, and maintained notes own later synthesis. - Keep `AGENTS.md` normative and concise without removing load-bearing rules. A scope hub may hold rationale, history, examples, and linked decisions, but never silently overrides a guide or becomes the only home of an edit-time rule. -- Run `kb percolate --root .` after materially changing a note, review the cited evidence, then run `kb refresh --root .` and `kb check --root .`. -- During parallel edits, each lane runs `kb check --root . --no-catalog`; the integrating agent performs one final refresh and normal check. -- Use `kb context --root . --repo ` for scoped repository knowledge, `kb list` for exact metadata or tags, `kb graph` for the whole explicit graph, `kb links` for bounded relationship traversal, and `kb search` when the concept may use different words. +- Run `wordcell percolate --root .` after materially changing a note, review the cited evidence, then run `wordcell refresh --root .` and `wordcell check --root .`. +- During parallel edits, each lane runs `wordcell check --root . --no-catalog`; the integrating agent performs one final refresh and normal check. +- Use `wordcell context --root . --repo ` for scoped repository knowledge, `wordcell list` for exact metadata or tags, `wordcell graph` for the whole explicit graph, `wordcell links` for bounded relationship traversal, and `wordcell search` when the concept may use different words. diff --git a/kb/scopes/AGENTS.md b/kb/scopes/AGENTS.md index 9c1f43d..226908b 100644 --- a/kb/scopes/AGENTS.md +++ b/kb/scopes/AGENTS.md @@ -5,6 +5,6 @@ # Guidelines - Keep one hub per exact repository-relative directory scope, with `type: agent-context` and `scope` in frontmatter. -- Derive the canonical hub path and reciprocal marker with `kb agents identity `; do not reproduce the slug or hash logic by hand. +- Derive the canonical hub path and reciprocal marker with `wordcell agents identity `; do not reproduce the slug or hash logic by hand. - Put rationale, history, examples, evidence, and links here. Keep ownership, prohibitions, required commands, and every rule needed before editing in the guide. -- Use `kb agents check --root --repo ` after changing a mapping; use `kb agents audit` to review guide and inherited-chain size without treating length as correctness. +- Use `wordcell agents check --root --repo ` after changing a mapping; use `wordcell agents audit` to review guide and inherited-chain size without treating length as correctness.