@hraness/wordcell 0.22.0 → 0.22.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/wordcell",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "description": "A local knowledge base for coding agents. Save decisions in Markdown and recover the context behind your code.",
   "license": "MIT",
   "type": "module",
@@ -476,14 +476,15 @@
     "url-metadata:tool:build": "bun ./dist/cli.js url-metadata tool build",
     "url-metadata:tool:check": "bun ./dist/cli.js url-metadata tool check",
     "test:package": "bun run ./scripts/package-smoke.ts",
-    "check": "bun run check:effect && bun run check:workflows && bun run check:portfolio-inventory && bun run check:installed-command-docs && bun run typecheck && bun run build && bun run test:package && bun run test && bun run url-metadata:tool:check",
+    "check": "bun run check:worker && bun run check:effect && bun run check:workflows && bun run check:portfolio-inventory && bun run check:installed-command-docs && bun run typecheck && bun run build && bun run test:package && bun run test && bun run url-metadata:tool:check",
     "prepack": "bun run check",
     "check:effect": "bun run scripts/check-effect-policy.ts",
-    "kb:search": "bunx --bun --package https://github.com/hraness/wordcell/releases/download/v0.22.0/hraness-wordcell-0.22.0.tgz wordcell search --root kb --mode exact --rerank typesafe --rerank-limit 25",
-    "kb:search:local": "bunx --bun --package https://github.com/hraness/wordcell/releases/download/v0.22.0/hraness-wordcell-0.22.0.tgz wordcell search --root kb --mode exact"
+    "kb:search": "bunx --bun --package https://github.com/hraness/wordcell/releases/download/v0.22.1/hraness-wordcell-0.22.1.tgz wordcell search --root kb --mode exact --rerank typesafe --rerank-limit 25",
+    "kb:search:local": "bunx --bun --package https://github.com/hraness/wordcell/releases/download/v0.22.1/hraness-wordcell-0.22.1.tgz wordcell search --root kb --mode exact",
+    "check:worker": "tsc -p worker/tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@hraness/oh": "https://github.com/hraness/oh/releases/download/v0.10.8/hraness-oh-0.10.8.tgz",
+    "@hraness/oh": "https://github.com/hraness/oh/releases/download/v0.11.0/hraness-oh-0.11.0.tgz",
     "@steipete/sweet-cookie": "0.4.3",
     "@tobilu/qmd": "git+https://github.com/hraness/qmd.git#aa993dceb3ef8cfb71d470554ca437570f5a2b3c",
     "agent-browser": "0.32.3",

package/skills/wordcell/SKILL.md

@@ -35,7 +35,7 @@ selected.
 | Create or update an implementation plan, proposal, RFC, migration plan, execution audit, or phased checklist in the vault | [Write a durable plan](references/plan.md) and [use its structure](references/plan-structure.md) |
 | Review recurring ideas, promote concepts, or add and verify typed relationships | [Percolate concepts and relationships](references/percolate.md) |
 | Refresh or validate the catalog, graph, attachments, repository scopes, context mappings, or overall vault health | [Refresh and check the knowledge base](references/refresh.md) |
-| Publish a vault or a selected subsection as a hosted read-only static site with browser-local search | [Publish a static site](references/publish.md) |
+| Publish a vault or a selected subsection as a hosted read-only static site with browser-local search — locally via `wordcell publish`, or over the wordcell.io REST/MCP surface when no filesystem or Bun runtime is available | [Publish a static site](references/publish.md) |
 
 Read more than one primary reference only when the request spans those
 workflows. For example, saving a source and linking it from a maintained note
@@ -56,7 +56,7 @@ missing:
 ```sh
 command -v wordcell >/dev/null 2>&1 || {
   command -v bun >/dev/null 2>&1 || exit 1
-  bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.22.0/hraness-wordcell-0.22.0.tgz
+  bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.22.1/hraness-wordcell-0.22.1.tgz
 }
 wordcell --help
 ```

package/skills/wordcell/references/publish.md

@@ -91,3 +91,37 @@ 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/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 = {},

package/src/cli-program.ts

