@gmickel/gno 2.2.1 → 2.3.0

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.0**. See [CHANGELOG.md](./CHANGELOG.md).
 
 <!-- /public-truth -->
 

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.0.zip.sha256

@@ -0,0 +1 @@
+9eea4e537f21515ea5de8e1eaea1710b5af0a1201a8b05db399ef0b6874f5f64  gno-browser-clipper-v2.3.0.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.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "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));
+}

package/src/ingestion/record-container.ts

@@ -23,6 +23,7 @@ import {
 } from "../core/change-diff";
 import { createEgressLineage } from "../core/egress-provenance";
 import { normalizeTag, validateTag } from "../core/tags";
+import { persistChunkLayout } from "./chunking";
 import { runRecordAdapter } from "./record-adapter";
 import { recordVirtualPath } from "./record-path";
 import { reconcileRecordSnapshot, type RecordSyncPlan } from "./record-sync";
@@ -397,7 +398,7 @@ const persistRecord = async (
     const chunks: ChunkInput[] = input.chunker
       .chunk(
         record.markdown,
-        DEFAULT_CHUNK_PARAMS,
+        input.options.chunkingToken?.params ?? DEFAULT_CHUNK_PARAMS,
         record.languageHint ?? input.collection.languageHint,
         virtualPath
       )
@@ -410,13 +411,13 @@ const persistRecord = async (
         language: chunk.language ?? undefined,
         tokenCount: chunk.tokenCount ?? undefined,
       }));
