@gmickel/gno 2.2.1 → 2.3.1

package/README.md

@@ -117,7 +117,7 @@ gno daemon --detach  # headless indexing + resident MCP gateway
 
 <!-- public-truth:current-version -->
 
-> Current source version: **v2.2.1**. See [CHANGELOG.md](./CHANGELOG.md).
+> Current source version: **v2.3.1**. See [CHANGELOG.md](./CHANGELOG.md).
 
 <!-- /public-truth -->
 
@@ -288,6 +288,9 @@ gno query "ECONNREFUSED 127.0.0.1:5432" --thorough
 
 ```bash
 gno setup ~/notes --name notes   # Build BM25 and prove an exact local result
+gno skill install --target claude --scope user # Choose your agent
+gno agents install --target claude # Teach retrieval and writing discipline
+gno agents verify --target claude
 gno daemon --detach              # Keep index fresh in the background (macOS/Linux)
 gno query "auth best practices"  # Hybrid search
 gno ask "summarize the API" --answer  # AI answer with citations
@@ -365,6 +368,30 @@ See also: [docs/DAEMON.md](./docs/DAEMON.md)
 
 ### Connect to AI Agents
 
+For a second brain or LLM wiki, install both a connector and the retrieval
+protocol. The skill teaches GNO commands and workflows; the instruction block
+teaches the harness when to retrieve, how to choose an efficient search path,
+and how to cite and maintain knowledge. A connector alone does not establish
+that discipline.
+
+```bash
+gno skill install --target claude --scope user
+gno agents install --target claude
+gno agents verify --target claude
+```
+
+Choose your harness target (`claude`, `codex`, `opencode`, `openclaw`, or
+`hermes`). For MCP clients, install the MCP connector instead of the skill,
+then add the protocol where the harness supports it. `gno agents install`
+without a target covers detected supported harnesses; see the
+[agent instructions guide](docs/AGENT-INSTRUCTIONS.md) for the target matrix and
+manual guidance. It preserves text outside its managed block.
+
+Start a fresh agent session and ask a question answered by an indexed document.
+Check that the agent retrieves it and cites the source. `gno agents verify`
+checks the installed block, not model behavior. CLI and Web UI users can skip
+agent setup.
+
 #### MCP Server (Claude Desktop, Cursor, Zed, etc.)
 
 One command to add GNO to your AI assistant:
@@ -391,7 +418,7 @@ target, add `--force` to preview the replacement without writing it.
 
 Check status: `gno mcp status`
 
-#### Skills (Claude Code, Codex, OpenCode, OpenClaw)
+#### Skills (Claude Code, Codex, OpenCode, OpenClaw, Hermes)
 
 Skills integrate via CLI with no MCP overhead and include second-brain recipe playbooks:
 
@@ -400,6 +427,7 @@ gno skill install --scope user        # User-wide
 gno skill install --target codex      # Codex
 gno skill install --target opencode   # OpenCode
 gno skill install --target openclaw   # OpenClaw
+gno skill install --target hermes     # Hermes
 gno skill install --target all        # All targets
 ```
 
@@ -627,10 +655,12 @@ Give your local LLM agents a long-term memory. GNO integrates as a Claude Code s
 
 ### Skills
 
-Skills add GNO search to Claude Code, Codex, OpenCode, and OpenClaw without MCP protocol overhead:
+Skills teach Claude Code, Codex, OpenCode, OpenClaw, and Hermes how to use GNO. Pair the skill with the retrieval protocol for second-brain and LLM-wiki work:
 
 ```bash
 gno skill install --scope user
+gno agents install --target claude
+gno agents verify --target claude
 ```
 
 ![GNO Skill in Claude Code](./assets/screenshots/claudecodeskill.jpg)