@@ -122,10 +122,14 @@ import {
   type QuerySort,
 } from "./query.js";
 import {
+  auditRepositoryMemoryScopes,
   buildRepositoryMemoryContext,
+  MAX_REPOSITORY_MEMORY_DETAIL_LIMIT,
   MAX_REPOSITORY_SCOPES,
   repositoryMemoryGroupKeys,
   type RepositoryMemoryContext,
+  type RepositoryMemoryScopeAudit,
+  type RepositoryMemoryScopeAuditError,
 } from "./repository-memory.js";
 import { validateSearchQuery } from "./search.js";
 import {
@@ -248,7 +252,7 @@ Usage:
   wordcell inspect <url> [capture options]
   wordcell pdf <file-or-url> [PDF options]
   wordcell refresh [--root <directory>] [--index <path>] [--json]
-  wordcell check [--root <directory>] [--index <path>] [--no-catalog] [--json]
+  wordcell check [--root <directory>] [--index <path>] [--no-catalog] [--repo <repository>] [--json]
   wordcell catalog [--root <directory>] [--index <path>] [--json]
   wordcell graph [--root <directory>] [--index <path>] [--json]
   wordcell graph rebuild [--fresh] [--root <directory>] [--index <path>] [--json]
@@ -443,6 +447,8 @@ type ParsedCommand =
       readonly depth?: number;
       readonly limit?: number;
       readonly noCatalog?: boolean;
+      /** `check --repo` only: repository working tree for the advisory scope lane. */
+      readonly repository?: string;
     }
   | {
       readonly kind: "note-create";
@@ -528,6 +534,7 @@ type CliDependencies = GraphCliDependencies & {
   readonly percolateWithGraph?: typeof percolateWithGraph;
   readonly inspectAgentContextRepository?: typeof inspectAgentContextRepository;
   readonly buildRepositoryMemoryContext?: typeof buildRepositoryMemoryContext;
+  readonly auditRepositoryMemoryScopes?: typeof auditRepositoryMemoryScopes;
   readonly auditAgentGuideRepository?: typeof auditAgentGuideRepository;
   readonly validateMarkdownAttachments?: typeof validateMarkdownAttachments;
   readonly publishVault?: typeof publishVault;
@@ -623,6 +630,7 @@ function parseVaultCommand(command: VaultCommand, arguments_: readonly string[])
   let depth = 1;
   let limit: number | undefined;
   let noCatalog = false;
+  let repository: string | undefined;
   const positional: string[] = [];
 
   for (let cursor = 0; cursor < arguments_.length; cursor += 1) {
@@ -636,6 +644,13 @@ function parseVaultCommand(command: VaultCommand, arguments_: readonly string[])
       noCatalog = true;
       continue;
     }
+    if (argument === "--repo" && command === "check") {
+      const value = readValue(arguments_, cursor);
+      if (value === null) return { ok: false, message: "--repo requires a value" };
+      repository = value;
+      cursor += 1;
+      continue;
+    }
     if (argument === "--root" || argument === "--index") {
       const value = readValue(arguments_, cursor);
       if (value === null) return { ok: false, message: `${argument} requires a value` };
@@ -700,6 +715,7 @@ function parseVaultCommand(command: VaultCommand, arguments_: readonly string[])
       options: index === undefined ? {} : { index },
       json,
       ...(command === "check" && noCatalog ? { noCatalog: true } : {}),
+      ...(command === "check" && repository !== undefined ? { repository } : {}),
     },
   };
 }
@@ -2637,6 +2653,7 @@ function summary(
   options: {
     readonly noCatalog?: boolean;
     readonly attachments?: AttachmentValidationReport;
+    readonly repositoryScopes?: RepositoryMemoryScopeAudit;
   } = {},
 ): Record<string, unknown> {
   return {
@@ -2662,6 +2679,9 @@ function summary(
             issues: options.attachments.issues,
           },
         }),
+    ...(options.repositoryScopes === undefined
+      ? {}
+      : { repositoryScopes: options.repositoryScopes }),
   };
 }
 
@@ -2697,6 +2717,60 @@ function renderAdvisories(analysis: VaultAnalysis): string[] {
   return lines;
 }
 
