agentfootprint 8.9.0 → 8.11.0

package/AGENTS.md

@@ -152,6 +152,8 @@ agent.rag(docs);
 await agent.run({ message: 'How long do refunds take?' });
 ```
 
+**Building the index** (8.10.0) is `agentfootprint/rag`: `indexFolder('./docs', { to: store, embedder })`, or the `loadDocuments` → `splitDocuments` → `indexCorpus` pieces, or `npx agentfootprint-index ./docs --to ./corpus.db`. Loaders for text/Markdown/HTML (zero-dep) and PDF (lazy `unpdf`, per-page text so citations can name a page). Re-running embeds only what changed. `defineRAG` stays on the MAIN barrel — it is run-time wiring; that door is index time.
+
 `defineRAG` runs on `defineMemory({ type: SEMANTIC, strategy: TOP_K })`. Same machinery, three deliberate differences: a corpus is **read-only** (it never stores the conversation), it reads under its **own namespace** rather than the run's identity, and its chunks render as **citable `<source>` blocks**. For conversation memory alongside a corpus, register both — `.rag(defineRAG(...))` and `.memory(defineMemory(...))`, each with its own store.
 
 **Why did the agent read this passage?** `agentfootprint.memory.retrieved` carries every candidate with its score — including the ones that were rejected and why. `agentfootprint.memory.attached` fires per chunk that reached the prompt. `agentfootprint.context.injected` reports `source: 'rag'` with that chunk's `retrievalScore` / `rankPosition` / `threshold`. The whole record is on root state as `retrievalEvidence_<id>`, where a backward slice can reach it.

package/CLAUDE.md

@@ -16,6 +16,7 @@ Entry points (package.json exports): `.` core API · `/observe` ALL observabilit
 | adapters/ | hexagonal ports (types.ts = ALL port interfaces) + vendor impls (llm/, memory/, identity/, observability/). memory/sqliteVector.ts (8.9.0) = the only FULL MemoryStore we ship with `search` besides InMemoryStore — exact cosine over a resident Float32Array matrix, hydrated per namespace on first search and dropped on any write to it |
 | recorders/core/ | bridges footprintjs events → typed EventDispatcher (ContextRecorder, EmitBridge, typedEmit) — auto-attached by Agent.createExecutor; most factories also exported via `/observe` for manual wiring (EmitBridge itself stays internal) |
 | recorders/observability/ | consumer recorders over the typed stream (RunStepRecorder, FlowchartRecorder, Status, Trace replay) + `recordRun` — THE producer of a recording `{snapshot, events, structure}` (the shape lens's `observeRecording` consumes; `structure` = `getSpec().buildTimeStructure`, which no snapshot carries). Anything that saves a run goes through it |
+| rag/ | (8.10.0, door `/rag`) index-TIME: `DocumentLoader` adapters (text/markdown/html zero-dep, pdf via lazy `unpdf`) + `Splitter` factories + `indexCorpus` — a REAL footprintjs chart whose commit log IS the indexing report. `defineRAG` deliberately stays on the MAIN barrel (run-time wiring); this door is the half that runs once, before any agent exists |
 | lib/ | first-party sub-libraries: injection-engine/, context-bisect/ (localizeContextBug, toBacktrackTrace + sliceToBacktrackTrace — the atui board serializers), influence-core/, trace-toolpack/ (selfExplain; 6 tools incl. variable-first `backtrack(variable, element?)`), context-ledger/ (which pieces EARNED their tokens — post-run offers/uses/outcomes bookkeeping + demote-never-starve gates `ledgerToolGate`/`ledgerEntryScorer`/`ledgerGated`; grouped-mode folds sf-llm-call inner logs, unmeterable runs → undefined; /observe), mcp/, rag/, tool-lint/ |
 | memory/ | store/ (MemoryStore port) + pipeline presets + stages + beats/facts + causal/ (dev-only, TOP_K+search()-only) + wire/mountMemoryPipeline + retrieval/ (8.8.0: the `RetrievalStrategy` seam + `RetrievalEvidence`, the record a retrieval leaves — `topK()` is what every earlier release did unnamed) |
 | events/ | EventDispatcher (wildcard subs), registry (EVENT_NAMES, AgentfootprintEventMap), payloads |
@@ -39,6 +40,8 @@ Traps: `src/observability/` holds the finder IMPLEMENTATIONS (canonical home; `d
 - **New typed event (3-step)**: payload interface in events/payloads.ts + entry in `AgentfootprintEventMap` (registry.ts:198) + append to `ALL_EVENT_TYPES` (registry.ts:488, count-asserted by tests). New DOMAIN also needs a bridge attach in Agent.createExecutor or emits never reach the dispatcher — AND a hand-edit to `DomainWildcard` (dispatcher.ts:67-82; already missing validation/credential/reliability).
 - **Strategy (vendor sink)**: shapes in strategies/types.ts (Observability :130, Cost :169, LiveStatus :201, Lens :234); attach via `agent.enable.*` or `registerObservabilityStrategy` (strategies/registry.ts). New vendor = export from observability-providers.ts, NOT a new subpath.
 - **Memory store**: implement `MemoryStore` (memory/store/types.ts:113; `search?` REQUIRED for causal memory); pass to `defineMemory({store})`. Memory TYPE/STRATEGY unions are CLOSED (define.types.ts:57/74 — new one edits defineMemory dispatch + a pipeline builder).
