wendkeep 0.13.0 → 0.16.0

package/CHANGELOG.md

@@ -4,6 +4,49 @@ All notable changes to **wendkeep** are documented here. Format based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.16.0] — 2026-07-06
+
+Retroactive memory.
+
+### Added
+- **`wendkeep import`** — backfill the vault with this project's *past* Claude Code sessions.
+  It scans `.claude/projects/<slug>/*.jsonl`, and for every session not already in the vault
+  (deduped by `session_id` against the `SESSION_REGISTRY`) reconstructs a full, dated session
+  note — frontmatter, one iteration block per turn, cost + subagent telemetry, derived
+  decision/bug/learning notes, and a finalized closing — placed in its **real** date folder
+  (`02-Sessões/<year>/<MM-MMM>/DIA <dd>/`), not today's. One command turns your whole history
+  into memory that `wendkeep cost` immediately aggregates.
+  - Offline replay of the live capture flow (same `buildSessionContent` / `insertIteration` /
+    `finalizeSessionFile` / usage + subagent code) so an imported note is indistinguishable
+    from a captured one.
+  - Options: `--from <dir>` (point at the `.claude/projects` folder explicitly), `--project`,
+    `--since <date>`, `--limit <n>`, `--dry-run` (report without writing), `--json`.
+  - Idempotent: re-running skips everything already imported. Never overwrites an existing note.
+  - v1 covers Claude Code transcripts; Codex is a follow-up.
+
+### Changed
+- `session-start.mjs` now guards its `main()` behind the standard `import.meta.url` check (like
+  `session-stop.mjs`) so its note-building helpers can be imported by `import`/tests without
+  running the hook. No behavioral change when invoked as a hook.
+
+## [0.15.0] — 2026-07-06
+
+### Added
+- **`wendkeep cost --top [N]`** — the N priciest sessions (cost incl. subagents · date · file),
+  most expensive first (default 10). Spot where the money went. `cost --json` now also carries
+  the per-session `sessions` list.
+
+## [0.14.0] — 2026-07-06
+
+### Changed
+- **dotcontext is no longer a default companion.** wendkeep's native a2 loop (`change` /
+  `verify` / gate) recreates dotcontext's execution/gate role, so pinning it duplicates the
+  harness. The interactive / `--yes` default is now **`context-mode` only**; dotcontext stays
+  selectable via `--companions dotcontext` for anyone already invested.
+- **README:** rewrote "Install & set up" with a clear **`init` options table** and a
+  per-companion breakdown; clarified that `--no-mcp` skips **only wendkeep's own** vault MCP
+  (companion MCPs still follow `--companions`).
+
 ## [0.13.0] — 2026-07-06
 
 Cost intelligence: waste + average.
@@ -272,6 +315,8 @@ Initial release — the capture engine, extracted from a system in daily product
 - `wendkeep init` (cross-platform installer) + optional `@bitbonsai/mcpvault` MCP server.
 
 <!-- Only v0.4.0+ is tagged in git (history starts here); older versions link to npm. -->
+[0.15.0]: https://github.com/rogersialves/wendkeep/releases/tag/v0.15.0
+[0.14.0]: https://github.com/rogersialves/wendkeep/releases/tag/v0.14.0
 [0.13.0]: https://github.com/rogersialves/wendkeep/releases/tag/v0.13.0
 [0.12.0]: https://github.com/rogersialves/wendkeep/releases/tag/v0.12.0
 [0.11.0]: https://github.com/rogersialves/wendkeep/releases/tag/v0.11.0

package/README.md

@@ -39,20 +39,40 @@ npx wendkeep init
 
 1. Create the vault folder taxonomy and a templated `README.md` (default vault: `<project>/.<project-name>-vault`, e.g. `.MyApp-vault`; override with `--vault`).
 2. **Merge** the three session hooks and `OBSIDIAN_VAULT_PATH` into `.claude/settings.json` — without clobbering your existing settings (a `.bak` is saved; an unparseable file is left untouched and a `.new` is written for you to merge).