+function renderRepositoryScopeAuditError(error: RepositoryMemoryScopeAuditError): string {
+  if (error.kind === "invalid-record") {
+    return `${safe(error.path)}: ${error.issues.map(safe).join(" ")}`;
+  }
+  const declared = error.recordPaths.map(safe).join(", ")
+    + (error.recordPathsTruncated ? ", …" : "");
+  return `${safe(error.scope)}: ${safe(error.state.reason)} at ${safe(error.state.path)}`
+    + ` (declared by ${declared})`;
+}
+
+/**
+ * Advisory repository-state lane for `check --repo`.
+ *
+ * Every line derives from authored `repository_scopes` declarations and the
+ * working tree they name. Nothing here changes the exit code: a current note
+ * that names a path the repository no longer has is reported for a reader to
+ * judge, never treated as a vault correctness failure.
+ */
+function renderRepositoryScopeAudit(audit: RepositoryMemoryScopeAudit): string[] {
+  const { counts } = audit;
+  const lines = [
+    `Repository scopes: ${counts.authoredRecords} declaring note${counts.authoredRecords === 1 ? "" : "s"}; `
+      + `${counts.distinctScopes} distinct scope${counts.distinctScopes === 1 ? "" : "s"} `
+      + `(${counts.presentScopes} present, ${counts.absentScopes} absent, ${counts.invalidScopes} unusable).`,
+  ];
+  if (audit.advisories.total > 0) {
+    lines.push(audit.advisories.total === 1
+      ? "Advisory: 1 current note declares a repository path that no longer exists."
+      : `Advisory: ${audit.advisories.total} current notes declare repository paths that no longer exist.`);
+    for (const advisory of audit.advisories.details) {
+      lines.push(`  ${safe(advisory.path)} declares absent scope ${safe(advisory.scope)}`);
+    }
+    if (audit.advisories.truncated) {
+      lines.push(
+        `  … ${audit.advisories.total - audit.advisories.returned} more; rerun with --json for the complete audit.`,
+      );
+    }
+  }
+  if (audit.errors.total > 0) {
+    lines.push(
+      `Advisory: ${audit.errors.total} repository scope declaration problem${audit.errors.total === 1 ? "" : "s"}.`,
+    );
+    for (const error of audit.errors.details) {
+      lines.push(`  ${renderRepositoryScopeAuditError(error)}`);
+    }
+    if (audit.errors.truncated) {
+      lines.push(
+        `  … ${audit.errors.total - audit.errors.returned} more; rerun with --json for the complete audit.`,
+      );
+    }
+  }
+  return lines;
+}
+
 function checkExitCode(
   snapshot: VaultSnapshot,
   noCatalog = false,
@@ -2723,6 +2797,7 @@ function renderSnapshot(
   snapshot: VaultSnapshot,
   noCatalog = false,
   attachments?: AttachmentValidationReport,
+  repositoryScopes?: RepositoryMemoryScopeAudit,
 ): string {
   const lines = [
     `${command === "refresh" ? "Refreshed" : "Checked"} ${safe(snapshot.root)}`,
@@ -2742,6 +2817,7 @@ function renderSnapshot(
     lines.push("error: attachment validation was truncated by a resource limit");
   }
   lines.push(...renderAdvisories(snapshot.analysis));
+  if (repositoryScopes !== undefined) lines.push(...renderRepositoryScopeAudit(repositoryScopes));
   return `${lines.join("\n")}\n`;
 }
 
@@ -3806,9 +3882,24 @@ async function runVault(
           documents: snapshot.notes.map(({ path, content }) => ({ path, content })),
         })
       : undefined;
+    const repositoryScopes = command.kind === "check" && command.repository !== undefined
+      ? await (dependencies.auditRepositoryMemoryScopes ?? auditRepositoryMemoryScopes)(
+          snapshot.notes,
+          {
+            repositoryRoot: command.repository,
+            detailLimit: MAX_REPOSITORY_MEMORY_DETAIL_LIMIT,
+          },
+        )
+      : undefined;
     output.stdout(command.json
-      ? terminalSafeJson(summary(snapshot, { noCatalog, ...(attachments === undefined ? {} : { attachments }) }))
-      : sanitizeTerminalText(renderSnapshot(command.kind, snapshot, noCatalog, attachments)));
+      ? terminalSafeJson(summary(snapshot, {
+          noCatalog,
+          ...(attachments === undefined ? {} : { attachments }),
+          ...(repositoryScopes === undefined ? {} : { repositoryScopes }),
+        }))
+      : sanitizeTerminalText(
+        renderSnapshot(command.kind, snapshot, noCatalog, attachments, repositoryScopes),
+      ));
     return checkExitCode(snapshot, noCatalog, attachments);
   }
   if (command.kind === "graph") {

package/src/graph.ts

@@ -608,7 +608,7 @@ function aliasesFromMetadata(metadata: MetadataObject): readonly string[] {
 }
 
 function frontmatterOf(content: string, path: string): Frontmatter {
-  const lines = content.split("\n");
+  const lines = content.split(/\r?\n/u);
   if (lines[0]?.trim() !== "---") {
     return {
       values: new Map(),