+- **Document loader** (8.10.0): implement `DocumentLoader` (rag/types.ts) — `{name, extensions, load}`. `loadDocuments` routes by extension, caller-supplied loaders FIRST, so overriding a built-in is passing yours ahead of it rather than editing `DEFAULT_LOADERS`. A loader MUST NOT rewrite text after offsets are conceivable: the HTML stripper replaces tags with EQUAL-LENGTH whitespace for exactly this reason.
+- **Splitter** (8.10.0): implement `Splitter` (`{name, split(doc) → SplitPiece[]}`), a factory function like the window/retrieval families. THE invariant — `doc.text.slice(charStart, charEnd) === piece.text` — is VERIFIED by `splitDocuments`, not trusted. All offset arithmetic lives once in `splitters/shared.ts`; a strategy that does its own is how the invariant breaks.
 - **Durable store** (8.9.0): `sqliteVectorStore` follows `hosting/sqliteSessions` line for line — lazy `node:sqlite`, WAL read-back on `journalMode`, STRICT tables, schema-identity + schema-version refusals, `':memory:'` refused. TWO things it adds that have no precedent there: `putMany`/`putIfVersion`/`forget` wrap in a transaction (sqliteSessions has none), and the EMBEDDER FINGERPRINT (`'<id>@<dims>'`, one per namespace in `af_index_meta`) is refused at write AND query. `SqliteUnavailableError` is now ONE class in `lib/sqliteUnavailable.ts` re-exported by both doors — a second class of that name is a duplicate type the build refuses.
 - **Retrieval rule** (8.8.0): implement `RetrievalStrategy` (memory/retrieval/types.ts) — `select(pool) → verdict[]`, one verdict per candidate, order preserved; it never touches the store and never embeds. Pass as `defineRAG({retrieval})`. `topK()` is the only shipped one; rerank/MMR are named-but-deferred adapters behind the same interface. `TopKStrategy` is a UNION whose arms exclude (`{topK,threshold}` vs `{retrieval}`) — refused in the type AND at runtime, because two spellings of one rule can disagree.
 - **Injection/skill**: `Injection = {id, flavor, trigger, inject}` (lib/injection-engine/types.ts:161); trigger is a closed 4-variant union (:30 — new kind edits evaluator.ts:40-74 switch). Factories defineSkill etc.; skill graph via `skillGraph()` (skillGraph.ts:392) with pluggable `EntryScorer` (entryScorer.ts:64). `SkillGraphConfig` is a UNION (flat arm `start`/`steps` vs tree arm) — the contradictions it encodes are ALSO refused at build (`.tree()` + `.entry()`/`.route()`, a non-leaf in `skills[]` under a tree, two skills claiming one id, a second `.skillGraph()` on one agent).