-    mustOk(
-      await input.store.upsertChunks(record.mirrorHash, chunks),
-      "upsertChunks"
-    );
-    mustOk(
-      await input.store.rebuildFtsForHash(record.mirrorHash),
-      "rebuildFtsForHash"
+    await persistChunkLayout(
+      input.store,
+      record.mirrorHash,
+      chunks,
+      input.options.chunkingToken,
+      virtualPath,
+      record.languageHint ?? input.collection.languageHint
     );
     mustOk(
       await input.store.setDocTags(document.id, categories, "frontmatter"),

package/src/ingestion/sync-options.ts

@@ -20,11 +20,13 @@ export function resolveContentTypeRules(
 
 export function withContentTypeRules(
   options: SyncOptions = {},
-  config?: Pick<Config, "contentTypes">
+  config?: Pick<Config, "contentTypes" | "chunking">
 ): SyncOptions {
   const rules = options.contentTypeRules ?? resolveContentTypeRules(config);
+  const chunking = options.chunking ?? config?.chunking;
   return {
     ...options,
+    ...(chunking ? { chunking } : {}),
     contentTypeRules: rules,
     contentTypeRulesFingerprint:
       options.contentTypeRulesFingerprint ??

package/src/ingestion/sync.ts

@@ -58,6 +58,7 @@ import {
 import { extractMemoryScopes } from "../core/memory-record";
 import { normalizeTag, validateTag } from "../core/tags";
 import { defaultChunker } from "./chunker";
+import { persistChunkLayout, prepareChunking } from "./chunking";
 import {
   extractHashtags,
   parseFrontmatter,
@@ -937,7 +938,7 @@ export class SyncService {
         // 9. Chunk content
         const chunks = this.chunker.chunk(
           artifact.markdown,
-          DEFAULT_CHUNK_PARAMS,
+          options.chunkingToken?.params ?? DEFAULT_CHUNK_PARAMS,
           artifact.languageHint ?? collection.languageHint,
           entry.relPath
         );
@@ -953,21 +954,15 @@ export class SyncService {
           tokenCount: c.tokenCount ?? undefined,
         }));
 
-        // 11. Upsert chunks - CHECKED
-        const chunksResult = await store.upsertChunks(
+        // 11-12. Apply chunks and lexical projection under the policy token.
+        await persistChunkLayout(
+          store,
           artifact.mirrorHash,
-          chunkInputs
+          chunkInputs,
+          options.chunkingToken,
+          entry.relPath,
+          artifact.languageHint ?? collection.languageHint
         );
-        mustOk(chunksResult, "upsertChunks", {
-          mirrorHash: artifact.mirrorHash,
-          chunkCount: chunkInputs.length,
-        });
-
-        // 12. Rebuild FTS for this hash - CHECKED
-        const ftsResult = await store.rebuildFtsForHash(artifact.mirrorHash);
-        mustOk(ftsResult, "rebuildFtsForHash", {
-          mirrorHash: artifact.mirrorHash,
-        });
 
         // 13. Extract and store tags from frontmatter and body hashtags
         // Always call setDocTags to clear removed tags on re-sync
@@ -1249,8 +1244,9 @@ export class SyncService {
     options: SyncOptions = {}
   ): Promise<CollectionSyncResult> {
     const startedAt = Date.now();
+    const prepared = await prepareChunking(store, this.chunker, options);
     const syncOptions: SyncOptions = {
-      ...options,
+      ...prepared.options,
       contentTypeRules: options.contentTypeRules ?? [],
       contentTypeRulesFingerprint:
         options.contentTypeRulesFingerprint ??
@@ -1511,13 +1507,18 @@ export class SyncService {
       syncOptions.projectTypedEdges === false
         ? []
         : await this.projectTypedEdges(store, syncOptions, projectionSourceIds);
-    return summarizePathResults(
-      collection.name,
-      results,
-      markedInactive,
-      startedAt,
-      errors
-    );
+    return {
+      ...summarizePathResults(
+        collection.name,
+        results,
+        markedInactive,
+        startedAt,
+        errors
+      ),
+      ...(prepared.rechunkedMirrors
+        ? { rechunkedMirrors: prepared.rechunkedMirrors }
+        : {}),
+    };
   }
 
   /**
@@ -1717,8 +1718,9 @@ export class SyncService {
     options: SyncOptions = {}
   ): Promise<CollectionSyncResult> {
     const startTime = Date.now();
+    const prepared = await prepareChunking(store, this.chunker, options);
     const syncOptions: SyncOptions = {
-      ...options,
+      ...prepared.options,
       contentTypeRules: options.contentTypeRules ?? [],
       contentTypeRulesFingerprint:
         options.contentTypeRulesFingerprint ??
@@ -2038,6 +2040,9 @@ export class SyncService {
 
     return {
       collection: collection.name,
+      ...(prepared.rechunkedMirrors
+        ? { rechunkedMirrors: prepared.rechunkedMirrors }
+        : {}),
       filesProcessed: entries.length + inventoryErrored,
       filesAdded: added,
       filesUpdated: updated,
@@ -2060,9 +2065,10 @@ export class SyncService {
     options: SyncOptions = {}
   ): Promise<SyncResult> {
     const startTime = Date.now();
+    const prepared = await prepareChunking(store, this.chunker, options);
     const results: CollectionSyncResult[] = [];
     const deferredProjectionOptions: SyncOptions = {
-      ...options,
+      ...prepared.options,
       projectTypedEdges: false,
     };
 
@@ -2094,6 +2100,9 @@ export class SyncService {
 
     return {
       collections: results,
+      ...(prepared.rechunkedMirrors
+        ? { rechunkedMirrors: prepared.rechunkedMirrors }
+        : {}),
       totalDurationMs: Date.now() - startTime,
       totalFilesProcessed: totals.processed,
       totalFilesAdded: totals.added,

package/src/ingestion/types.ts

@@ -12,8 +12,14 @@ import type {
   RecordAttachmentInventoryItem,
 } from "../converters/types";
 import type { EgressLineage } from "../core/egress-provenance";
+import type { ChunkingPolicyToken } from "../store/chunking";
 import type { DirectoryAvailabilityPort } from "./source-availability/types";
 
+import {
+  DEFAULT_CHUNKING_PARAMS,
+  type ChunkingParams,
+} from "../config/chunking";
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Walker Types
 // ─────────────────────────────────────────────────────────────────────────────
@@ -115,8 +121,7 @@ export interface ChunkParams {
 
 /** Default chunk params */
 export const DEFAULT_CHUNK_PARAMS: ChunkParams = {
-  maxTokens: 800,
-  overlapPercent: 0.15,
+  ...DEFAULT_CHUNKING_PARAMS,
 };
 
 /** Chunked output */
@@ -157,6 +162,10 @@ export interface ChunkerPort {
 
 /** Sync options */
 export interface SyncOptions {
+  /** Index-wide configured policy; omitted means the existing defaults. */
+  chunking?: Partial<ChunkingParams>;
+  /** Internal token passed from an outer sync; never a public CLI override. */
+  chunkingToken?: ChunkingPolicyToken;
   /** Run git pull before scanning */
   gitPull?: boolean;
   /** Run collection updateCmd before scanning */
@@ -266,6 +275,8 @@ export interface FileSyncResult {
 
 /** Collection sync summary */
 export interface CollectionSyncResult {
+  /** Cached layouts updated independently of source-refresh file counters. */
+  rechunkedMirrors?: number;
   collection: string;
   filesProcessed: number;
   filesAdded: number;
@@ -285,6 +296,8 @@ export interface CollectionSyncResult {
 
 /** Full sync summary */
 export interface SyncResult {
+  /** Cached layouts updated independently of source-refresh file counters. */
+  rechunkedMirrors?: number;
   collections: CollectionSyncResult[];
   totalDurationMs: number;
   totalFilesProcessed: number;

package/src/mcp/tools/status.ts

@@ -8,6 +8,7 @@ import type { IndexStatus } from "../../store/types";
 import type { ToolContext } from "../server";
 
 import { buildContentTypeBoostStatus } from "../../config/content-types";
+import { formatChunkingStatus } from "../../core/chunking-status";
 import { resolveModelUri } from "../../llm/registry";
 import { createStandaloneResidentStatus } from "../../serve/resident-status";
 import { runTool, type ToolResult } from "./index";
@@ -55,6 +56,9 @@ function formatStatus(status: IndexStatus): string {
     lines.push(`Embedding backlog: ${status.embeddingBacklog} chunks`);
   }
 
+  const chunking = formatChunkingStatus(status.chunking);
+  if (chunking) lines.push(chunking);
+
   if (status.recentErrors > 0) {
     lines.push(`Recent errors: ${status.recentErrors} (last 24h)`);
   }
@@ -79,6 +83,7 @@ export function handleStatus(
     async () => {
       const result = await ctx.store.getStatus({
         embedModel: resolveModelUri(ctx.config, "embed"),
+        chunking: ctx.config.chunking ?? {},
       });
       if (!result.ok) {
         throw new Error(result.error.message);

package/src/sdk/client.ts

@@ -1352,6 +1352,7 @@ class GnoClientImpl implements GnoClient {
     const status = unwrapStore(
       await this.store.getStatus({
         embedModel: resolveModelUri(this.config, "embed"),
+        chunking: this.config.chunking ?? {},
       })
     );
     return {

package/src/serve/status-model.ts

@@ -1,5 +1,6 @@
 import type { ContentTypeBoostStatus } from "../config/content-types";
 import type { ActivationStatus } from "../core/activation-status";
+import type { ChunkingStatus } from "../store/chunking";
 
 export type HealthCheckStatus = "ok" | "warn" | "error";
 
@@ -176,6 +177,7 @@ export interface BootstrapState {
 }
 
 export interface AppStatusResponse {
+  chunking?: ChunkingStatus;
   resident: ResidentStatus;
   indexName: string;
   configPath: string;

package/src/serve/status.ts

@@ -654,6 +654,7 @@ export async function buildAppStatus(
 ): Promise<AppStatusResponse> {
   const result = await ctx.store.getStatus({
     embedModel: resolveModelUri(ctx.config, "embed"),
+    chunking: ctx.config.chunking ?? {},
   });
   if (!result.ok) {
     throw result.error;
@@ -733,6 +734,7 @@ export async function buildAppStatus(
     totalDocuments: status.activeDocuments,
     totalChunks: status.totalChunks,
     embeddingBacklog: status.embeddingBacklog,
+    chunking: status.chunking,
     lastUpdated: status.lastUpdatedAt,
     recentErrors: status.recentErrors,
     healthy: checks.every((check) => check.status === "ok"),

package/src/store/chunking.ts

@@ -0,0 +1,31 @@
+import type { ChunkingParams } from "../config/chunking";
+
+export interface ChunkingPolicyToken {
+  params: ChunkingParams;
+  generation: number;
+}
+
+export interface PendingChunkingMirror {
+  mirrorHash: string;
+  sourcePath: string;
+  languageHint?: string;
+}
+
+export interface ChunkingStatus {
+  configured: ChunkingParams;
+  applied: ChunkingParams | null;
+  state: "empty" | "legacy-default" | "current" | "pending" | "mixed";
+  pendingDocuments: number;
+  pendingMirrors: number;
+}
+
+export class ChunkingPolicyConflictError extends Error {
+  readonly code = "CHUNKING_POLICY_CONFLICT";
+
+  constructor() {
+    super(
+      "CHUNKING_POLICY_CONFLICT: The index chunking policy changed. Reopen the client or restart the resident runtime with the intended configuration."
+    );
+    this.name = "ChunkingPolicyConflictError";
+  }
+}

package/src/store/sqlite/adapter.ts

@@ -113,6 +113,11 @@ import type {
 import type { SqliteDbProvider } from "./types";
 
 import { buildUri, deriveDocid, stripUriIndex } from "../../app/constants";
+import {
+  DEFAULT_CHUNKING_PARAMS,
+  resolveChunkingParams,
+  type ChunkingParams,
+} from "../../config/chunking";
 import {
   type Collection,
   type Context,
@@ -140,6 +145,11 @@ import {
   parseActivationReceipt,
   serializeActivationReceipt,
 } from "../activation-receipts";
+import {
+  ChunkingPolicyConflictError,
+  type ChunkingPolicyToken,
+  type PendingChunkingMirror,
+} from "../chunking";
 import { getSchemaVersion, migrations, runMigrations } from "../migrations";
 import { err, ok } from "../types";
 import { getStoredEmbeddingFingerprint } from "../vector/freshness";
@@ -164,6 +174,15 @@ import {
   purgeDocumentChanges as purgeStoredDocumentChanges,
   snapshotDocumentChange,
 } from "./change-journal-store";
+import {
+  assertChunkingTarget,
+  claimChunkingTarget,
+  getChunkingStatus,
+  markChunkingApplied,
+  pendingChunkingMirrors,
+  pruneChunkingMetadata,
+  readChunkingTarget,
+} from "./chunking-policy";
 import {
   appendEgressAuditReceipt as appendStoredEgressAuditReceipt,
   appendEgressAuditReceiptWithRetention as appendStoredEgressAuditReceiptWithRetention,
@@ -535,6 +554,7 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
   private shutdownFenced = false;
   private shutdownDeadline?: number;
   private contextGeneration = 0;
+  private chunkingGeneration = 0;
 
   // ─────────────────────────────────────────────────────────────────────────
   // Lifecycle
@@ -603,6 +623,7 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
         return result;
       }
 
+      this.chunkingGeneration = readChunkingTarget(this.db).generation;
       this.contextGeneration += 1;
       return result;
     } catch (cause) {
@@ -2631,12 +2652,20 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
 
   async upsertChunks(
     mirrorHash: string,
-    chunks: ChunkInput[]
+    chunks: ChunkInput[],
+    policy?: ChunkingPolicyToken
   ): Promise<StoreResult<void>> {
     try {
       const db = this.ensureOpen();
 
       const transaction = db.transaction(() => {
+        assertChunkingTarget(
+          db,
+          policy ?? {
+            params: DEFAULT_CHUNKING_PARAMS,
+            generation: this.chunkingGeneration,
+          }
+        );
         // Retain stable rows: DELETE cascades erase valid legacy vectors even
         // when duplicate ingestion produces exactly the same embedding input.
         const nextBySequence = new Map(
@@ -2693,13 +2722,83 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
       return ok(undefined);
     } catch (cause) {
       return err(
-        "QUERY_FAILED",
+        cause instanceof ChunkingPolicyConflictError
+          ? cause.code
+          : "QUERY_FAILED",
         cause instanceof Error ? cause.message : "Failed to upsert chunks",
         cause
       );
     }
   }
 
+  async claimChunkingPolicy(
+    input: ChunkingParams
+  ): Promise<StoreResult<ChunkingPolicyToken>> {
+    const params = resolveChunkingParams(input);
+    const result = await this.withTransaction(async () =>
+      claimChunkingTarget(this.ensureOpen(), this.chunkingGeneration, params)
+    );
+    if (result.ok) this.chunkingGeneration = result.value.generation;
+    else if (result.error.cause instanceof ChunkingPolicyConflictError) {
+      return err(
+        "CHUNKING_POLICY_CONFLICT",
+        result.error.message,
+        result.error.cause
+      );
+    }
+    return result;
+  }
+
+  async listPendingChunkingMirrors(
+    policy: ChunkingPolicyToken,
+    afterHash = ""
+  ): Promise<StoreResult<PendingChunkingMirror[]>> {
+    try {
+      return ok(pendingChunkingMirrors(this.ensureOpen(), policy, afterHash));
+    } catch (cause) {
+      return err(
+        cause instanceof ChunkingPolicyConflictError
+          ? cause.code
+          : "QUERY_FAILED",
+        cause instanceof Error
+          ? cause.message
+          : "Failed to list pending chunk layouts",
+        cause
+      );
+    }
+  }
+
+  async applyChunkLayout(
+    mirrorHash: string,
+    chunks: ChunkInput[],
+    policy: ChunkingPolicyToken,
+    sourcePath: string,
+    languageHint?: string
+  ): Promise<StoreResult<void>> {
+    const result = await this.withTransaction(async () => {
+      const db = this.ensureOpen();
+      assertChunkingTarget(db, policy);
+      const applied = await this.upsertChunks(mirrorHash, chunks, policy);
+      if (!applied.ok)
+        throw applied.error.cause ?? new Error(applied.error.message);
+      const indexed = await this.rebuildFtsForHash(mirrorHash);
+      if (!indexed.ok)
+        throw indexed.error.cause ?? new Error(indexed.error.message);
+      markChunkingApplied(db, mirrorHash, policy, sourcePath, languageHint);
+    });
+    if (
+      !result.ok &&
+      result.error.cause instanceof ChunkingPolicyConflictError
+    ) {
+      return err(
+        "CHUNKING_POLICY_CONFLICT",
+        result.error.message,
+        result.error.cause
+      );
+    }
+    return result;
+  }
+
   async getChunks(mirrorHash: string): Promise<StoreResult<ChunkRow[]>> {
     try {
       const db = this.ensureOpen();
@@ -5690,6 +5789,7 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
   async getStatus(options?: {
     embedModel?: string;
     embedFingerprint?: string;
+    chunking?: Partial<ChunkingParams>;
   }): Promise<StoreResult<IndexStatus>> {
     try {
       const db = this.ensureOpen();
@@ -5884,6 +5984,7 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
         activeDocuments: totalsRow?.active ?? 0,
         totalChunks: chunkCount,
         embeddingBacklog: variantStatus?.backlog ?? backlogRow?.count ?? 0,
+        chunking: getChunkingStatus(db, options?.chunking),
         recentErrors,
         lastUpdatedAt: lastUpdatedRow?.last_updated ?? null,
         healthy,
@@ -5968,6 +6069,7 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
           )
         `);
         orphanedContent = contentResult.changes;
+        pruneChunkingMetadata(db);
 
         // Delete chunks for deleted content
         const chunksResult = db.run(`

package/src/store/sqlite/chunking-policy.ts

@@ -0,0 +1,212 @@
+import type { Database } from "bun:sqlite";
+
+import type {
+  ChunkingPolicyToken,
+  ChunkingStatus,
+  PendingChunkingMirror,
+} from "../chunking";
+
+import {
+  ChunkingConfigSchema,
+  chunkingPolicyKey,
+  DEFAULT_CHUNKING_PARAMS,
+  DEFAULT_CHUNKING_POLICY_KEY,
+  resolveChunkingParams,
+  type ChunkingParams,
+} from "../../config/chunking";
+import { ChunkingPolicyConflictError } from "../chunking";
+
+const TARGET_KEY = "chunking_policy_v1";
+const LAYOUT_PREFIX = "chunking_mirror_v1:";
+
+export function readChunkingTarget(db: Database): ChunkingPolicyToken {
+  const row = db
+    .query<{ value: string }, [string]>(
+      "SELECT value FROM schema_meta WHERE key = ?"
+    )
+    .get(TARGET_KEY);
+  if (!row) return { params: { ...DEFAULT_CHUNKING_PARAMS }, generation: 0 };
+  const parsed: unknown = JSON.parse(row.value);
+  if (
+    !parsed ||
+    typeof parsed !== "object" ||
+    !("generation" in parsed) ||
+    !Number.isSafeInteger(parsed.generation) ||
+    typeof parsed.generation !== "number" ||
+    parsed.generation < 1 ||
+    !("params" in parsed)
+  ) {
+    throw new Error("Invalid stored chunking policy");
+  }
+  return {
+    params: ChunkingConfigSchema.parse(parsed.params),
+    generation: parsed.generation,
+  };
+}
+
+export function assertChunkingTarget(
+  db: Database,
+  token: ChunkingPolicyToken
+): void {
+  const current = readChunkingTarget(db);
+  if (
+    current.generation !== token.generation ||
+    chunkingPolicyKey(current.params) !== chunkingPolicyKey(token.params)
+  ) {
+    throw new ChunkingPolicyConflictError();
+  }
+}
+
+/** Called while the adapter holds its transaction writer. */
+export function claimChunkingTarget(
+  db: Database,
+  observedGeneration: number,
+  params: ChunkingParams
+): ChunkingPolicyToken {
+  const current = readChunkingTarget(db);
+  if (current.generation !== observedGeneration) {
+    throw new ChunkingPolicyConflictError();
+  }
+  if (chunkingPolicyKey(current.params) === chunkingPolicyKey(params)) {
+    return current;
+  }
+  const generation = current.generation + 1;
+  if (!Number.isSafeInteger(generation)) {
+    throw new Error("Chunking policy generation exhausted");
+  }
+  const target = { params, generation };
+  db.run(
+    "INSERT INTO schema_meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+    [TARGET_KEY, JSON.stringify(target)]
+  );
+  return target;
+}
+
+/** Keyset paging bounds memory even for a large index. */
+export function pendingChunkingMirrors(
+  db: Database,
+  token: ChunkingPolicyToken,
+  afterHash: string
+): PendingChunkingMirror[] {
+  assertChunkingTarget(db, token);
+  // No policy has ever changed, so every legacy/default layout is current.
+  if (token.generation === 0) return [];
+  return db
+    .query<
+      {
+        mirror_hash: string;
+        source_path: string;
+        language_hint: string | null;
+      },
+      [string, string, string, string]
+    >(
+      `SELECT c.mirror_hash,
+         COALESCE(json_extract(m.value, '$.sourcePath'), d.rel_path) AS source_path,
+         CASE WHEN m.value IS NOT NULL
+           THEN json_extract(m.value, '$.languageHint') ELSE d.language_hint END AS language_hint
+       FROM content c JOIN documents d ON d.id = (
+         SELECT id FROM documents
+         WHERE mirror_hash = c.mirror_hash AND active = 1
+         ORDER BY collection, rel_path, id LIMIT 1
+       )
+       LEFT JOIN schema_meta m ON m.key = ? || c.mirror_hash
+       WHERE c.mirror_hash > ?
+         AND COALESCE(json_extract(m.value, '$.params'), ?) <> ?
+       ORDER BY c.mirror_hash LIMIT 64`
+    )
+    .all(
+      LAYOUT_PREFIX,
+      afterHash,
+      DEFAULT_CHUNKING_POLICY_KEY,
+      chunkingPolicyKey(token.params)
+    )
+    .map((row) => ({
+      mirrorHash: row.mirror_hash,
+      sourcePath: row.source_path,
+      languageHint: row.language_hint ?? undefined,
+    }));
+}
+
+export function markChunkingApplied(
+  db: Database,
+  mirrorHash: string,
+  token: ChunkingPolicyToken,
+  sourcePath: string,
+  languageHint?: string
+): void {
+  const updated = db.run(
+    `INSERT INTO schema_meta (key, value)
+     SELECT ?, ? WHERE EXISTS (SELECT 1 FROM content WHERE mirror_hash = ?)
+     ON CONFLICT(key) DO UPDATE SET value = excluded.value`,
+    [
+      `${LAYOUT_PREFIX}${mirrorHash}`,
+      JSON.stringify({ params: token.params, sourcePath, languageHint }),
+      mirrorHash,
+    ]
+  );
+  if (updated.changes !== 1)
+    throw new Error("Cannot mark a missing cached mirror applied");
+}
+
+export function getChunkingStatus(
+  db: Database,
+  configured?: Partial<ChunkingParams>
+): ChunkingStatus {
+  const params = resolveChunkingParams(
+    configured ?? readChunkingTarget(db).params
+  );
+  const key = chunkingPolicyKey(params);
+  const groups = db
+    .query<
+      { policy: string | null; documents: number; mirrors: number },
+      [string]
+    >(
+      `SELECT json_extract(m.value, '$.params') AS policy, COUNT(*) AS documents,
+         COUNT(DISTINCT c.mirror_hash) AS mirrors
+       FROM content c JOIN documents d ON d.mirror_hash = c.mirror_hash
+       LEFT JOIN schema_meta m ON m.key = ? || c.mirror_hash
+       WHERE d.active = 1 GROUP BY policy`
+    )
+    .all(LAYOUT_PREFIX);
+  const appliedPolicies = new Map<string, ChunkingParams>();
+  let pendingDocuments = 0;
+  let pendingMirrors = 0;
+  for (const group of groups) {
+    const applied = group.policy
+      ? ChunkingConfigSchema.parse(JSON.parse(group.policy))
+      : { ...DEFAULT_CHUNKING_PARAMS };
+    const appliedKey = chunkingPolicyKey(applied);
+    appliedPolicies.set(appliedKey, applied);
+    if (appliedKey !== key) {
+      pendingDocuments += group.documents;
+      pendingMirrors += group.mirrors;
+    }
+  }
+  let state: ChunkingStatus["state"] = "current";
+  if (groups.length === 0) state = "empty";
+  else if (appliedPolicies.size > 1) state = "mixed";
+  else if (pendingMirrors > 0) state = "pending";
+  else if (groups.every((group) => group.policy === null))
+    state = "legacy-default";
+
+  return {
+    configured: params,
+    applied:
+      appliedPolicies.size === 1
+        ? (appliedPolicies.values().next().value ?? null)
+        : null,
+    state,
+    pendingDocuments,
+    pendingMirrors,
+  };
+}
+
+export function pruneChunkingMetadata(db: Database): void {
+  db.run(
+    `DELETE FROM schema_meta WHERE key GLOB ?
+       AND NOT EXISTS (
+         SELECT 1 FROM content WHERE mirror_hash = substr(schema_meta.key, ?)
+       )`,
+    [`${LAYOUT_PREFIX}*`, LAYOUT_PREFIX.length + 1]
+  );
+}

package/src/store/types.ts

@@ -5,6 +5,7 @@
  * @module src/store/types
  */
 
+import type { ChunkingParams } from "../config/chunking";
 import type {
   Collection,
   Context,
@@ -19,6 +20,11 @@ import type {
   FileRefactorRecoveryReceipt,
   FileRefactorRecoveryReceiptDraft,
 } from "../core/file-refactor-journal";
+import type {
+  ChunkingPolicyToken,
+  ChunkingStatus,
+  PendingChunkingMirror,
+} from "./chunking";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Error Types
@@ -42,6 +48,7 @@ export type StoreErrorCode =
   | "QUERY_FAILED"
   | "TRANSACTION_FAILED"
   | "INVALID_INPUT"
+  | "CHUNKING_POLICY_CONFLICT"
   | "IO_ERROR"
   | "INTERNAL"
   | "EGRESS_DENIED"
@@ -806,6 +813,8 @@ export interface IndexStatus {
   totalChunks: number;
   /** Chunks without embeddings */
   embeddingBacklog: number;
+  /** Configuration and applied cached layouts; separate from source freshness. */
+  chunking?: ChunkingStatus;
   /** Recent ingest errors (last 24h) */
   recentErrors: number;
   /** Last successful update timestamp (ISO 8601) */
@@ -2036,7 +2045,28 @@ export interface StorePort {
    */
   upsertChunks(
     mirrorHash: string,
-    chunks: ChunkInput[]
+    chunks: ChunkInput[],
+    policy?: ChunkingPolicyToken
+  ): Promise<StoreResult<void>>;
+
+  /** Claim an index-wide policy against the generation observed at open. */
+  claimChunkingPolicy?(
+    params: ChunkingParams
+  ): Promise<StoreResult<ChunkingPolicyToken>>;
+
+  /** Page cached mirrors whose applied policy differs from the claimed target. */
+  listPendingChunkingMirrors?(
+    policy: ChunkingPolicyToken,
+    afterHash?: string
+  ): Promise<StoreResult<PendingChunkingMirror[]>>;
+
+  /** Atomically replace a layout, refresh FTS and mark its actual policy. */
+  applyChunkLayout?(
+    mirrorHash: string,
+    chunks: ChunkInput[],
+    policy: ChunkingPolicyToken,
+    sourcePath: string,
+    languageHint?: string
   ): Promise<StoreResult<void>>;
 
   /**
@@ -2288,6 +2318,7 @@ export interface StorePort {
   getStatus(options?: {
     embedModel?: string;
     embedFingerprint?: string;
+    chunking?: Partial<ChunkingParams>;
   }): Promise<StoreResult<IndexStatus>>;
 
   // ─────────────────────────────────────────────────────────────────────────

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

@@ -1 +0,0 @@
-cf4c351a255144b6f65dd25b71096effd05c0ea93a0691fc83ee49a3166a37c2  gno-browser-clipper-v2.2.1.zip