wendkeep 0.23.0 → 0.25.0

package/CHANGELOG.md

@@ -4,6 +4,30 @@ 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.25.0] — 2026-07-08
+
+Cost trend/projection + shareable stats + launch assets.
+
+### Added
+- **`wendkeep cost --trend [day|week|month]`** — cost bucketed over time plus a run-rate
+  **projection** (recent-window daily average × horizon). `wendkeep cost --write` generates a
+  `00-Custo.md` trend note in the vault (by-month table + projection + top models). `src/cost.mjs`.
+- **`wendkeep stats`** — one shareable line: sessions · prompts · spend · date span · models
+  (`--json` too). For the npm page, a README badge line, or a post. `src/stats.mjs`.
+- **Launch assets** (`docs/`): README hero (tagline, badges, quickstart, screenshot slot),
+  Show HN / r/ObsidianMD / X post drafts (`docs/20-launch-posts.md`), and a repeatable
+  graph-screenshot guide (`docs/21-graph-screenshot.md`).
+
+## [0.24.0] — 2026-07-08
+
+### Changed
+- **No companion is pre-selected anymore.** `context-mode` was pre-checked (and the
+  non-interactive default); wendkeep is a neutral harness and should not presume a third-party
+  plugin. The interactive picker now starts with **nothing checked**, `init --yes` (and any
+  non-interactive run) installs **no** companions, and `resolveCompanions({})` returns `[]`.
+  Opt in explicitly — interactively (Space) or `--companions context-mode`. `src/taxonomy.mjs`.
+- Prompt/help/README text updated to reflect the empty default.
+
 ## [0.23.0] — 2026-07-08
 
 Vault structure — generated views + housekeeping (audit wave 2).

package/README.md

@@ -1,9 +1,21 @@
 # wendkeep
 