@@ -818,7 +848,23 @@ On [Omarchy](https://omarchy.org/), [**GNO Recall**](https://github.com/gmickel/
 omarchy plugin add https://github.com/gmickel/omarchy-gno-recall --enable
 ```
 
-Requires gno >= 1.36.0 on `PATH`.
+Then install the plugin's verified runtime and, optionally, the Super+R binding:
+
+```bash
+cd ~/.config/omarchy/plugins/gmickel.gno-recall
+./scripts/install-runtime.sh
+./scripts/install-keybind.sh # Optional; checks for conflicts
+```
+
+[Marketplace listing](https://omarchyplugins.com/plugin.html?id=gmickel.gno-recall)
+· [Setup and runtime compatibility](https://github.com/gmickel/omarchy-gno-recall#install)
+· [Screenshots](https://github.com/gmickel/omarchy-gno-recall#screenshots)
+
+Recall uses its own verified GNO/Bun runtime. A global GNO upgrade does not
+update it; follow the plugin's update instructions and shared-index
+compatibility guidance.
+
+![GNO Recall searching a demo index](https://raw.githubusercontent.com/gmickel/omarchy-gno-recall/main/assets/screenshots/overlay-search.png)
 
 ---
 

package/assets/skill/README.md

@@ -1,10 +1,10 @@
 # GNO — Agent Skill
 
 Local-first semantic search for documents, notes, and knowledge bases,
-packaged as a Claude Code / Codex / OpenCode / OpenClaw skill.
+packaged as a Claude Code / Codex / OpenCode / OpenClaw / Hermes skill.
 
 > **TL;DR** — this folder is a runnable agent skill. Drop it into any
-> Claude Code, Codex, OpenCode, or OpenClaw workspace and the agent can
+> Claude Code, Codex, OpenCode, OpenClaw, or Hermes workspace and the agent can
 > index and search your local files through the `gno` CLI.
 
 ## Prerequisites
@@ -13,14 +13,10 @@ You need the `gno` CLI installed locally. The skill drives it; it does
 not ship the binary itself.
 
 ```bash
-# macOS / Linux
-curl -fsSL https://gno.sh/install | bash
-
-# npm / Bun
-bun add -g @gmickel/gno        # or: npm install -g @gmickel/gno
+bun install -g @gmickel/gno
 ```
 
-Verify: `gno --version` should print `1.0.3` or later.
+Verify the installed release with `gno --version`. Use the bundled skill to match that release.
 
 ## Install the skill
 
@@ -30,8 +26,7 @@ you're starting from.
 ### Option A — install from your local `gno` (recommended if you already have GNO)
 
 If you already installed GNO, it ships this skill in-tree. One command
-drops it into the right place for every supported agent, always in sync
-with your installed GNO version:
+drops it into the right place for every supported agent, matching the GNO version installed when you run it:
 
 ```bash
 gno skill install --target claude       # Claude Code (default)
@@ -59,23 +54,67 @@ gno skill paths                         # resolved installation paths
 gno skill uninstall --target all        # remove from all agents
 ```
 
-This path always gives you the skill that matches your GNO CLI — no
-version drift.
+After upgrading GNO, refresh the installed copy as described below.
+
+### Option B: ClawHub-managed installation
+
+Use the [GNO listing](https://clawhub.ai/gmickel/gno) when your harness manages
+skills through a registry. The GNO executable is still required separately.
+
+```bash
+# OpenClaw workspace: run from its workspace root
+bunx clawhub@0.23.3 install @gmickel/gno
+bunx clawhub@0.23.3 update @gmickel/gno
+
+# Hermes hub installation
+hermes skills install clawhub/gno # May require review; prefer the local installer
+hermes skills check
+hermes skills update gno
+```
+
+GNO releases publish the same source bundle to ClawHub. Choose one installer
+for a given skill directory so registry and local copies do not overwrite one
+another. For Hermes, prefer the local GNO installer if your hub version cannot
+retrieve the full bundle. A bare SKILL.md URL may omit recipes and references.
 
-### Option B — install from ClawHub (recommended if you use OpenClaw)
+## Install the retrieval protocol too
 
-ClawHub is the OpenClaw skill registry. Use this when you manage
-skills centrally across multiple workspaces or when you don't have GNO
-installed yet.
+For second-brain and LLM-wiki work, pair the skill with standing instructions
+for the harness. The skill teaches commands and workflows; the protocol teaches
+when to retrieve, which search path to use, and how to cite and maintain knowledge.
 
 ```bash
-openclaw skills install gno             # installs @gmickel/gno
-openclaw skills update gno              # pull a newer version later
-openclaw skills info gno                # inspect what's installed
+gno agents install          # Detected supported harnesses
+gno agents verify
 ```
 
-You can also browse the skill at
-<https://clawhub.ai/gmickel/gno> and download the folder manually.
+Use `--target claude`, `codex`, `opencode`, `openclaw`, or `hermes` for one
+harness. MCP users should install the protocol too where supported. Text outside
+the managed instruction block stays unchanged. Start a fresh session and verify
+that the agent retrieves and cites a document from your index. The verify command
+checks the block, not model behavior. See [agent instructions](https://gno.sh/docs/agents-install).
+
+## Keep installations current
+
+Local installs copy the skill from your installed GNO release. After upgrading,
+refresh the selected target and protocol:
+
+```bash
+gno skill install --target hermes --scope user --force
+gno agents update --target hermes
+gno agents verify --target hermes
+```
+
+`--force` replaces local skill edits. Preserve your customizations before using
+it. Change the target for another harness. Registry installs use their native
+update command instead; upgrading the GNO executable alone does not refresh them.
+
+For unattended registry updates, schedule only the chosen skill's native update
+command with your OS scheduler, using the same user, workspace, and executable
+paths as the interactive install. Preserve logs and keep safety prompts enabled;
+an update that needs approval must remain pending. Run `gno agents update` after
+upgrading GNO. New skill versions can require a newer executable, so update GNO
+before refreshing the skill. Publishing a release does not modify users' machines.
 
 ## What the skill teaches the agent
 

package/assets/skill/SKILL.md

@@ -509,6 +509,13 @@ gno embed --collection travel
 
 MCP `gno.sync` and `gno.capture` do NOT auto-embed. Use CLI for embedding.
 
+Optional index-wide YAML `chunking.maxTokens` and `chunking.overlapPercent`
+control size and overlap (`0.15` means 15%). Leave defaults unless asked to
+tune them. After a change, `gno index` rechunks cached mirrors and embeds;
+`gno update` rechunks only. Check `gno status --json` fields
+`chunking.pendingMirrors` and `embeddingBacklog`. Use separate `--config`
+files and `--index` names for comparisons; see [cli-reference.md](cli-reference.md).
+
 ## Capture Notes
 
 Use `gno capture` for quick second-brain writes into an editable collection:

package/assets/skill/cli-reference.md

@@ -24,6 +24,22 @@ punctuation. NFC/case-equivalent spellings share one identity. See
 
 ## Initialization
 
+### Optional index-wide chunking
+
+User YAML can set `chunking: { maxTokens: 256, overlapPercent: 0.15 }`.
+Defaults remain 800 approximate tokens and 0.15 overlap; unchanged/default
+config does not force a rebuild. The token estimate uses four characters per
+token, and overlap accepts a fraction from 0 through 0.5.
+
+After changing policy, `gno index` rechunks cached mirrors and embeds changed
+chunks. `gno update` performs the rechunking without embedding. The policy
+applies across the index even for targeted source sync; original files are not
+read merely to rechunk. `gno status --json` reports configured/applied policy,
+pending mirrors/documents, and a separate embedding backlog. On
+`CHUNKING_POLICY_CONFLICT`, reopen the client with the intended configuration.
+Compare policies with separate `--config` files and `--index` names, holding
+corpus, models, query set, and type boosts constant.
+
 ### gno setup
 
 Preferred activation path: add one folder, prove a real exact lexical result,

package/browser-extension/artifacts/gno-browser-clipper-v2.3.1.zip.sha256

@@ -0,0 +1 @@
+674db0a56d6ba5a485f4d6195066a7cd700b3dbbbcbf921b12047548fcdd21e0  gno-browser-clipper-v2.3.1.zip

package/browser-extension/dist/manifest.json

@@ -21,5 +21,5 @@
   "content_security_policy": {
     "extension_pages": "script-src 'self'; object-src 'none'; connect-src http://127.0.0.1:*"
   },
-  "version": "2.2.1"
+  "version": "2.3.1"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "2.2.1",
+  "version": "2.3.1",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",

package/spec/cli.md

@@ -531,6 +531,27 @@ protection remain authoritative.
 `graphHints` is active: ordered hints type
 projected wiki/markdown edges and surface in graph traversal/diagnose metadata.
 
+Optional root `chunking` sets one policy per index. `maxTokens` defaults to 800
+and accepts integers from 10 through 2251799813685247; the chunker estimates
+four characters per token. `overlapPercent` defaults to 0.15 and accepts a
+fraction from 0 through 0.5. Missing fields inherit defaults. Invalid values
+fail configuration validation before index mutation.
+
+Omitted or explicitly default settings preserve existing chunks and embeddings
+on upgrade. A policy change rechunks cached Markdown mirrors during the next
+index/update or targeted sync, including mirrors outside the source-refresh
+collection. Rechunking does not read original files or claim source freshness.
+Sync-only operations leave changed chunks pending embedding; `gno index`
+also embeds. A stale writer receives `CHUNKING_POLICY_CONFLICT` and must reopen
+its client/runtime with the intended configuration.
+
+Status JSON adds `chunking` with `configured` parameters, `applied` parameters
+(null for empty/mixed layouts), `state` (`empty`, `legacy-default`, `current`,
+`pending`, or `mixed`), `pendingDocuments`, and `pendingMirrors`. These counts
+cover active cached content, independently of source errors and embedding
+backlog. Sync receipts optionally add `rechunkedMirrors` when cached layouts
+were updated; existing file counters keep their source-refresh meaning.
+
 `collections[].sourceAvailability` is optional; omitted means `any`. Exact
 values: `any` | `local`. There is no separate public knob beyond these two
 modes and no claim that availability is egress policy. `any` preserves

package/spec/mcp.md

@@ -1352,6 +1352,15 @@ counters; it never claims attachment to another process.
 normalized IDs/factors plus the rules fingerprint; path prefixes are never
 returned.
 
+`chunking` reports the index-wide configuration and cached layout readiness:
+`configured` and `applied` contain `maxTokens` and `overlapPercent` (`applied`
+is null for empty/mixed layouts); `state` is `empty`, `legacy-default`,
+`current`, `pending`, or `mixed`; `pendingDocuments` and `pendingMirrors` count
+active cached content using another policy. Source refresh errors and embedding
+backlog remain separate. Reading status never rechunks or changes the policy.
+Sync results may include `rechunkedMirrors` when a policy change updates cached
+layouts. A stale client must reopen on `CHUNKING_POLICY_CONFLICT`.
+
 ---
 
 ### gno_recall

package/spec/output-schemas/status.schema.json

@@ -24,6 +24,47 @@
     "resident"
   ],
   "properties": {
+    "chunking": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "configured",
+        "applied",
+        "state",
+        "pendingDocuments",
+        "pendingMirrors"
+      ],
+      "properties": {
+        "configured": { "$ref": "#/properties/chunking/definitions/params" },
+        "applied": {
+          "oneOf": [
+            { "$ref": "#/properties/chunking/definitions/params" },
+            { "type": "null" }
+          ]
+        },
+        "state": {
+          "type": "string",
+          "enum": ["empty", "legacy-default", "current", "pending", "mixed"]
+        },
+        "pendingDocuments": { "type": "integer", "minimum": 0 },
+        "pendingMirrors": { "type": "integer", "minimum": 0 }
+      },
+      "definitions": {
+        "params": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["maxTokens", "overlapPercent"],
+          "properties": {
+            "maxTokens": {
+              "type": "integer",
+              "minimum": 10,
+              "maximum": 2251799813685247
+            },
+            "overlapPercent": { "type": "number", "minimum": 0, "maximum": 0.5 }
+          }
+        }
+      }
+    },
     "resident": {
       "$ref": "gno://schemas/resident-status@1.0"
     },

package/src/cli/commands/shared.ts

@@ -160,6 +160,12 @@ export function formatSyncResultLines(
 ): string[] {
   const lines: string[] = [];
 
+  if (syncResult.rechunkedMirrors) {
+    lines.push(
+      `Rechunked ${syncResult.rechunkedMirrors} cached mirrors. Run gno embed if embedding was skipped.`
+    );
+  }
+
   for (const c of syncResult.collections) {
     lines.push(`${c.collection}:`);
     lines.push(

package/src/cli/commands/status.ts

@@ -19,6 +19,7 @@ import {
 } from "../../config";
 import { isConnectorActivationComplete } from "../../core/activation-connector-health";
 import { buildActivationStatus } from "../../core/activation-status";
+import { formatChunkingStatus } from "../../core/chunking-status";
 import {
   buildMemoryStatus,
   formatMemoryStatusLines,
@@ -112,6 +113,9 @@ function formatTerminal(
     lines.push(`Embedding backlog: ${indexStatus.embeddingBacklog} chunks`);
   }
 
+  const chunking = formatChunkingStatus(indexStatus.chunking);
+  if (chunking) lines.push(chunking);
+
   if (indexStatus.recentErrors > 0) {
     lines.push(`Recent errors: ${indexStatus.recentErrors} (last 24h)`);
   }
@@ -198,6 +202,9 @@ function formatMarkdown(
   lines.push(`- **Embedding backlog**: ${indexStatus.embeddingBacklog}`);
   lines.push(`- **Recent errors**: ${indexStatus.recentErrors}`);
 
+  const chunking = formatChunkingStatus(indexStatus.chunking);
+  if (chunking) lines.push(`- ${chunking}`);
+
   if (indexStatus.lastUpdatedAt) {
     lines.push(`- **Last updated**: ${indexStatus.lastUpdatedAt}`);
   }
@@ -274,6 +281,7 @@ export async function status(
   try {
     const statusResult = await store.getStatus({
       embedModel: resolveModelUri(config, "embed"),
+      chunking: config.chunking ?? {},
     });
     if (!statusResult.ok) {
       return { success: false, error: statusResult.error.message };
@@ -339,6 +347,7 @@ export function formatStatus(
         totalDocuments: s.activeDocuments,
         totalChunks: s.totalChunks,
         embeddingBacklog: s.embeddingBacklog,
+        chunking: s.chunking,
         lastUpdated: s.lastUpdatedAt,
         healthy: isStatusHealthy(s, result.activation),
         contentTypeBoost: result.contentTypeBoost,

package/src/config/chunking.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+
+/** Existing character-based chunker defaults. */
+export const DEFAULT_CHUNKING_PARAMS = {
+  maxTokens: 800,
+  overlapPercent: 0.15,
+};
+
+export const MAX_CHUNK_TOKENS = Math.floor(Number.MAX_SAFE_INTEGER / 4);
+
+export const ChunkingConfigSchema = z
+  .object({
+    maxTokens: z
+      .number()
+      .int()
+      .min(10)
+      .max(MAX_CHUNK_TOKENS)
+      .default(DEFAULT_CHUNKING_PARAMS.maxTokens),
+    overlapPercent: z
+      .number()
+      .finite()
+      .min(0)
+      .max(0.5)
+      .default(DEFAULT_CHUNKING_PARAMS.overlapPercent),
+  })
+  .strict();
+
+export type ChunkingParams = z.infer<typeof ChunkingConfigSchema>;
+
+export function resolveChunkingParams(
+  input?: Partial<ChunkingParams>
+): ChunkingParams {
+  return ChunkingConfigSchema.parse(input ?? {});
+}
+
+/** Canonical JSON is the policy identity, including partial/default aliases. */
+export function chunkingPolicyKey(params: ChunkingParams): string {
+  return JSON.stringify({
+    maxTokens: params.maxTokens,
+    overlapPercent: params.overlapPercent,
+  });
+}
+
+export const DEFAULT_CHUNKING_POLICY_KEY = chunkingPolicyKey(
+  DEFAULT_CHUNKING_PARAMS
+);

package/src/config/types.ts

@@ -12,6 +12,7 @@ import { z } from "zod";
 import { URI_PREFIX } from "../app/constants";
 import { JsonlFieldMappingSchema } from "../converters/adapters/jsonl/config";
 import { MCP_TOOL_PROFILES } from "../mcp/tool-profile";
+import { ChunkingConfigSchema, type ChunkingParams } from "./chunking";
 import { RetrievalTraceConfigSchema } from "./retrieval-traces";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -595,6 +596,9 @@ export const ConfigSchema = z.object({
   /** Opt-in schema-lite content type rules */
   contentTypes: z.array(ContentTypeSchema).default([]),
 
+  /** Optional index-wide chunk size/overlap; omitted preserves legacy defaults. */
+  chunking: ChunkingConfigSchema.optional(),
+
   /** Model configuration */
   models: ModelConfigSchema.optional(),
 
@@ -632,9 +636,10 @@ export const ConfigSchema = z.object({
 
 export type Config = Omit<
   z.infer<typeof ConfigSchema>,
-  "contentTypes" | "busyTimeoutMs"
+  "contentTypes" | "busyTimeoutMs" | "chunking"
 > & {
   contentTypes?: ContentTypeConfig[];
+  chunking?: Partial<ChunkingParams>;
   /** Present after schema parse; omitted on hand-built Config objects. */
   busyTimeoutMs?: number;
 };

package/src/core/chunking-status.ts

@@ -0,0 +1,30 @@
+import type { ChunkingParams } from "../config/chunking";
+import type { ChunkingStatus } from "../store/chunking";
+
+import {
+  chunkingPolicyKey,
+  DEFAULT_CHUNKING_POLICY_KEY,
+} from "../config/chunking";
+
+const formatParams = (params: ChunkingParams): string =>
+  `${params.maxTokens} approximate tokens / ${Number((params.overlapPercent * 100).toFixed(4))}% overlap`;
+
+/** Keep the healthy default terminal output unchanged. */
+export function formatChunkingStatus(status?: ChunkingStatus): string | null {
+  if (!status) return null;
+  if (
+    chunkingPolicyKey(status.configured) === DEFAULT_CHUNKING_POLICY_KEY &&
+    status.pendingMirrors === 0 &&
+    status.state !== "mixed"
+  )
+    return null;
+  const applied = status.applied
+    ? formatParams(status.applied)
+    : status.state === "empty"
+      ? "none"
+      : "mixed";
+  const pending = status.pendingMirrors
+    ? `; ${status.pendingDocuments} documents / ${status.pendingMirrors} mirrors pending (run gno update)`
+    : "";
+  return `Chunking: configured ${formatParams(status.configured)}; applied ${applied}${pending}`;
+}

package/src/core/mutation-generations.ts

@@ -1,6 +1,7 @@
 /** Shared mutation detection for resident content and vector generations. */
 
 interface SyncMutationCounts {
+  rechunkedMirrors?: number;
   filesAdded?: number;
   filesUpdated?: number;
   filesMarkedInactive?: number;
@@ -11,6 +12,7 @@ interface SyncMutationCounts {
 
 export function hasContentMutation(result: SyncMutationCounts): boolean {
   return (
+    (result.rechunkedMirrors ?? 0) > 0 ||
     (result.filesAdded ?? result.totalFilesAdded ?? 0) > 0 ||
     (result.filesUpdated ?? result.totalFilesUpdated ?? 0) > 0 ||
     (result.filesMarkedInactive ?? 0) > 0 ||

package/src/ingestion/chunking.ts

@@ -0,0 +1,108 @@
+import type { ChunkingPolicyToken } from "../store/chunking";
+import type { ChunkInput, StorePort, StoreResult } from "../store/types";
+import type { ChunkerPort, SyncOptions } from "./types";
+
+import {
+  chunkingPolicyKey,
+  DEFAULT_CHUNKING_POLICY_KEY,
+  resolveChunkingParams,
+} from "../config/chunking";
+import { ChunkingPolicyConflictError } from "../store/chunking";
+
+function unwrapChunking<T>(result: StoreResult<T>): T {
+  if (result.ok) return result.value;
+  if (result.error.code === "CHUNKING_POLICY_CONFLICT") {
+    throw new ChunkingPolicyConflictError();
+  }
+  throw new Error(`Chunking failed: ${result.error.message}`);
+}
+
+/** One preparation per sync, including nested collection/path syncs. */
+export async function prepareChunking(
+  store: StorePort,
+  chunker: ChunkerPort,
+  options: SyncOptions
+): Promise<{ options: SyncOptions; rechunkedMirrors: number }> {
+  if (options.chunkingToken) return { options, rechunkedMirrors: 0 };
+  const params = resolveChunkingParams(options.chunking);
+  if (
+    !(
+      store.claimChunkingPolicy &&
+      store.listPendingChunkingMirrors &&
+      store.applyChunkLayout
+    )
+  ) {
+    if (chunkingPolicyKey(params) !== DEFAULT_CHUNKING_POLICY_KEY) {
+      throw new Error("This store does not support configurable chunking");
+    }
+    return { options, rechunkedMirrors: 0 };
+  }
+
+  const token = unwrapChunking(await store.claimChunkingPolicy(params));
+  let rechunkedMirrors = 0;
+  let afterHash = "";
+  for (;;) {
+    const mirrors = unwrapChunking(
+      await store.listPendingChunkingMirrors(token, afterHash)
+    );
+    if (mirrors.length === 0) break;
+    for (const mirror of mirrors) {
+      const markdown = unwrapChunking(
+        await store.getContent(mirror.mirrorHash)
+      );
+      if (markdown === null)
+        throw new Error("Cached mirror disappeared during rechunking");
+      const chunks: ChunkInput[] = chunker
+        .chunk(markdown, token.params, mirror.languageHint, mirror.sourcePath)
+        .map((chunk) => ({
+          seq: chunk.seq,
+          pos: chunk.pos,
+          text: chunk.text,
+          startLine: chunk.startLine,
+          endLine: chunk.endLine,
+          language: chunk.language ?? undefined,
+          tokenCount: chunk.tokenCount ?? undefined,
+        }));
+      unwrapChunking(
+        await store.applyChunkLayout(
+          mirror.mirrorHash,
+          chunks,
+          token,
+          mirror.sourcePath,
+          mirror.languageHint
+        )
+      );
+      rechunkedMirrors += 1;
+      afterHash = mirror.mirrorHash;
+    }
+  }
+  return {
+    options: { ...options, chunking: token.params, chunkingToken: token },
+    rechunkedMirrors,
+  };
+}
+
+/** Preserve the original store contract for default-only test/alternate ports. */
+export async function persistChunkLayout(
+  store: StorePort,
+  mirrorHash: string,
+  chunks: ChunkInput[],
+  token: ChunkingPolicyToken | undefined,
+  sourcePath: string,
+  languageHint?: string
+): Promise<void> {
+  if (token && store.applyChunkLayout) {
+    unwrapChunking(
+      await store.applyChunkLayout(
+        mirrorHash,
+        chunks,
+        token,
+        sourcePath,
+        languageHint
+      )
+    );
+    return;
+  }
+  unwrapChunking(await store.upsertChunks(mirrorHash, chunks));
+  unwrapChunking(await store.rebuildFtsForHash(mirrorHash));
+}