@hraness/wordcell 0.21.3 → 0.22.1

package/skills/wordcell/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Wordcell"
   short_description: "Set up, query, capture, and maintain Markdown memory"
-  default_prompt: "Use $wordcell to set up or work with this hraness/wordcell knowledge base, routing the request before any runtime preparation and loading only the references needed. Follow its optional support protocol once at an eligible human-facing task closeout."
+  default_prompt: "Use $wordcell to set up or work with this hraness/wordcell knowledge base, routing the request before any runtime preparation and loading only the references needed. Prefer the repository's approved pinned kb:search script for search and inspect rerank diagnostics when it enables hosted processing. Follow its optional support protocol once at an eligible human-facing task closeout."

package/skills/wordcell/references/publish.md

@@ -0,0 +1,127 @@
+# Publish selected knowledge as a static site
+
+Use `wordcell publish` to turn selected Markdown notes into read-only pages,
+backlinks, a graph, and browser-local search. It builds files locally with no
+model call. Publishing here means generating the artifact; uploading it to a
+host is a separate action.
+
+## Select and preview
+
+Use the scope in the user's request. Ask only when the selection or destination
+is materially ambiguous. Resolve `KB_ROOT` before running commands, and choose
+an output directory outside the vault that does not contain it.
+
+Start with a compact, read-only preview:
+
+```sh
+wordcell publish --root "$KB_ROOT" --out ./public-notes \
+  --include notes/decision --include plans/implementation \
+  --dry-run --list-limit 20 --json
+```
+
+The report contains counts, at most 20 selected note IDs, and a digest of the
+selected Markdown. It does not print note bodies. Inspect `selection.truncated` before
+treating the preview as a complete list. Raise `--list-limit` up to 1000 when
+individual IDs matter, or use zero for counts and a digest alone. Open only
+selected notes whose contents need review; do not load or summarize the whole
+vault to choose a known slice.
+
+Selectors are repeatable:
+
+- `--include <id-or-directory>` selects exact notes or directory prefixes.
+- `--include-glob 'notes/**'` and `--exclude-glob '**/draft-*'` select by pattern.
+  Quote globs so the shell does not expand them. `*` matches within one segment,
+  `?` matches one character, and `**` matches whole path segments.
+- `--where type=concept`, `--has relations`, `--tag public`, and
+  `--scope packages/parser` select by authored metadata.
+- `--from notes/topic --depth 2 --direction both` selects a bounded neighborhood
+  of explicit links and relationships. Oversized neighborhoods fail rather
+  than silently publish an incomplete selection.
+
+Positive path, glob, metadata, and graph selectors form a **union**. Metadata
+predicates within their group must all match. `--include notes --tag public`
+therefore includes all of `notes`, not only its public-tagged notes. Use a
+metadata conjunction or explicit note IDs when an intersection is required.
+Excludes and `publish: false` always win.
+
+Publication is not prose redaction. Review selected text and referenced assets
+for anything unsuitable for the intended audience. A selected note can mention
+excluded material in its own text. Private flags exclude a note's page, search
+record, and graph membership; they cannot remove information copied into another
+note or attachment. `--noindex` is a crawler preference, not access control.
+
+## Build the reviewed slice
+
+Repeat the preview command without `--dry-run`. Keep the same selectors and
+check the returned digest and counts; if the Markdown changed, review it again.
+The digest covers selected Markdown, not attachment bytes. Review referenced
+attachments separately before sharing.
+
+```sh
+wordcell publish --root "$KB_ROOT" --out ./public-notes \
+  --include notes/decision --include plans/implementation \
+  --title "Project decisions" --deterministic --json
+```
+
+Use `--force` only to replace a known generated output directory. Set
+`--base-path /handbook/` if the host serves the files at a subpath, and add
+`--base-url https://docs.example.com` when a sitemap is useful. Use
+`--no-index-content` for field-only search. None of these flags changes the
+source vault.
+
+Read dropped-link, skipped-asset, and search-truncation counts. Run
+`wordcell check --root "$KB_ROOT"` when missing links or attachments need
+diagnosis. Do not report missing content as complete.
+
+## Preview and host
+
+```sh
+wordcell serve --root ./public-notes --port 8080
+```
+
+Open the loopback URL. Check a note, its navigation, the Search overlay, and the
+Graph page. HTML can be read without JavaScript; browser search and graph need
+HTTP hosting rather than `file://`. The preview server is not a production
+service.
+
+Upload the generated directory to the user's selected static host only when
+hosting is in the request. Confirm the exact destination and preserve unrelated
+files. Verify the public URL and selected content after upload. A successful
+local build alone is not a live deployment.
+
+The full artifact contract and hosting options are in
+[the publishing guide](https://github.com/hraness/wordcell/blob/main/docs/publish.md).
+
+## Publish through wordcell.io when the CLI cannot run
+
+Agents on platforms without a filesystem or Bun runtime can publish the same
+`hraness.wordcell.site.v1` artifact through the hosted surface. It runs the
+identical projection server-side; published sites are public.
+
+```sh
+# Self-serve capability token (IP-limited; shown once — store it).
+TOKEN=$(curl -sf -X POST https://wordcell.io/api/v1/tokens \
+  -H 'content-type: application/json' -d '{"label":"my-agent"}' | jq -r .token)
+
+# Publish a vault as a files map: path -> utf8 string, {"base64":"..."}, or
+# {"upload":"<id>"} from POST /api/v1/uploads for larger assets.
+curl -sf -X PUT "https://wordcell.io/api/v1/sites/my-notes" \
+  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
+  -d '{"files":{"index.md":"# Notes\n","a.md":"# A\n"},"title":"My notes"}'
+# -> {"site":{"url":"https://wordcell.io/p/<key8>/my-notes/",...},"idempotent":false}
+```
+
+`GET /api/v1/sites` lists the token's sites and `DELETE /api/v1/sites/{slug}`
+unpublishes. Identical bytes republish idempotently without a revision bump;
+changed bytes sweep the superseded artifact. Deletes and republishes can take
+up to 60 seconds to propagate at the edge. MCP clients can instead point at the
+streamable-HTTP endpoint `POST https://wordcell.io/api/v1/mcp`, which exposes
+`create_token`, `publish_site`, `list_sites`, and `delete_site` tools over the
+same routes — `create_token` is unauthenticated so an MCP-only client can
+onboard itself. `GET /api/v1/openapi.json` describes the REST surface.
+
+The hosted surface carries the same selection semantics (`selection` mirrors
+the CLI selectors) and the same redaction warning: `publish: false` excludes a
+note, it does not erase text quoted elsewhere. Bounded inputs apply — at most
+256 files and 4 MiB inline per publish, 32 MiB per uploaded asset, 50 live
+sites per token.

package/skills/wordcell/references/query.md

@@ -155,6 +155,28 @@ 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.
 
+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.
+
 `wordcell history <note>` returns the bounded commit history already associated with
 one resolved note. `wordcell history search <query-or-path>` searches the bounded Git
 projection directly and retains hashes, subjects, matched paths, co-change

package/skills/wordcell/references/refresh.md

@@ -126,6 +126,20 @@ After any note or link edit, run the refresh command again so derived state and
 wordcell check --root "$KB_ROOT"
 ```
 
+When the vault lives inside a repository and `KB_REPO` is set, add the advisory
+repository-state pass:
+
+```sh
+wordcell check --root "$KB_ROOT" --repo "$KB_REPO"
+```
+
+This compares every authored `repository_scopes` declaration with the current
+working tree and reports each current record whose declared path is now absent
+or unusable. It is advisory: the exit code does not change, and a terminal plan
+that names a removed path stays silent because that is valid authored history.
+Treat an absent-scope advisory as a note to reread against the code, not as a
+proven error; confirm the path in the repository before editing the note.
+
 Finish only when the graph check and any required agent-context check succeed,
 the configured catalog mode is satisfied, and broken or ambiguous links,
 relationships, and local attachments are resolved. Summarize deliberate

package/src/authoring-model.ts

@@ -89,6 +89,11 @@ export interface AuthoringOptions {
   readonly dependencies?: Partial<AuthoringDependencies>;
 }
 
+export interface UpdateNoteBodyOptions extends AuthoringOptions {
+  /** Exact revision read before preparing the replacement body. */
+  readonly expectedRevision: NoteRevision;
+}
+
 export class InvalidCanonicalNoteIdError extends TypeError {
   readonly noteId: string;
 
@@ -692,6 +697,30 @@ export function normalizedRequestedBody(body: string): string {
   return body.endsWith("\n") ? body : `${body}\n`;
 }
 
+/** Replace prose without serializing or modifying the authored frontmatter. */
+export function renderUpdatedNoteBody(
+  snapshot: Pick<NoteSnapshot, "content" | "relativePath">,
+  parts: FrontmatterParts,
+  body: string,
+): string {
+  if (typeof body !== "string") throw new TypeError("a note body must be a string");
+  if (Buffer.byteLength(body, "utf8") > MAX_NOTE_BYTES) {
+    throw new RangeError("the note body is too large for bounded authoring");
+  }
+  if (Buffer.from(body, "utf8").toString("utf8") !== body) {
+    throw new TypeError("a note body must contain well-formed Unicode");
+  }
+  const normalized = normalizedRequestedBody(body);
+  if (!parts.hadFrontmatter) {
+    if (frontmatter(normalized, snapshot.relativePath).hadFrontmatter) {
+      throw new TypeError("a body update cannot introduce frontmatter into a note");
+    }
+    return normalized;
+  }
+  const header = snapshot.content.slice(0, snapshot.content.length - parts.bodySuffix.length);
+  return `${header}${parts.newline}${parts.newline}${normalized}`;
+}
+
 export function renderCreatedNote(input: CreateNoteInput, documentId: string): string {
   const title = validateTitle(input.title);
   const type = validateType(input.type);

package/src/authoring-program.ts

@@ -3,13 +3,13 @@ import { Effect, Exit } from "effect";
 import {
   MAX_NOTE_BYTES, NoteRevisionConflictError, addRelationToParts, assertCompatibleCreate,
   assertExpected, canonicalNoteId, canonicalRelationTarget, checkedExpectedRevision,
-  frontmatter, isErrno, normalizeRelationPredicate, noteResult, pathFor, relationsFromParts,
-  removeRelationFromParts, renderCreatedNote, renderFrontmatter, revisionFor,
+  existingDocumentId, frontmatter, isErrno, normalizeRelationPredicate, noteResult, pathFor, relationsFromParts,
+  removeRelationFromParts, renderCreatedNote, renderFrontmatter, renderUpdatedNoteBody, requireRevision, revisionFor,
   sameQuarantinedSnapshot, sameSnapshot, withRecoveryPath,
 } from "./authoring-model.js";
 import type {
   AuthoringDependencies, AuthoringInstallContext, AuthoringOptions, CreateNoteInput,
-  DirectoryIdentity, NoteAuthoringResult, NoteRevision, NoteSnapshot, RecoveryLocation, Vault,
+  DirectoryIdentity, NoteAuthoringResult, NoteRevision, NoteSnapshot, RecoveryLocation, UpdateNoteBodyOptions, Vault,
 } from "./authoring-model.js";
 import type { NoteLock } from "./note-lock.js";
 import { parseDocumentId } from "./portfolio-identity.js";
@@ -276,3 +276,38 @@ export function editNoteRelationProgram(
     );
   });
 }
+
+export function updateNoteBodyProgram(
+  platform: AuthoringPlatform, root: string, idInput: string, body: string,
+  options: UpdateNoteBodyOptions,
+): Effect.Effect<NoteAuthoringResult, AuthoringFailure> {
+  return Effect.gen(function*() {
+    const id = yield* authoringSync(() => canonicalNoteId(idInput));
+    const expected = yield* authoringSync(() => {
+      if (typeof options?.expectedRevision !== "string") {
+        throw new TypeError("expectedRevision is required for a note body update");
+      }
+      return requireRevision(options.expectedRevision);
+    });
+    const vault = yield* authoringNative(() => platform.resolveVault(root));
+    const dependencies = yield* authoringSync(() => platform.dependenciesFor(options.dependencies));
+    return yield* authoringResource(
+      authoringNative(() => platform.acquireNoteLock(vault.root, id, options.lock)),
+      (lock) => Effect.gen(function*() {
+        yield* authoringNative(() => platform.recoverInterruptedAuthoring(vault, id, lock));
+        const source = yield* authoringNative(() => platform.readSnapshot(vault, id));
+        yield* authoringSync(() => assertExpected(source, expected));
+        const parts = yield* authoringSync(() => frontmatter(source.content, source.relativePath));
+        const identity = yield* authoringSync(() => existingDocumentId(parts));
+        if (identity.kind === "invalid") return yield* fail(new TypeError("the note has an invalid document_id"));
+        const documentId = identity.kind === "valid" ? identity.documentId : undefined;
+        const relations = yield* authoringSync(() => relationsFromParts(parts, source.relativePath));
+        const content = yield* authoringSync(() => renderUpdatedNoteBody(source, parts, body));
+        if (content === source.content) return yield* authoringSync(() => noteResult(source, relations, false, documentId));
+        const revision = yield* installNote(platform, vault, id, content, source, lock, dependencies);
+        return yield* authoringSync(() => noteResult({ relativePath: source.relativePath, revision }, relations, true, documentId));
+      }),
+      (lock) => authoringNative(() => lock.release()),
+    );
+  });
+}

package/src/authoring.ts

@@ -1,12 +1,12 @@
 import type {
   AuthoringOptions, CreateConceptNoteInput, CreateNoteInput, NoteAuthoringResult,
-  NoteRelation, NoteRevision,
+  NoteRelation, NoteRevision, UpdateNoteBodyOptions,
 } from "./authoring-model.js";
 import { canonicalNoteId, frontmatter, relationsFromParts } from "./authoring-model.js";
 import {
   assertNoInterruptedRecovery, nativeAuthoringPlatform, readSnapshot, resolveVault,
 } from "./authoring-platform.js";
-import { createNoteProgram, editNoteRelationProgram } from "./authoring-program.js";
+import { createNoteProgram, editNoteRelationProgram, updateNoteBodyProgram } from "./authoring-program.js";
 import { runAuthoring } from "./authoring-runtime.js";
 
 export {
@@ -15,7 +15,7 @@ export {
 } from "./authoring-model.js";
 export type {
   AuthoringDependencies, AuthoringInstallContext, AuthoringOptions,
-  CreateConceptNoteInput, CreateNoteInput, NoteAuthoringResult, NoteRelation, NoteRevision,
+  CreateConceptNoteInput, CreateNoteInput, NoteAuthoringResult, NoteRelation, NoteRevision, UpdateNoteBodyOptions,
 } from "./authoring-model.js";
 
 /**
@@ -60,6 +60,20 @@ export async function createConceptNote(
   return createNote(root, { ...input, type: "concept" }, options);
 }
 
+/**
+ * Replace one existing note's body at an exact revision. Frontmatter bytes,
+ * stable identity and relations remain unchanged. Like createNote, this adds a
+ * final newline and separates frontmatter from the body with one blank line.
+ *
+ * A stale revision fails even if the requested body already matches. Callers
+ * must read back an interrupted operation before deciding whether to retry.
+ */
+export async function updateNoteBody(
+  root: string, id: string, body: string, options: UpdateNoteBodyOptions,
+): Promise<NoteAuthoringResult> {
+  return runAuthoring(updateNoteBodyProgram(nativeAuthoringPlatform, root, id, body, options));
+}
+
 /** Add one exact outbound typed relation, idempotently. */
 export async function addNoteRelation(
   root: string, sourceId: string, predicate: string, targetId: string, options: AuthoringOptions = {},