+> **Your AI coding agent forgets every session. wendkeep makes it remember — in the Obsidian vault you already use.**
+
+[![npm](https://img.shields.io/npm/v/wendkeep.svg)](https://www.npmjs.com/package/wendkeep)
 ![test](https://github.com/rogersialves/wendkeep/actions/workflows/test.yml/badge.svg)
+![zero deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen)
+![node](https://img.shields.io/badge/node-%E2%89%A518-blue)
 
 **A persistent‑memory harness for AI coding agents, built on your Obsidian vault.** Every Claude Code / Codex session is captured turn‑by‑turn into local Markdown — with token/cost tracking, auto‑extracted decisions, bugs and learnings, and a curated memory layer injected back at the start of the next session. On top of that memory core sits a native, zero‑dependency **change lifecycle** (spec → change → TDD → sensor‑gated archive) that keeps intent, work and proof wikilinked in one graph. 100% local, open‑core.
 
+```bash
+npm i -D wendkeep && npx wendkeep init      # captures from the next session on
+npx wendkeep import                          # backfill past Claude + Codex sessions
+```
+
+<!-- SCREENSHOT: Obsidian graph of a wendkeep vault (sessions ↔ decisions ↔ bugs ↔ changes). Drop a PNG/GIF at docs/assets/graph.png and reference it here. -->
+
 > Extracted from a system in daily production use: the capture engine, cost tracking and graph wiring are battle‑tested; the cross‑platform installer (`wendkeep init`) and the native change loop are the newer parts. See [`docs/`](https://github.com/rogersialves/wendkeep/tree/main/docs) for the project's strategy and decision log.
 
 ---
@@ -65,7 +77,7 @@ npx wendkeep init --no-companions --no-mcp --yes              # zero companions,
 | `--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). |
+| `--companions <csv>` | Companions to pin: `context-mode,caveman,understand-anything` (default: **none** — opt in explicitly; `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). |

package/bin/wendkeep.mjs

@@ -30,7 +30,7 @@ Usage:
     --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,caveman,understand-anything
-                           (default: context-mode). dotcontext is legacy — the native a2 loop replaces it.
+                           (default: none — opt in explicitly). 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
@@ -48,7 +48,9 @@ Usage:
   wendkeep spec <sub>          Living specs: list | show <capability>.
   wendkeep sensors <sub>       list | add <id> "<command>" [--severity --type --report].
   wendkeep cost [opts]         Aggregate AI-coding spend across the vault's sessions.
-                           --since <date> · --top [N] (priciest sessions) · --json.
+                           --since <date> · --top [N] (priciest) · --trend [day|week|month]
+                           (+ run-rate projection) · --write (generate 00-Custo.md) · --json.
+  wendkeep stats [--vault P]   One shareable line: sessions · prompts · spend · span · models (--json).
   wendkeep import [opts]       Backfill: import this project's past Claude + Codex sessions into
                            the vault (deduped by session_id). --source all|claude|codex (default
                            all) · --stamp-ids (backfill session_id in existing notes) ·
@@ -144,6 +146,11 @@ async function main() {
       runCost(rest);
       break;
     }
+    case 'stats': {
+      const { runStats } = await import('../src/stats.mjs');
+      runStats(rest);
+      break;
+    }
     case 'import': {
       const { runImportCli } = await import('../src/import.mjs');
       runImportCli(rest);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.23.0",
+  "version": "0.25.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

@@ -1,12 +1,16 @@
 // `wendkeep cost` — aggregate AI-coding spend across every session note in the vault.
 // Each session note carries cost in its frontmatter (main + subagents since 0.10.0); this
 // rolls the whole vault up: total, by day, by model. Pure aggregation + a thin CLI.
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
 import { getLocale } from '../hooks/locale.mjs';
 
 const round4 = (n) => Math.round((Number(n) || 0) * 10000) / 10000;
 const usd = (n) => `$${(Number(n) || 0).toFixed(4)}`;
+const today = () => {
+  const d = new Date();
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+};
 
 function fmValue(content, key) {
   const m = content.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'));
@@ -24,6 +28,7 @@ export function parseSessionCost(content) {
     wasted: Number(fmValue(content, 'subagents_wasted_usd')) || 0,
     tokens: Number(fmValue(content, 'tokens_total')) || 0,
     subTokens: Number(fmValue(content, 'subagents_tokens_total')) || 0,
+    prompts: Number(fmValue(content, 'prompts')) || 0,
   };
 }
 
@@ -35,8 +40,9 @@ export function aggregateCosts(entries) {
   let wasted = 0;
   let tokens = 0;
   let subTokens = 0;
+  let prompts = 0;
   for (const e of entries) {
-    main += e.mainCost; sub += e.subCost; wasted += e.wasted || 0; tokens += e.tokens; subTokens += e.subTokens;
+    main += e.mainCost; sub += e.subCost; wasted += e.wasted || 0; tokens += e.tokens; subTokens += e.subTokens; prompts += e.prompts || 0;
     const d = e.date || '?';
     (byDay[d] = byDay[d] || { cost: 0, count: 0 }).cost += e.mainCost + e.subCost;
     byDay[d].count += 1;
@@ -48,12 +54,93 @@ export function aggregateCosts(entries) {
     count: entries.length,
     main: round4(main), sub: round4(sub), total: round4(total), wasted: round4(wasted),
     avg: round4(entries.length ? total / entries.length : 0),
-    tokens, subTokens,
+    tokens, subTokens, prompts,
     byDay: Object.entries(byDay).sort().map(([date, v]) => ({ date, cost: round4(v.cost), count: v.count })),
     byModel: Object.entries(byModel).sort((a, b) => b[1].cost - a[1].cost).map(([model, v]) => ({ model, cost: round4(v.cost), count: v.count })),
   };
 }
 
+// Shift a 'YYYY-MM-DD' string by `delta` days (UTC, pure).
+function shiftDate(dateStr, delta) {
+  const d = new Date(`${dateStr}T00:00:00Z`);
+  d.setUTCDate(d.getUTCDate() + delta);
+  return d.toISOString().slice(0, 10);
+}
+
+// ISO-ish week key 'YYYY-Www' for a 'YYYY-MM-DD' string (pure).
+function isoWeek(dateStr) {
+  const d = new Date(`${dateStr}T00:00:00Z`);
+  const day = (d.getUTCDay() + 6) % 7; // Mon=0
+  d.setUTCDate(d.getUTCDate() - day + 3); // nearest Thursday
+  const firstThu = new Date(Date.UTC(d.getUTCFullYear(), 0, 4));
+  const week = 1 + Math.round(((d - firstThu) / 86400000 - 3 + ((firstThu.getUTCDay() + 6) % 7)) / 7);
+  return `${d.getUTCFullYear()}-W${String(week).padStart(2, '0')}`;
+}
+
+// Group the per-day cost series (agg.byDay) into day|week|month buckets. Pure.
+export function trendBuckets(byDay, bucket = 'month') {
+  const keyOf = (date) => (bucket === 'day' ? date : bucket === 'week' ? isoWeek(date) : String(date).slice(0, 7));
+  const map = {};
+  for (const d of byDay || []) {
+    if (!d.date || d.date === '?') continue;
+    const k = keyOf(d.date);
+    (map[k] = map[k] || { period: k, cost: 0, count: 0 }).cost += d.cost;
+    map[k].count += d.count;
+  }
+  return Object.values(map).sort((a, b) => a.period.localeCompare(b.period)).map((b) => ({ ...b, cost: round4(b.cost) }));
+}
+
+// Run-rate projection from the last `windowDays` of activity. Pure; nowStr = 'YYYY-MM-DD'
+// (defaults to the latest day seen). Honest: a flat run-rate, not a fitted forecast.
+export function projectSpend(byDay, { nowStr, windowDays = 30, horizonDays = 30 } = {}) {
+  const days = (byDay || []).filter((d) => d.date && d.date !== '?');
+  if (!days.length) return { dailyRate: 0, projected: 0, windowDays, horizonDays, basisDays: 0, basisTotal: 0 };
+  const now = nowStr || days[days.length - 1].date;
+  const cutoff = shiftDate(now, -windowDays);
+  const recent = days.filter((d) => d.date > cutoff);
+  const basisTotal = recent.reduce((s, d) => s + d.cost, 0);
+  const dailyRate = basisTotal / windowDays;
+  return { dailyRate: round4(dailyRate), projected: round4(dailyRate * horizonDays), windowDays, horizonDays, basisDays: recent.length, basisTotal: round4(basisTotal) };
+}
+
+// A generated vault note: cost by month + projection + top models. Overwrites (it is generated).
+export function renderTrendNote(agg, proj, dateStr) {
+  const rows = trendBuckets(agg.byDay, 'month').map((b) => `| ${b.period} | ${usd(b.cost)} | ${b.count} |`).join('\n');
+  const models = agg.byModel.slice(0, 8).map((m) => `| ${m.model} | ${usd(m.cost)} | ${m.count} |`).join('\n');
+  return `---
+type: cost-trend
+date: ${dateStr}
+cssclasses:
+  - topic-dashboard
+tags:
+  - custo
+---
+
+# Custo — tendência
+
+> Gerado por \`wendkeep cost --write\`. ${agg.count} sessão(ões) · total ${usd(agg.total)} · ${usd(agg.avg)}/sessão.
+
+## Por mês
+
+| Mês | Custo | Sessões |
+|---|---|---|
+${rows || '| — | — | — |'}
+
+## Projeção (run-rate ${proj.windowDays}d)
+
+Base: ${usd(proj.basisTotal)} nos últimos ${proj.windowDays} dias (${proj.basisDays} dia(s) com atividade) → **${usd(proj.dailyRate)}/dia**.
+Projeção próximos ${proj.horizonDays} dias: **${usd(proj.projected)}**.
+
+> Run-rate simples (média diária × horizonte), não previsão ajustada.
+
+## Por modelo
+
+| Modelo | Custo | Sessões |
+|---|---|---|
+${models || '| — | — | — |'}
+`;
+}
+
 function walkNotes(dir) {
   const out = [];
   let names;
@@ -111,6 +198,24 @@ export function runCost(argv) {
     process.exit(0);
   }
 
+  const trendIdx = argv.indexOf('--trend');
+  if (trendIdx >= 0) {
+    const bucket = ['day', 'week', 'month'].includes(argv[trendIdx + 1]) ? argv[trendIdx + 1] : 'month';
+    const proj = projectSpend(agg.byDay);
+    process.stdout.write(`Tendência de custo (por ${bucket}):\n`);
+    for (const b of trendBuckets(agg.byDay, bucket)) process.stdout.write(`  ${b.period}  ${usd(b.cost).padStart(11)}  (${b.count})\n`);
+    process.stdout.write(`\nRun-rate ${proj.windowDays}d: ${usd(proj.dailyRate)}/dia · projeção ${proj.horizonDays}d: ${usd(proj.projected)} (base ${usd(proj.basisTotal)} em ${proj.basisDays} dia(s))\n`);
+    process.exit(0);
+  }
+
+  if (argv.includes('--write')) {
+    const proj = projectSpend(agg.byDay);
+    const rel = '00-Custo.md';
+    writeFileSync(join(vaultBase, rel), renderTrendNote(agg, proj, today()), 'utf8');
+    process.stdout.write(`cost --write: ${rel} (nota de tendência gerada)\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/init.mjs

@@ -207,13 +207,13 @@ function installVaultColors(vaultPath) {
 const PROMPTS = {
   'pt-BR': {
     vault: (f) => `Caminho do vault Obsidian (Enter aceita o padrão, ou digite outro)\n  [${f}]\n> `,
-    companionsHeader: '\nCompanions (plugins/MCP opcionais — context-mode é a principal):',
+    companionsHeader: '\nCompanions (plugins/MCP opcionais — nenhum vem pré-marcado):',
     companionsAsk: (def) => `Digite os ids separados por vírgula (Enter aceita [${def}], "none" p/ nenhum): `,
     menu: { hint: 'Espaço marca/desmarca · ↑/↓ move · a=todos · n=nenhum · Enter confirma', header: 'Companions' },
   },
   en: {
     vault: (f) => `Obsidian vault path (Enter for the default, or type another)\n  [${f}]\n> `,
-    companionsHeader: '\nCompanions (optional plugins/MCP — context-mode is the main one):',
+    companionsHeader: '\nCompanions (optional plugins/MCP — none pre-selected):',
     companionsAsk: (def) => `Enter ids comma-separated (Enter for [${def}], "none" for none): `,
     menu: { hint: 'Space toggles · ↑/↓ move · a=all · n=none · Enter confirms', header: 'Companions' },
   },

package/src/stats.mjs

@@ -0,0 +1,45 @@
+// `wendkeep stats` — one shareable line about what the vault has captured. For the npm page,
+// a README badge line, or a tweet. Read-only; reuses the cost aggregation.
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { collectVaultCost } from './cost.mjs';
+
+const usd = (n) => `$${(Number(n) || 0).toFixed(2)}`;
+const num = (n) => String(Math.round(Number(n) || 0)).replace(/\B(?=(\d{3})+(?!\d))/g, '.');
+
+// Pure: derive the shareable stats from a collectVaultCost aggregate.
+export function statsFrom(agg) {
+  const days = (agg.byDay || []).map((d) => d.date).filter((d) => d && d !== '?').sort();
+  return {
+    sessions: agg.count,
+    prompts: agg.prompts || 0,
+    cost: agg.total,
+    models: (agg.byModel || []).length,
+    firstDay: days[0] || '',
+    lastDay: days[days.length - 1] || '',
+    spanDays: days.length,
+  };
+}
+
+export function statsLine(s) {
+  const span = s.firstDay && s.lastDay ? ` · ${s.spanDays} dia(s) (${s.firstDay}→${s.lastDay})` : '';
+  return `wendkeep: ${num(s.sessions)} sessão(ões) · ${num(s.prompts)} prompts · ${usd(s.cost)} capturado${span} · ${s.models} modelo(s)`;
+}
+
+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 runStats(argv) {
+  const vaultRaw = opt(argv, '--vault') || process.env.OBSIDIAN_VAULT_PATH;
+  if (!vaultRaw) { process.stderr.write('wendkeep stats: 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 stats: vault not found: ${vaultBase}\n`); process.exit(2); }
+  const s = statsFrom(collectVaultCost(vaultBase));
+  if (argv.includes('--json')) { process.stdout.write(`${JSON.stringify(s, null, 2)}\n`); process.exit(0); }
+  process.stdout.write(`${statsLine(s)}\n`);
+  process.exit(0);
+}

package/src/taxonomy.mjs

@@ -102,8 +102,10 @@ export function hookCommand(name) {
 export const COMPANIONS = [
   {
     id: 'context-mode',
-    label: 'context-mode — otimizador de contexto + memória FTS5 (principal)',
-    default: true,
+    label: 'context-mode — otimizador de contexto + memória FTS5 (opcional)',
+    // Not a default: wendkeep is a neutral harness and does not presume a third-party plugin.
+    // Opt in interactively or with `--companions context-mode`.
+    default: false,
     marketplace: { source: 'git', url: 'https://github.com/mksglu/context-mode.git' },
     plugin: 'context-mode',
     // Agent-agnostic: MCP server, self-updating via unpinned npx.