-3. Add the `wendkeep-vault` MCP server to `.mcp.json` (skip with `--no-mcp`).
-4. Offer to pin **companion** plugins/MCP (multi-choice; `context-mode` + `dotcontext` pre-checked). Each is wired through the most agent-agnostic path it supports — `context-mode` and `dotcontext` as `.mcp.json` MCP servers (any agent), `understand-anything` via a `understand-inject` SessionStart hook that injects its domain graph when generated, and the Claude Code plugin layer (`extraKnownMarketplaces` + `enabledPlugins`) as a bonus. **`dotcontext`** (execution/PREVC harness) also gets its lifecycle hooks wired (SessionStart-last + Stop + PostToolUse, pinned CLI) and a starter `.context/config/sensors.json` seeded with a `wendkeep validate-memory` sensor plus one per detected `package.json` script (test/typecheck/lint/build) — add the `.context/runtime|cache|logs|plans|agents|skills/` paths to `.gitignore` (wendkeep doesn't touch git). If dotcontext is already configured globally (`~/.claude.json`), the project MCP entry is **skipped automatically** to avoid a duplicate; tune with `--dotcontext-mcp <auto|project|none>` and `--dotcontext-hooks <full|light|none>` (light drops PostToolUse). Control selection with `--companions <csv>` or `--no-companions`. (`caveman` additionally runs its own cross-agent installer on non-Claude agents.)
+3. Add the **`wendkeep-vault`** MCP server to `.mcp.json` so the agent can read/write the vault. Skip with `--no-mcp` — e.g. when the agent already has a vault MCP. (`--no-mcp` skips *only wendkeep's own* MCP; companion MCPs still follow `--companions`.)
+4. Offer to pin **companion** plugins/MCP (multi-choice; only `context-mode` pre-checked). Each is wired the most agent-agnostic way it supports:
+   - **`context-mode`** — context optimizer + FTS5 memory, as a `.mcp.json` MCP server (any agent). The recommended default.
+   - **`understand-anything`** — project domain graph, via a `understand-inject` SessionStart hook that injects the graph when generated.
+   - **`caveman`** — token-compression mode; runs its own cross-agent installer on non-Claude agents.
+   - **`dotcontext`** — *legacy, not recommended.* wendkeep's native a2 loop (`change` / `verify` / gate) already does its job, so installing it **duplicates the harness**. Still selectable via `--companions dotcontext` for anyone already invested (tune with `--dotcontext-mcp` / `--dotcontext-hooks`), but off by default.
+
+   Control with `--companions <csv>` or `--no-companions`. The Claude Code plugin layer (`extraKnownMarketplaces` + `enabledPlugins`) is wired as a bonus where the companion has one.
 5. Install a **color system** into the vault's `.obsidian/`: a CSS snippet that accents notes by type (session/decision/bug/learning, via the `cssclasses` the hooks emit) plus graph color groups by folder. Non-destructive merge into `appearance.json`/`graph.json`; skip with `--no-colors`.
 6. Seed the **curated memory layer**: `.brain/CORE.md` (the hand-curated hot layer, with the 3 required sections) and `.brain/COMPACTION_PROTOCOL.md` (the protocol guide). The auto layers (`DIGEST.md`, `index.jsonl`) are generated by the hooks. Validate the curated layer with `wendkeep validate-memory` (cap 25 lines, 3 sections, no secrets/PII).
 7. Seed the **definitions + skills layer**: `.brain/agents/` + `.brain/skills/` (versioned source of truth), including the native process skills `wk-workflow` / `wk-tdd` / `wk-debugging` / `wk-brainstorming` / `wk-planning`. `init` runs `wendkeep sync-defs` for you, delivering them to `.codex/agents/` + `.claude/skills/` (re‑run `sync-defs` after editing `.brain`).
 8. Seed the **change/spec lifecycle**: the `07-Specs/` + `08-Mudanças/` folders and a native `wendkeep.sensors.json` (a `validate-memory` sensor plus one per detected `package.json` script). Drives `wendkeep change` / `wendkeep verify` — see **Change lifecycle** below.
 
 ```bash
-npx wendkeep init --vault "~/vaults/work" --project . --yes   # non-interactive (companions: context-mode,dotcontext)
-npx wendkeep init --companions "context-mode,caveman" --yes
-npx wendkeep init --no-companions --yes
+npx wendkeep init --vault "~/vaults/work" --project . --yes   # non-interactive (default companion: context-mode)
+npx wendkeep init --companions "context-mode,understand-anything" --yes
+npx wendkeep init --no-companions --no-mcp --yes              # zero companions, no wendkeep MCP
 ```
 
-Then open the vault in Obsidian, send a test prompt in your agent, and confirm a note appears under `02-Sessões/…`.
+### `init` options
+
+| Flag | What it does |
+|---|---|
+| `--vault <path>` | Vault folder. Default `<project>/.<project-name>-vault`; interactive init asks. Point it at an existing vault to install into it. |
+| `--project <path>` | Project root to wire (default: current directory). |
+| `--locale <pt-BR\|en>` | Vault language — folder names, scaffold, skills. Interactive init asks; locked at init. |
+| `--companions <csv>` | Companions to pin: `context-mode,caveman,understand-anything` (default: `context-mode`; `dotcontext` is legacy). |
+| `--no-companions` | Pin no companions. |
+| `--no-mcp` | Skip **wendkeep's own** vault MCP (`wendkeep-vault`). Companion MCPs still follow `--companions`. |
+| `--no-colors` | Skip the Obsidian color system (`.obsidian` snippet + graph groups). |
+| `--yes`, `-y` | Non-interactive; accept defaults (skips the language / vault / companion prompts). |
+| `--force` | Overwrite existing wendkeep config blocks. |
+
+Then open the vault in Obsidian, send a test prompt in your agent, and confirm a note appears under `02-Sessões/…` (or `02-Sessions/…` for an `en` vault).
 
 ## Updating
 
@@ -75,12 +95,27 @@ No re‑copying, no snapshot to re‑sync — the package is the single source o
 | `wendkeep spec <sub>` | Living specs: `list` / `show <capability>`. |
 | `wendkeep sensors <sub>` | `list` / `add <id> "<command>"` — view/edit `wendkeep.sensors.json` (JSON Schema shipped). |
 | `wendkeep cost [--since d]` | Aggregate AI-coding spend across the vault's sessions — total, by model, by day (`--json`). |
+| `wendkeep import [opts]` | **Retroactive memory** — backfill past Claude sessions into the vault (deduped by `session_id`). `--from <dir>` / `--since d` / `--limit n` / `--dry-run` / `--json`. |
 | `wendkeep lesson add "t" "l"` | Record a project-local lesson (injected at the next SessionStart). |
 | `wendkeep sync-defs` | Copy `.brain/agents\|skills` into the project (`.codex/agents`, `.claude/skills`). |
 | `wendkeep validate-memory [path]` | Validate `.brain/CORE.md` (cap 25, 3 sections, no secrets/PII). |
 | `wendkeep doctor [--vault P]` | Run a vault health check (integrity of sessions, registry, links). |
 | `wendkeep --version` / `--help` | Version / usage. |
 
+## Retroactive memory (`import`)
+
+Install wendkeep into an existing project and it only remembers sessions **from now on**. `wendkeep import` fixes that: it reads the project's past Claude Code transcripts (`~/.claude/projects/<slug>/*.jsonl`) and rebuilds each one as a full session note in its **real** date folder — frontmatter, one iteration block per turn, cost + subagent telemetry, derived decision/bug/learning notes, finalized closing. It is an offline replay of the live capture flow, so an imported note is indistinguishable from a captured one.
+
+```bash
+wendkeep import --vault .myproject-vault --dry-run   # preview what would be imported
+wendkeep import --vault .myproject-vault             # write the notes
+```
+
+- **Deduped** by `session_id` against the vault's `SESSION_REGISTRY` — only sessions not already present are imported, and it never overwrites an existing note. Re-running is a no-op.
+- **`--from <dir>`** points at the `.claude/projects/<slug>/` folder explicitly (use it if the auto-derived path misses). Also: `--since <date>`, `--limit <n>`, `--json`.
+- Once imported, `wendkeep cost` aggregates your entire history — retroactively.
+- v1 covers Claude Code; Codex import is a follow-up.
+
 ## Change lifecycle — the a2 loop (spec‑driven, native)
 
 Beyond capturing sessions, wendkeep is a **harness**: a native, zero‑dependency loop that keeps *intent* (specs), *work* (changes) and *proof* (sensors) together in the vault, wikilinked into the Obsidian graph.

package/bin/wendkeep.mjs

@@ -29,8 +29,8 @@ Usage:
     --vault <path>         Obsidian vault folder (default: <project>/.<project-name>-vault).
     --project <path>       Project root to wire (default: current directory).
     --no-mcp               Do not add the mcpvault MCP server to .mcp.json.
-    --companions <csv>     Companion plugins/MCP to pin: context-mode,dotcontext,caveman,understand-anything
-                           (default when interactive/--yes: context-mode,dotcontext).
+    --companions <csv>     Companion plugins/MCP to pin: context-mode,caveman,understand-anything
+                           (default: context-mode). dotcontext is legacy — the native a2 loop replaces it.
     --no-companions        Skip companion plugins/MCP entirely.
     --no-colors            Skip the Obsidian color system (.obsidian snippet + graph groups).
     --dotcontext-mcp <v>   dotcontext MCP placement: auto (default; skip project entry
@@ -47,7 +47,9 @@ Usage:
                            done <id> | undone <id> | diff | archive [--force].
   wendkeep spec <sub>          Living specs: list | show <capability>.
   wendkeep sensors <sub>       list | add <id> "<command>" [--severity --type --report].
-  wendkeep cost [--since d]    Aggregate AI-coding spend across the vault's sessions (--json).
+  wendkeep cost [opts]         Aggregate AI-coding spend across the vault's sessions.
+  wendkeep import [opts]       Backfill: import this project's past Claude sessions into the vault.
+                           --since <date> · --top [N] (priciest sessions) · --json.
   wendkeep verify [--change s] Run a change's task sensors + record evidence (the gate).
   wendkeep lesson add "t" "l"   Record a project-local lesson (injected at SessionStart).
   wendkeep validate-memory [path]  Validate .brain/CORE.md against the compaction
@@ -136,6 +138,11 @@ async function main() {
       runCost(rest);
       break;
     }
+    case 'import': {
+      const { runImportCli } = await import('../src/import.mjs');
+      runImportCli(rest);
+      break;
+    }
     case '--version':
     case '-v':
       process.stdout.write(`${version()}\n`);

package/hooks/import-sessions.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+// Retroactive memory: import Claude Code transcripts that predate wendkeep into the vault.
+// Each `.claude/projects/<slug>/<session_id>.jsonl` becomes a full session note in its real
+// dated folder, deduped by session_id against the vault's SESSION_REGISTRY. This is an offline
+// replay of the live capture flow — same skeleton, same iteration blocks, same cost/subagent
+// telemetry, same finalize — so an imported note is indistinguishable from a captured one.
+import { existsSync, readdirSync, writeFileSync } from 'fs';
+import { basename, join } from 'path';
+import {
+  parseTranscript,
+  buildIterationBlock,
+  insertIteration,
+  finalizeSessionFile,
+  mergeCreatedNotes,
+  findLinkedDerivedNotes,
+} from './session-stop.mjs';
+import { buildSessionContent, allocateSessionPath } from './session-start.mjs';
+import { createLinkedNotes } from './linked-notes.mjs';
+import { updateSessionUsage } from './token-usage.mjs';
+import { upsertSubagentUsage } from './subagent-usage.mjs';
+import { readSessionRegistry, upsertSessionRegistry, formatLocalIso, formatDate } from './obsidian-common.mjs';
+
+// Claude encodes a project's absolute path as its `.claude/projects` dir name by replacing each
+// path separator and the drive colon with '-'. `C:\GitHub\WendKeep` -> `C--GitHub-WendKeep`.
+// Note: each char maps 1:1 (no collapsing), so `C:\` yields `C--`.
+export function claudeProjectSlug(projectPath) {
+  return String(projectPath || '').replace(/[\\/:]/g, '-');
+}
+
+function homeDir() {
+  return process.env.USERPROFILE || process.env.HOME || '';
+}
+
+export function defaultClaudeProjectsDir(projectPath) {
+  const home = homeDir();
+  if (!home) return '';
+  return join(home, '.claude', 'projects', claudeProjectSlug(projectPath));
+}
+
+// List candidate transcripts. The Claude session_id IS the filename, so we get it without
+// parsing — cheap dedup for the (usually large) set of already-captured sessions.
+export function discoverTranscripts(projectPath, fromDir) {
+  const dir = fromDir || defaultClaudeProjectsDir(projectPath);
+  if (!dir || !existsSync(dir)) return { dir, transcripts: [] };
+  const transcripts = readdirSync(dir)
+    .filter((name) => /\.jsonl$/i.test(name))
+    .map((name) => ({ path: join(dir, name), sessionId: basename(name, '.jsonl') }));
+  return { dir, transcripts };
+}
+
+// Session objective for the note title/frontmatter: first real user prompt, one line.
+function deriveSummary(tx) {
+  for (const turn of tx.turns || []) {
+    const prompt = (turn.userPrompts || []).find(Boolean);
+    if (prompt) {
+      return prompt.replace(/[\r\n#]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 80) || 'session';
+    }
+  }
+  return 'session';
+}
+
+function toDate(ts, fallback) {
+  const d = ts ? new Date(ts) : null;
+  return d && Number.isFinite(d.getTime()) ? d : fallback;
+}
+
+// Replay one transcript into a fresh, finalized note. Returns {sessionId, relPath, turns} or
+// null when the transcript has no memorializable turns. Assumes the caller already deduped.
+export function importSession(vaultBase, txPath, preParsed) {
+  const tx = preParsed || parseTranscript(txPath);
+  const turns = tx.turns || [];
+  if (!turns.length) return null;
+
+  const sessionId = tx.sessionId || basename(String(txPath), '.jsonl');
+  const startDate = toDate(turns[0].timestamp, new Date());
+  const endDate = toDate(turns.at(-1).timestamp, startDate);
+  const summary = deriveSummary(tx);
+
+  // Skeleton in the real dated folder.
+  const { absPath, relPath } = allocateSessionPath(vaultBase, startDate, summary);
+  writeFileSync(absPath, buildSessionContent({ relPath, now: startDate, summary }), 'utf-8');
+
+  // One iteration block per turn (insertIteration dedups by turn marker -> re-import safe).
+  for (const turn of turns) {
+    const block = buildIterationBlock(tx, { turn_id: turn.turnId, now: turn.timestamp });
+    insertIteration(absPath, block, turn.turnId, tx);
+  }
+
+  // Cost + subagent telemetry, exactly like the live Stop hook. Fail-open.
+  try {
+    updateSessionUsage({ vaultBase, sessionRel: relPath, sessionPath: absPath, transcriptPath: txPath });
+  } catch { /* usage is best-effort */ }
+  try {
+    upsertSubagentUsage(absPath, txPath);
+  } catch { /* subagent telemetry is best-effort */ }
+
+  // Finalize: derived notes + closing section + ended_at from the last turn.
+  const endedAt = formatLocalIso(endDate);
+  const created = mergeCreatedNotes(
+    createLinkedNotes(vaultBase, formatDate(endDate), relPath, tx),
+    findLinkedDerivedNotes(vaultBase, relPath),
+  );
+  finalizeSessionFile(absPath, tx, created, endedAt);
+
+  upsertSessionRegistry(vaultBase, sessionId, {
+    session_file: relPath,
+    status: 'done',
+    started_at: formatLocalIso(startDate),
+    ended_at: endedAt,
+    last_turn_id: turns.at(-1).turnId,
+    transcript_path: txPath,
+    imported: true,
+  });
+
+  return { sessionId, relPath, turns: turns.length };
+}
+
+// Import every not-yet-captured transcript. Deduped by session_id against the registry.
+// Options: { projectPath, from, since (ISO/date), limit, dryRun }.
+export function runImport(vaultBase, opts = {}) {
+  const { projectPath = process.cwd(), from = '', since = '', limit = 0, dryRun = false } = opts;
+  const { dir, transcripts } = discoverTranscripts(projectPath, from);
+  const captured = new Set(Object.keys(readSessionRegistry(vaultBase).sessions || {}));
+  const sinceMs = since ? Date.parse(since) : 0;
+  const report = { dir, scanned: transcripts.length, imported: 0, skipped: 0, errors: [], sessions: [] };
+
+  let done = 0;
+  for (const t of transcripts) {
+    if (captured.has(t.sessionId)) { report.skipped++; continue; }
+    if (limit && done >= limit) break;
+
+    let tx;
+    try {
+      tx = parseTranscript(t.path);
+    } catch (error) {
+      report.errors.push({ sessionId: t.sessionId, error: error.message });
+      continue;
+    }
+    const turns = tx.turns || [];
+    if (!turns.length) { report.skipped++; continue; }
+
+    const startTs = turns[0].timestamp || '';
+    if (sinceMs && startTs && Number.isFinite(Date.parse(startTs)) && Date.parse(startTs) < sinceMs) {
+      report.skipped++;
+      continue;
+    }
+
+    if (dryRun) {
+      report.sessions.push({ sessionId: t.sessionId, turns: turns.length, startTs, dryRun: true });
+      report.imported++;
+      done++;
+      continue;
+    }
+
+    try {
+      const r = importSession(vaultBase, t.path, tx);
+      if (r) { report.sessions.push(r); report.imported++; done++; }
+      else { report.skipped++; }
+    } catch (error) {
+      report.errors.push({ sessionId: t.sessionId, error: error.message });
+    }
+  }
+
+  return report;
+}

package/hooks/session-start.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { existsSync, writeFileSync } from 'fs';
 import { basename, join } from 'path';
+import { pathToFileURL } from 'url';
 import {
   controlPath,
   ensureDir,
@@ -30,7 +31,7 @@ import {
   yamlQuote,
 } from './obsidian-common.mjs';
 
-function buildSessionContent({ relPath, now, summary = 'session' }) {
+export function buildSessionContent({ relPath, now, summary = 'session' }) {
   const date = formatDate(now);
   const startedAt = formatLocalIso(now);
   const titleTime = formatTime(now).slice(0, 5);
@@ -112,7 +113,7 @@ Sessão ainda em andamento.
 `;
 }
 
-function allocateSessionPath(vaultBase, now, summary = 'session') {
+export function allocateSessionPath(vaultBase, now, summary = 'session') {
   const folderRel = sessionFolderRel(now, vaultBase);
   const folderAbs = join(vaultBase, folderRel);
   ensureDir(folderAbs);
@@ -301,11 +302,13 @@ function main() {
   });
 }
 
-try {
-  main();
-} catch (error) {
-  process.stderr.write(`[codex-obsidian] SessionStart falhou: ${error.message}\n`);
-  writeHookOutput({
-    systemMessage: `[codex-obsidian] Não foi possível criar a sessão Obsidian: ${error.message}`,
-  });
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    main();
+  } catch (error) {
+    process.stderr.write(`[codex-obsidian] SessionStart falhou: ${error.message}\n`);
+    writeHookOutput({
+      systemMessage: `[codex-obsidian] Não foi possível criar a sessão Obsidian: ${error.message}`,
+    });
+  }
 }

package/hooks/session-stop.mjs

@@ -781,7 +781,7 @@ function noteReferencesSession(content, sessionRel) {
   return content.includes(sessionRel) || content.includes(sessionLink);
 }
 
-function findLinkedDerivedNotes(vaultBase, sessionRel) {
+export function findLinkedDerivedNotes(vaultBase, sessionRel) {
   const linked = { decisions: [], bugs: [], learnings: [] };
   const locF = getLocale(vaultBase).folders;
   const folders = {
@@ -808,7 +808,7 @@ function findLinkedDerivedNotes(vaultBase, sessionRel) {
   return linked;
 }
 
-function mergeCreatedNotes(created, linked) {
+export function mergeCreatedNotes(created, linked) {
   const merged = { decisions: [], bugs: [], learnings: [] };
   for (const key of Object.keys(merged)) {
     merged[key] = [...new Set([...(created[key] || []), ...(linked[key] || [])])];
@@ -861,7 +861,7 @@ function replaceClosingSection(content, closing) {
   return `${content.slice(0, index).trimEnd()}\n\n${closing}\n`;
 }
 
-function finalizeSessionFile(sessionPath, tx, created, endedAt) {
+export function finalizeSessionFile(sessionPath, tx, created, endedAt) {
   const pending = extractPending(tx.rawTextForDetection);
   const links = (items) => items.length ? items.map((rel) => `  - ${wikilinkFromRel(rel)}`).join('\n') : '  - Nenhuma';
   const summary = tx.latestAssistantMessage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.13.0",
+  "version": "0.16.0",
   "description": "A persistent-memory harness for AI coding agents on your Obsidian vault: turn-by-turn session capture plus a native, zero-dependency spec→change→verify→archive loop (sensor-gated, independent verdict, mutation discrimination). Local-first, agent-agnostic (Claude Code, Codex, Cursor…).",
   "type": "module",
   "bin": {

package/src/cost.mjs

@@ -76,9 +76,15 @@ export function collectVaultCost(vaultBase, { since } = {}) {
     try { e = parseSessionCost(readFileSync(f, 'utf8')); } catch { continue; }
     if (!e) continue;
     if (since && e.date && e.date < since) continue;
+    e.file = f.slice(vaultBase.length + 1).replace(/\\/g, '/');
     entries.push(e);
   }
-  return aggregateCosts(entries);
+  const agg = aggregateCosts(entries);
+  // Per-session list (main+sub), most expensive first — powers `cost --top`.
+  agg.sessions = entries
+    .map((e) => ({ file: e.file, date: e.date, cost: round4(e.mainCost + e.subCost) }))
+    .sort((a, b) => b.cost - a.cost);
+  return agg;
 }
 
 function opt(argv, name) {
@@ -97,6 +103,14 @@ export function runCost(argv) {
 
   if (argv.includes('--json')) { process.stdout.write(`${JSON.stringify(agg, null, 2)}\n`); process.exit(0); }
 
+  const topIdx = argv.indexOf('--top');
+  if (topIdx >= 0) {
+    const n = Number(argv[topIdx + 1]) || 10;
+    process.stdout.write(`Sessões mais caras (top ${n} de ${agg.count}):\n`);
+    for (const s of agg.sessions.slice(0, n)) process.stdout.write(`  ${usd(s.cost).padStart(11)}  ${s.date || '?'}  ${s.file}\n`);
+    process.exit(0);
+  }
+
   process.stdout.write(`Custo total (vault): ${usd(agg.total)} — ${agg.count} sessão(ões) · ${usd(agg.avg)}/sessão\n`);
   process.stdout.write(`  main: ${usd(agg.main)} · subagents: ${usd(agg.sub)}\n`);
   if (agg.wasted) process.stdout.write(`  desperdiçado (runs killed/failed): ${usd(agg.wasted)}\n`);

package/src/import.mjs

@@ -0,0 +1,53 @@
+// `wendkeep import` — retroactive memory. Scans this project's Claude Code transcripts and
+// turns every session that isn't already in the vault into a full, dated session note (deduped
+// by session_id). One command backfills your whole history: cost, subagents, iterations.
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { runImport, defaultClaudeProjectsDir } from '../hooks/import-sessions.mjs';
+
+function opt(argv, name) {
+  const i = argv.indexOf(name);
+  if (i >= 0) return argv[i + 1];
+  const eq = argv.find((a) => a.startsWith(`${name}=`));
+  return eq ? eq.slice(name.length + 1) : undefined;
+}
+
+export function runImportCli(argv) {
+  const vaultRaw = opt(argv, '--vault') || process.env.OBSIDIAN_VAULT_PATH;
+  if (!vaultRaw) { process.stderr.write('wendkeep import: no vault (--vault or OBSIDIAN_VAULT_PATH).\n'); process.exit(2); }
+  const vaultBase = isAbsolute(vaultRaw) ? vaultRaw : resolve(process.cwd(), vaultRaw);
+  if (!existsSync(vaultBase)) { process.stderr.write(`wendkeep import: vault not found: ${vaultBase}\n`); process.exit(2); }
+
+  const projectRaw = opt(argv, '--project') || process.cwd();
+  const projectPath = isAbsolute(projectRaw) ? projectRaw : resolve(process.cwd(), projectRaw);
+  const from = opt(argv, '--from') || '';
+  const since = opt(argv, '--since') || '';
+  const limit = Number(opt(argv, '--limit')) || 0;
+  const dryRun = argv.includes('--dry-run');
+
+  const sourceDir = from || defaultClaudeProjectsDir(projectPath);
+  if (!from && (!sourceDir || !existsSync(sourceDir))) {
+    process.stderr.write(`wendkeep import: no Claude transcripts for this project.\n`);
+    process.stderr.write(`  Looked in: ${sourceDir || '(home not resolved)'}\n`);
+    process.stderr.write(`  Pass --from <dir> pointing at .claude/projects/<slug>/ explicitly.\n`);
+    process.exit(2);
+  }
+
+  const report = runImport(vaultBase, { projectPath, from, since, limit, dryRun });
+
+  if (argv.includes('--json')) { process.stdout.write(`${JSON.stringify(report, null, 2)}\n`); process.exit(0); }
+
+  const verb = dryRun ? 'importaria' : 'importadas';
+  process.stdout.write(`Fonte: ${report.dir}\n`);
+  process.stdout.write(`${report.scanned} transcript(s) · ${report.imported} ${verb} · ${report.skipped} já no vault\n`);
+  for (const s of report.sessions) {
+    const tag = s.dryRun ? '(dry-run)' : '→';
+    process.stdout.write(`  ${tag} ${s.sessionId}  ${s.turns} turno(s)${s.relPath ? `  ${s.relPath}` : ''}\n`);
+  }
+  if (report.errors.length) {
+    process.stdout.write(`\n${report.errors.length} com erro (pulados):\n`);
+    for (const e of report.errors) process.stdout.write(`  ${e.sessionId}: ${e.error}\n`);
+  }
+  if (dryRun) process.stdout.write('\nNada foi escrito (--dry-run). Rode sem --dry-run para criar as notas.\n');
+  process.exit(0);
+}

package/src/taxonomy.mjs

@@ -43,6 +43,7 @@ export const HOOK_FILES = [
   'brain-recall.mjs',
   'brain-reindex.mjs',
   'session-backfill.mjs',
+  'import-sessions.mjs',
   'vault-health.mjs',
   'understand-inject.mjs',
 ];
@@ -124,8 +125,11 @@ export const COMPANIONS = [
   },
   {
     id: 'dotcontext',
-    label: 'dotcontext — orquestração de execução (PREVC + sensores + gate E→V)',
-    default: true,
+    // Legacy: wendkeep's native a2 loop (change/verify/gate) recreates dotcontext's role,
+    // so it is no longer recommended — installing it would duplicate the native harness.
+    // Kept selectable for anyone already invested in it; not a default.
+    label: 'dotcontext — legado (o loop a2 nativo do wendkeep substitui; não recomendado)',
+    default: false,
     // MCP-only (no Claude Code plugin). Agent-agnostic server, @latest surface.
     mcp: { key: 'dotcontext', entry: { type: 'stdio', command: 'npx', args: ['-y', '@dotcontext/mcp@latest'], env: {} } },
     // Lifecycle hooks via the pinned CLI; wired by wendkeep (single writer).