@@ -51,6 +54,7 @@ Traps: `src/observability/` holds the finder IMPLEMENTATIONS (canonical home; `d
 ## Change-impact map
 - **conventions.ts** (STAGE_IDS/SUBFLOW_IDS/INJECTION_KEYS) → chart builders that mount by id, ContextRecorder slot attribution, localizer loop-head detection (lib/context-bisect/trajectory.ts:17-33), `stageRole`/`milestoneFor` (Lens contract), BoundaryRecorder. Renaming an id is the whole blast radius.
 - **BoundaryRecorder wiring is THREE connections, all at record time**: `runner.attach` (boundaries), `.subscribe(runner)` (what's inside them), `{getCommitCount}` (where each sits on the commit axis). The third fails SILENTLY — every event stamps `commitIdxBefore: 0`, `boundaryIndex` stays empty by design, and an offline step strip has nothing to place. Unrecoverable after the run (the commit log never records WHEN a boundary was crossed). Wired by `attachFlowchart` (which `enable.flowchart`/`enable.localObservability` both go through) and by `recordRun`; a new entry point must pass all three.
+- **indexCorpus fan-out** (8.10.0) → `maxBranches` on `addParallelForEach` TRUNCATES surplus items rather than queueing them, so the chart fans out over a WINDOW (`take-window` → `embed` → `tally-window` → `more-batches-decider` `{loopTo: 'take-window'}`) that can never exceed the ceiling. A single fan-out over all batches would silently index only the first `maxConcurrentBatches` — pinned by the 12-batches-through-a-window-of-2 test. `embedded` is summed from each branch's `written`, never from the plan's queue, and the fan-out is `failFast: true` because a half-indexed corpus keeps answering.
 - **Embedder fingerprint** (8.9.0) → `Embedder.id` (optional; every shipped embedder sets one, and NONE include dims — the store appends `@<dims>` itself, so an id carrying its own size double-stamps) + `indexDocuments` defaulting `embedderId` to it + `SqliteVectorStore.reconcileFingerprint` (the only comparison site). Rule: dimensions ALWAYS decide, model ids decide only when BOTH sides named themselves — refusing on an absent name would block the majority of callers who never pass `embedderId`.
 - **Retrieval record** (8.8.0) → FOUR stages write one object in sequence: `loadRelevant` (candidates+scores+threshold verdicts) → `pickByBudget` (re-marks admitted→over-budget/over-max-entries) → `formatDefault` (`promptFragment` + `promptPosition`) → the read mount's outputMapper lifts it to root as `retrievalEvidence_<id>`. `memoryRecallInjections` then splits ONE recall into one ActiveInjection PER CHUNK — guarded by a byte-equality check (`fragments.join('\n\n') === systemContent`) that falls back to the single injection rather than change the prompt. `rank` (score order) and `promptPosition` (picker order) are DIFFERENT and both load-bearing: joining fragments in rank order reproduces the right bytes in a sequence the model never saw.
 - **AgentState** → all 8 stages/ files, both builders' mappers, memory-wire STRING-TYPED keys ('runIdentity'/'turnNumber'/… buildAgentChart.ts:177-180 — not refactor-safe), finalizeResult's `reliabilityFail*`/`policyHalt*` reads (rename silently kills the typed errors).

package/README.md

@@ -18,11 +18,11 @@
 
 <p align="center">
   <a href="https://footprintjs.github.io/agentThinkingUI/">
-    <img src="docs/assets/hero-atui.png" alt="An agent run replayed in AgentThinkingUI — the LLM 'brain' calls the Flight-search tool, the step inspector shows the tool's raw output and the brain's reasoning about it, and the timeline scrubs every step of the run." width="100%">
+    <img src="docs/assets/hero-atui.png" alt="An agent run replayed in Story Lens — the LLM 'brain' calls the Flight-search tool, the step inspector shows the tool's raw output and the brain's reasoning about it, and the timeline scrubs every step of the run." width="100%">
   </a>
 </p>
 <p align="center">
-  <sub>A real run, replayed — rendered with <a href="https://github.com/footprintjs/agentThinkingUI"><b>AgentThinkingUI</b></a> (<code>npm i agentthinkingui</code>). Every frame is generated from the run's own trace; <a href="https://footprintjs.github.io/agentThinkingUI/">▶ watch it live</a>.</sub>
+  <sub>A real run, replayed — rendered with <a href="https://github.com/footprintjs/agentThinkingUI"><b>Story Lens</b></a> (<code>npm i agentthinkingui</code>). Every frame is generated from the run's own trace; <a href="https://footprintjs.github.io/agentThinkingUI/">▶ watch it live</a>.</sub>
 </p>
 
 <p align="center">
@@ -139,11 +139,12 @@ const agent = Agent.create({ provider, model })
     id: 'refund-policy',
     prompt: 'Never promise a refund before checking the policy tool.',
   }))
-  .skill(defineSkill({                  // guidance + tools — unlocks when the LLM asks
+  .skill(defineSkill({                  // guidance the LLM loads when it asks
     id: 'billing',
     description: 'Use for refunds, charges, billing questions.',
     body: 'When handling billing: confirm identity first, then…',
     tools: [refundTool],
+    autoActivate: 'currentSkill',       // ...and scope its tools to that window too
   }))
   .build();
 ```
@@ -277,7 +278,7 @@ confident, wrong #1. Guides: [ranking-confidence](docs/guides/ranking-confidence
 [missing-context](docs/guides/missing-context.md).
 
 **The same walk, visual.** `toBacktrackTrace()` serializes the report into
-[AgentThinkingUI](https://github.com/footprintjs/agentThinkingUI)'s `<BacktrackView>`
+[Story Lens](https://github.com/footprintjs/agentThinkingUI)'s `<BacktrackView>`
 — the "why?" board, triggerable from any decision point (final answer, a mid-loop tool
 choice, a deterministic `decide()` rule):
 
@@ -368,7 +369,7 @@ That's the whole model: `Injection = slot × trigger × cache`.
 | `llm-activated` | runtime — agent-driven | LLM calls `read_skill('id')` | `.skill(defineSkill({ id: 'refund-policy', description, body, viaToolName: 'read_skill' }))` | `system` (body) + `tools` |
 
 > [!NOTE]
-> The "Illustration" column shows the shape of each flavor — the typed builder methods (`.steering` / `.instruction` / `.skill` / `.fact` / `.rag`) take an `Injection` (or `MemoryDefinition` for `.rag`) produced by the matching `defineSteering` / `defineInstruction` / `defineSkill` / `defineFact` / `defineRAG` factory. A `Skill` targets more than one slot at once: `tools` (the schemas it unlocks) and `system` (its body — or, with `surfaceMode: 'tool-only'`, the `read_skill` result instead). The `messages` slot both projects the conversation and accepts delivery: `slot: 'messages'` (with a `role` you name) appends to the window itself, subject to what the attached provider carries inside `messages` and to a sequence rule that defers rather than reorders.
+> The "Illustration" column shows the shape of each flavor — the typed builder methods (`.steering` / `.instruction` / `.skill` / `.fact` / `.rag`) take an `Injection` (or `MemoryDefinition` for `.rag`) produced by the matching `defineSteering` / `defineInstruction` / `defineSkill` / `defineFact` / `defineRAG` factory. A `Skill` targets more than one slot at once: `tools` (the schemas it contributes — registered up front and visible from iteration 1 unless the Skill sets `autoActivate: 'currentSkill'`, which scopes them to the iterations where it is active) and `system` (its body — or, with `surfaceMode: 'tool-only'`, the `read_skill` result instead). The `messages` slot both projects the conversation and accepts delivery: `slot: 'messages'` (with a `role` you name) appends to the window itself, subject to what the attached provider carries inside `messages` and to a sequence rule that defers rather than reorders.
 
 **3 slots × 4 triggers × N flavors = the entire context-engineering surface.**
 
@@ -657,10 +658,10 @@ There is deliberately no list of "watch moments" to go with `.act()`'s five. A r
 ## 🐛 Debug — see what your agent did
 
 <p align="center">
-  <img src="docs/assets/lens-run.png" alt="A real agent run in the Lens: the conversation (with live PII redaction), the executed path lit on the merge-tree flowchart, the WHAT-HAPPENED timeline of every iteration/context/LLM turn/route, run stats, and the step inspector — all generated from the run's own trace." width="100%">
+  <img src="docs/assets/lens-run.png" alt="A real agent run in Why Lens: the conversation (with live PII redaction), the executed path lit on the merge-tree flowchart, the WHAT-HAPPENED timeline of every iteration/context/LLM turn/route, run stats, and the step inspector — all generated from the run's own trace." width="100%">
 </p>
 <p align="center">
-  <sub>One real run, fully explained — the <a href="https://github.com/footprintjs/agentfootprint-lens"><b>Lens</b></a> (<code>npm i agentfootprint-lens</code>): conversation · executed path · per-step timeline · stats, every pixel from the trace.</sub>
+  <sub>One real run, fully explained — <a href="https://github.com/footprintjs/agentfootprint-lens"><b>Why Lens</b></a> (<code>npm i agentfootprint-lens</code>): conversation · executed path · per-step timeline · stats, every pixel from the trace.</sub>
 </p>
 
 Because we own the loop, every decision and execution is captured during traversal — not bolted on. The default capture is the **causal trace**: every stage, read, write, and decision evidence as a JSON-portable, scrubbable, queryable, exportable artifact — and every LLM call backtracks to four typed answers: **what** was injected, **who** triggered it (which rule), **when** it fired, **how** it landed (slot · position · cache). Beyond the default, wire custom recorders for cost, latency, or quality scoring — any observation hook fires on the same stream.
@@ -677,9 +678,9 @@ Four views, one trace — pick by question:
 
 | View | Shows | When to use |
 |---|---|---|
-| **AgentThinkingUI** (the hero up top) | The run replayed as an animated, scrubbable story — the brain, the tools, the reasoning | Show anyone *what the agent did* |
+| **Story Lens** (the hero up top) | The run replayed as an animated, scrubbable story — the brain, the tools, the reasoning | Show anyone *what the agent did* |
 | **BacktrackView** ([the board above](#one-contextual-error-walked-end-to-end)) | A decision walked backwards — suspects, influence meters, ablation stamps, custody rewind | Answer *why it decided that* |
-| **Lens** | Agent-centric — User/Agent[3 slots]/Tool flowchart with iteration scrubber and round commentary | Live debugging, "what did the agent see at step 5?" |
+| **Why Lens** | Agent-centric — User/Agent[3 slots]/Tool flowchart with iteration scrubber and round commentary | Live debugging, "what did the agent see at step 5?" |
 | **Explainable Trace** | Structural — subflow tree, full flowchart, memory inspector, per-stage execution timeline | Architecture review, root-cause analysis |
 
 And two **conversational** doors over the same evidence — ask instead of look:
@@ -852,8 +853,8 @@ The flowchart, recorders, and tests don't change between dev and prod.
 - OTel GenAI span export · hash-chained tamper-evident audit bundles with an offline verifier
 
 **Tooling**
-- **AgentThinkingUI** — animated run player + BacktrackView why-board (separate `agentthinkingui` package)
-- **Lens** · **Explainable Trace** — two visual replays of the causal trace (separate `agentfootprint-lens` package)
+- **Story Lens** — animated run player + BacktrackView why-board (separate `agentthinkingui` package)
+- **Why Lens** · **Explainable Trace** — two visual replays of the causal trace (separate `agentfootprint-lens` package)
 - AI-coding-tool support — Claude Code · Cursor · Windsurf · Cline · Kiro · Copilot
 
 </details>

package/bin/agentfootprint-index.mjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+/**
+ * agentfootprint-index — build a corpus index from the command line.
+ *
+ * The third bin in this package, after `agentfootprint-setup` and
+ * `agentfootprint-lint-tools`. It exists because indexing is a BOOT-TIME job:
+ * a cron entry, a deploy step, a thing you run once after adding documents.
+ * Making that a script every consumer writes for themselves — argument
+ * parsing, embedder selection, a progress line — is the kind of small friction
+ * that gets in the way of the first ten minutes.
+ *
+ *   npx agentfootprint-index ./docs --to ./corpus.db
+ *   npx agentfootprint-index ./docs --to ./corpus.db --embedder local --split heading
+ *   npx agentfootprint-index ./docs --to ./corpus.db --dry-run
+ *
+ * It prints the same `IndexReport` the API returns, because the report IS the
+ * output: a second run over unchanged documents prints `embedded 0`, which is
+ * the whole point of an incremental index and the fastest way to see it work.
+ */
+
+import { parseArgs } from 'node:util';
+import { existsSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const USAGE = `
+agentfootprint-index — build a corpus index
+
+USAGE
+  agentfootprint-index <dir> --to <file.db> [options]
+
+REQUIRED
+  <dir>                  Directory of documents to index
+  --to <file.db>         SQLite index file (created if missing)
+
+OPTIONS
+  --embedder <name>      static (default) | local | openai | mock
+                         static: bundled weights, no key, no network
+                         local:  on-device sentence-transformer, no key
+                         openai: hosted, needs OPENAI_API_KEY
+                         mock:   letter frequency — plumbing only, NOT semantic
+  --split <name>         heading (default) | paragraph | fixed | whole
+  --chars <n>            Target chunk size. Default 1000
+  --overlap <n>          Overlap between chunks. Default 150
+  --include <.ext,...>   Extensions to index. Default: every format we read
+  --corpus <name>        Namespace to index into. Default '_global'
+  --no-recursive         Do not descend into subdirectories
+  --no-remove            Keep chunks whose document disappeared
+  --dry-run              Report what WOULD happen; write nothing
+  --json                 Print the report as JSON
+  -h, --help             This
+
+EXAMPLES
+  agentfootprint-index ./docs --to ./corpus.db
+  agentfootprint-index ./docs --to ./corpus.db --embedder local --chars 800
+  agentfootprint-index ./docs --to ./corpus.db --dry-run --json
+`;
+
+function fail(message) {
+  process.stderr.write(`agentfootprint-index: ${message}\n`);
+  process.stderr.write('Run with --help for usage.\n');
+  process.exit(1);
+}
+
+const { values, positionals } = (() => {
+  try {
+    return parseArgs({
+      allowPositionals: true,
+      options: {
+        to: { type: 'string' },
+        embedder: { type: 'string' },
+        split: { type: 'string' },
+        chars: { type: 'string' },
+        overlap: { type: 'string' },
+        include: { type: 'string' },
+        corpus: { type: 'string' },
+        recursive: { type: 'boolean', default: true },
+        remove: { type: 'boolean', default: true },
+        'dry-run': { type: 'boolean', default: false },
+        json: { type: 'boolean', default: false },
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+    });
+  } catch (err) {
+    fail(err instanceof Error ? err.message : String(err));
+  }
+})();
+
+if (values.help || positionals.length === 0) {
+  process.stdout.write(USAGE);
+  process.exit(values.help ? 0 : 1);
+}
+
+const dir = resolve(positionals[0]);
+if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+  fail(`'${positionals[0]}' is not a directory.`);
+}
+if (!values.to && !values['dry-run']) {
+  fail('--to <file.db> is required (or use --dry-run to report without writing).');
+}
+
+// Imported through the package's own entry points, so the CLI exercises the
+// same doors a consumer does — a break in the export map fails here too.
+const { indexCorpus } = await import('../dist/esm/doors/rag.js');
+const { byHeading, byParagraph, fixedWithOverlap, wholeDocument } = await import(
+  '../dist/esm/doors/rag.js'
+);
+const { sqliteVectorStore, InMemoryStore, mockEmbedder } = await import(
+  '../dist/esm/doors/memory.js'
+);
+const providers = await import('../dist/esm/doors/providers.js');
+
+const chars = values.chars === undefined ? undefined : Number(values.chars);
+const overlap = values.overlap === undefined ? undefined : Number(values.overlap);
+if (chars !== undefined && !Number.isFinite(chars)) fail('--chars must be a number.');
+if (overlap !== undefined && !Number.isFinite(overlap)) fail('--overlap must be a number.');
+
+const splitters = {
+  heading: () => byHeading({ ...(chars && { maxChars: chars }), ...(overlap !== undefined && { overlapChars: overlap }) }),
+  paragraph: () => byParagraph({ ...(chars && { maxChars: chars }), ...(overlap !== undefined && { overlapChars: overlap }) }),
+  fixed: () => fixedWithOverlap({ ...(chars && { chars }), ...(overlap !== undefined && { overlapChars: overlap }) }),
+  whole: () => wholeDocument(),
+};
+const splitName = values.split ?? 'heading';
+if (!(splitName in splitters)) {
+  fail(`unknown --split '${splitName}'. One of: ${Object.keys(splitters).join(', ')}.`);
+}
+
+const embedders = {
+  static: () => providers.staticEmbedder(),
+  local: () => providers.localEmbedder(),
+  openai: () => providers.openaiEmbedder(),
+  mock: () => mockEmbedder(),
+};
+const embedderName = values.embedder ?? 'static';
+if (!(embedderName in embedders)) {
+  fail(`unknown --embedder '${embedderName}'. One of: ${Object.keys(embedders).join(', ')}.`);
+}
+
+let embedder;
+try {
+  embedder = embedders[embedderName]();
+} catch (err) {
+  fail(err instanceof Error ? err.message : String(err));
+}
+
+// --dry-run writes to a throwaway in-memory index, so it reports real chunk
+// counts and real splitting without touching the file. It still EMBEDS —
+// the alternative is reporting a count that the real run might not match.
+const store = values['dry-run'] ? new InMemoryStore() : sqliteVectorStore({ file: resolve(values.to) });
+
+try {
+  const report = await indexCorpus({
+    source: {
+      dir,
+      recursive: values.recursive,
+      ...(values.include && { include: values.include.split(',').map((e) => e.trim()) }),
+    },
+    store,
+    embedder,
+    splitter: splitters[splitName](),
+    removeMissing: values.remove,
+    ...(values.corpus && { corpus: { conversationId: values.corpus } }),
+  });
+
+  if (values.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  } else {
+    const parts = [
+      `discovered ${report.discovered}`,
+      `loaded ${report.loaded}`,
+      `chunks ${report.chunks}`,
+      `embedded ${report.embedded}`,
+      `skipped ${report.skipped}`,
+      `removed ${report.removed}`,
+    ];
+    process.stdout.write(
+      `${values['dry-run'] ? '[dry run] ' : ''}${parts.join(' · ')}   (${report.elapsedMs}ms, ${report.splitter}, ${report.embedderFingerprint})\n`,
+    );
+    for (const failure of report.failed) {
+      process.stdout.write(`  failed: ${failure.uri} — ${failure.reason}\n`);
+    }
+    if (report.truncated.length > 0) {
+      process.stdout.write(
+        `  ${report.truncated.length} chunk(s) longer than the embedder reads — they were clipped. Lower --chars.\n`,
+      );
+    }
+  }
+  if (typeof store.close === 'function') store.close();
+} catch (err) {
+  process.stderr.write(`agentfootprint-index: ${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(1);
+}

package/dist/adapters/observability/cloudwatch.js

@@ -42,6 +42,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.cloudwatchObservability = exports._buildCloudWatchObservability = void 0;
 const lazyRequire_js_1 = require("../../lib/lazyRequire.js");
+const deliveryErrors_js_1 = require("./deliveryErrors.js");
 // ─── Generic base — also used by agentcoreObservability ──────────────
 /**
  * Internal: shared CloudWatch Logs base used by every adapter that
@@ -69,7 +70,20 @@ function _buildCloudWatchObservability(opts, strategyName) {
     let lastFlushPromise = Promise.resolve();
     let timer;
     let stopped = false;
-    let onErrorHook;
+    // What we know about the log stream (8.11.0). This is the per-(group,stream)
+    // create latch — group and stream are fixed for the life of a strategy, so
+    // one tri-state IS that latch:
+    //   'unknown'     — never delivered yet, or the stream vanished under us
+    //   'created'     — we created it, or a put has succeeded against it
+    //   'unavailable' — a create attempt failed for a reason retrying won't fix
+    //                   (no permission, missing GROUP). Never attempt again.
+    // 'created' is deliberately NOT terminal: a retention policy can delete a
+    // stream mid-process, and the next ResourceNotFoundException should heal it.
+    // Only 'unavailable' is terminal, which is what stops a create/put loop.
+    let streamState = 'unknown';
+    // The fallback when the consumer wires nothing. Rate-limited; a
+    // consumer-supplied sink is not.
+    const consoleSink = (0, deliveryErrors_js_1.rateLimitedConsoleSink)(strategyName);
     // Lazy-resolved on first flush so consumers who never trigger a
     // flush (because nothing was emitted) don't even hit the SDK.
     let client = opts._client;
@@ -87,6 +101,21 @@ function _buildCloudWatchObservability(opts, strategyName) {
             void doFlush();
         }, flushIntervalMs);
     }
+    /** Route a delivery failure through whatever `_onError` IS RIGHT NOW.
+     *  Reading it at call time (rather than capturing a hook at construction)
+     *  is the whole fix: a consumer who assigns `_onError` after building the
+     *  strategy gets delivery failures, and one who doesn't still gets the
+     *  default console sink. */
+    function reportFailure(err) {
+        strategy._onError?.(err);
+    }
+    async function putBatch(client, batch) {
+        await client.putLogEvents({
+            logGroupName: opts.logGroupName,
+            logStreamName,
+            logEvents: batch,
+        });
+    }
     async function doFlush() {
         if (buffer.length === 0 || stopped)
             return;
@@ -95,14 +124,57 @@ function _buildCloudWatchObservability(opts, strategyName) {
         const batch = buffer.splice(0);
         bufferBytes = 0;
         try {
-            await ensureClient().putLogEvents({
-                logGroupName: opts.logGroupName,
-                logStreamName,
-                logEvents: batch,
-            });
+            const client = ensureClient();
+            try {
+                await putBatch(client, batch);
+                streamState = 'created'; // a successful put proves the stream is there
+                return;
+            }
+            catch (err) {
+                // The one recoverable shape: CloudWatch rejects a put into a stream
+                // that doesn't exist. Before 8.11.0 this adapter asserted that
+                // precondition and never established it, so any stream name that
+                // didn't already exist dropped every event, forever, in silence —
+                // and the documented `${HOSTNAME}/${Date.now()}` convention can never
+                // pre-exist, so following the docs guaranteed the bug.
+                if (!isMissingStreamError(err) || streamState === 'unavailable')
+                    throw err;
+                if (!client.createLogStream) {
+                    throw new Error(`log stream '${logStreamName}' does not exist in log group ` +
+                        `'${opts.logGroupName}', and the injected \`_client\` has no ` +
+                        `\`createLogStream\` to create it.`);
+                }
+                try {
+                    await client.createLogStream({
+                        logGroupName: opts.logGroupName,
+                        logStreamName,
+                    });
+                }
+                catch (createErr) {
+                    // Two processes racing to create the same stream is normal and
+                    // expected — whoever lost the race still has a usable stream.
+                    if (!isAlreadyExistsError(createErr)) {
+                        // Anything else (no `logs:CreateLogStream`, or the log GROUP
+                        // itself is missing) will not fix itself. Latch it off so we
+                        // never loop, and say which of the two it probably is.
+                        streamState = 'unavailable';
+                        throw new Error(`could not create log stream '${logStreamName}' in log group ` +
+                            `'${opts.logGroupName}': ${errorMessage(createErr)}. Check that the log ` +
+                            `GROUP exists (this adapter never creates one) and that the role allows ` +
+                            `\`logs:CreateLogStream\`.`);
+                    }
+                }
+                streamState = 'created';
+                // Exactly ONE re-put of the same batch. Not a retry loop: if this
+                // fails the events are gone, and saying so is better than growing a
+                // buffer during an outage.
+                await putBatch(client, batch);
+            }
         }
         catch (err) {
-            onErrorHook?.(err instanceof Error ? err : new Error(String(err)));
+            const cause = errorMessage(err);
+            reportFailure(new Error(`${batch.length} event(s) dropped shipping to log group '${opts.logGroupName}' ` +
+                `stream '${logStreamName}': ${cause}`));
         }
     }
     function enqueue(event) {
@@ -121,10 +193,16 @@ function _buildCloudWatchObservability(opts, strategyName) {
             scheduleTimedFlush();
         }
     }
-    return {
+    const strategy = {
         name: strategyName,
         capabilities: { events: true, logs: true },
         exportEvent: enqueue,
+        /**
+         * Drain the buffer. **The framework does not call this for you** — wire it
+         * into your own shutdown or the last batch is lost:
+         *
+         *   process.on('SIGTERM', async () => { await strategy.flush(); strategy.stop(); });
+         */
         async flush() {
             // Drain anything pending. Awaits both an in-flight put AND any
             // newly-buffered events that arrived during it.
@@ -140,6 +218,8 @@ function _buildCloudWatchObservability(opts, strategyName) {
                     break;
             }
         },
+        /** Stop the flush timer. **The framework does not call this for you** —
+         *  an un-stopped strategy keeps a `setTimeout` alive. */
         stop() {
             stopped = true;
             if (timer) {
@@ -147,22 +227,46 @@ function _buildCloudWatchObservability(opts, strategyName) {
                 timer = undefined;
             }
         },
+        /**
+         * Where errors go. Two callers: the dispatch layer (when `exportEvent`
+         * itself throws) and this adapter's own delivery path.
+         *
+         * Before 8.11.0 this method lazily installed the console fallback INSIDE
+         * itself, so a delivery failure — which reads the hook rather than calling
+         * this method — found `undefined` and vanished. The fallback now exists
+         * from construction, and delivery failures route through this method,
+         * which means overriding it works: assign `_onError`, or pass `onError`
+         * in the factory options, and you receive delivery failures too.
+         */
         _onError(err, event) {
-            // Capture for use inside doFlush (the strategy doesn't know what
-            // the consumer's error sink is unless they wire `_onError` via
-            // the strategy options. We store it on this hook so put-failures
-            // route correctly).
-            onErrorHook =
-                onErrorHook ??
-                    ((e) => {
-                        // eslint-disable-next-line no-console
-                        console.error(`[${strategyName}Observability] flush failed:`, e.message);
-                    });
-            onErrorHook(err, event);
+            (opts.onError ?? consoleSink)(err, event);
         },
     };
+    return strategy;
 }
 exports._buildCloudWatchObservability = _buildCloudWatchObservability;
+// ─── Error shape helpers ─────────────────────────────────────────────
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Did this put fail because the log stream isn't there?
+ *
+ * Matched on `name` first (how the AWS SDK v3 surfaces it) with a message
+ * fallback, because a transport shim or an injected test double may carry the
+ * code only in the text.
+ */
+function isMissingStreamError(err) {
+    if (err?.name === 'ResourceNotFoundException')
+        return true;
+    return /ResourceNotFoundException|log stream does not exist/i.test(errorMessage(err));
+}
+/** Lost a create race with another process. Not an error — the stream exists. */
+function isAlreadyExistsError(err) {
+    if (err?.name === 'ResourceAlreadyExistsException')
+        return true;
+    return /ResourceAlreadyExistsException|already exists/i.test(errorMessage(err));
+}
 // ─── Public factory: cloudwatchObservability ─────────────────────────
 /**
  * Generic CloudWatch Logs observability adapter. See
@@ -191,6 +295,7 @@ function createCloudWatchClient(region, strategyName) {
             `\`CloudWatchLogsClient\` / \`PutLogEventsCommand\` was not found. Update the SDK.`);
     }
     const sdkClient = new mod.CloudWatchLogsClient({ ...(region && { region }) });
+    const createLogStreamCommand = mod.CreateLogStreamCommand;
     return {
         async putLogEvents(input) {
             // Cast the SDK constructor to the call shape — same trick as
@@ -198,6 +303,15 @@ function createCloudWatchClient(region, strategyName) {
             const cmd = new mod.PutLogEventsCommand(input);
             await sdkClient.send(cmd);
         },
+        // Only offered when the installed SDK has the command. An older SDK
+        // without it degrades to a reported failure rather than a crash — the
+        // adapter checks for this method before reaching for it.
+        ...(createLogStreamCommand && {
+            async createLogStream(input) {
+                const cmd = new createLogStreamCommand(input);
+                await sdkClient.send(cmd);
+            },
+        }),
     };
 }
 //# sourceMappingURL=cloudwatch.js.map

package/dist/adapters/observability/cloudwatch.js.map

@@ -1 +1 @@
-{"version":3,"file":"cloudwatch.js","sourceRoot":"","sources":["../../../src/adapters/observability/cloudwatch.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cloudwatch.js","sourceRoot":"","sources":["../../../src/adapters/observability/cloudwatch.ts"],"names":[],"mappings":"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"}

package/dist/adapters/observability/deliveryErrors.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * deliveryErrors — where an exporter's failures go when nobody is listening.
+ *
+ * **Telemetry that fails invisibly is indistinguishable from telemetry that
+ * works.** Every network-shipping observability adapter has the same problem:
+ * `exportEvent` is sync and non-throwing by contract, so the actual delivery
+ * happens later, inside a flush the caller never sees. If that flush fails and
+ * nothing is wired up, the process keeps running, the dashboard stays empty,
+ * and nobody learns anything until someone goes looking for a run that isn't
+ * there.
+ *
+ * Before 8.11.0 each adapter installed its console fallback lazily, INSIDE its
+ * own `_onError` method — so a delivery failure, which read the hook rather
+ * than calling the method, found `undefined` and vanished. Every CloudWatch,
+ * X-Ray and OTEL delivery failure was silent in the ordinary case.
+ *
+ * The rule this module encodes: **an unheard failure still gets said out loud,
+ * but saying it must not become the second outage.** A backend that has been
+ * down for an hour would otherwise produce one `console.error` per flush
+ * interval for an hour.
+ *
+ * Role: leaf helper for `adapters/observability/*`. No imports beyond the
+ * event type; composed as a field, never inherited.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rateLimitedConsoleSink = void 0;
+/**
+ * The default sink: loud on the first failure, then logarithmically quieter.
+ *
+ * Reports at failures 1, 2, 4, 8, 16, 32 … and stamps the running count, so an
+ * ongoing outage is visible (you can see the number climbing) without flooding
+ * the log. A consumer-supplied sink is NOT rate-limited — they asked for every
+ * failure and can do their own filtering.
+ *
+ * @param strategyName the adapter's `name` (e.g. `'cloudwatch'`), used to
+ *   prefix the line so a multi-exporter process says which one failed.
+ */
+function rateLimitedConsoleSink(strategyName) {
+    let failures = 0;
+    let reportAt = 1;
+    return (error) => {
+        failures++;
+        if (failures < reportAt)
+            return;
+        // Double the gap each time we speak, so the log cost is logarithmic in
+        // the length of the outage.
+        reportAt = failures * 2;
+        const count = failures > 1 ? ` (delivery failure #${failures})` : '';
+        // eslint-disable-next-line no-console
+        console.error(`[${strategyName}Observability] delivery failed${count}:`, error.message);
+    };
+}
+exports.rateLimitedConsoleSink = rateLimitedConsoleSink;
+//# sourceMappingURL=deliveryErrors.js.map

package/dist/adapters/observability/deliveryErrors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deliveryErrors.js","sourceRoot":"","sources":["../../../src/adapters/observability/deliveryErrors.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;;;AAOH;;;;;;;;;;GAUG;AACH,SAAgB,sBAAsB,CAAC,YAAoB;IACzD,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,OAAO,CAAC,KAAY,EAAQ,EAAE;QAC5B,QAAQ,EAAE,CAAC;QACX,IAAI,QAAQ,GAAG,QAAQ;YAAE,OAAO;QAChC,uEAAuE;QACvE,4BAA4B;QAC5B,QAAQ,GAAG,QAAQ,GAAG,CAAC,CAAC;QACxB,MAAM,KAAK,GAAG,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,uBAAuB,QAAQ,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,sCAAsC;QACtC,OAAO,CAAC,KAAK,CAAC,IAAI,YAAY,iCAAiC,KAAK,GAAG,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAC1F,CAAC,CAAC;AACJ,CAAC;AAbD,wDAaC"}