projectinator 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stepan Manookian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+<p align="center">
+  <img src="docs/logo.svg" alt="Projectinator" width="112" />
+</p>
+
+# Projectinator
+
+![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
+![tests: 134 passing](https://img.shields.io/badge/tests-134%20passing-brightgreen.svg)
+![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6.svg)
+![built on Pi](https://img.shields.io/badge/built%20on-Pi%20agent%20harness-e0a72d.svg)
+
+**You're the PM. Your dev team is a roster of AI models.** Hand Projectinator an idea; a
+project-manager model breaks it into a Scrum backlog, and each task is dispatched to the
+model that's best — and cheapest — for that exact job (planning, design, code, test). You
+watch it happen from a terminal cockpit: a live board, budget bar, and a standup.
+
+Built on the [Pi](https://pi.dev) agent harness (Node/TypeScript). Bring your own API key.
+
+**Run it — no clone needed** (Node ≥ 20):
+
+```bash
+npx github:smanookian/projectinator
+```
+
+Then, inside the app: **Settings → API keys** and paste an Anthropic, OpenAI, or Gemini key
+(stored at `~/.projectinator`, never in the repo). That's it — pick **New build** and go.
+
+<details>
+<summary>Run from source instead</summary>
+
+```bash
+git clone https://github.com/smanookian/projectinator && cd projectinator
+npm install
+npm start
+```
+</details>
+
+> **Optional:** `npx playwright install chromium` lets the tester actually run web apps in a
+> headless browser and enables live preview. Everything else works without it.
+
+> Projectinator spends **your** API money. Every screen shows the running cost; you set a
+> budget cap and it halts before crossing it. A tiny landing page is cents; a full app is
+> usually a dollar or two.
+
+---
+
+## What it does
+
+Type an idea → it plans → you approve → it builds, tests, and hands you working files.
+
+- **Best model per role.** Roles bind to a *capability + tier*, never a model name. A
+  swappable registry maps capabilities to models — new frontier model next month, edit one
+  place, every route updates. Run a **bake-off** to pick empirically.
+- **A real pipeline.** PM decomposes → Designer specs → Developer writes files → Tester
+  **runs the app headless and catches real bugs** → feedback loop re-runs the dev on failure.
+- **Multi-file apps.** Vanilla HTML/CSS/JS or **React (CDN, no build)** — your choice.
+- **The cockpit.** A polished terminal UI: editable board, Kanban, standup, per-task cost,
+  live budget bar, desktop notification when done.
+- **Honest cost.** Live spend tracking, per-project budget cap + an alert before the cap,
+  and predicted-vs-actual reporting that sharpens itself over real runs.
+
+## Highlights
+
+| | |
+|---|---|
+| 🧠 **PM intake** | Vague request? The PM asks 2–4 clarifying questions (with pickable options) before planning. Specific requests skip straight through. |
+| 🏛 **Deep plan (council)** | Opt-in: architect + product + risk leads propose epics in parallel, a synthesizer merges them, you approve, then they expand into the backlog. |
+| 🆚 **Model bake-off** | Run one task across models, an LLM judge scores the outputs, compare cost/latency/quality — save the winner to the registry. |
+| 🧪 **Real test execution** | The tester loads the built app in headless Chromium and fails on JS/console errors — not just by reading the code. |
+| 👁 **Live preview** | Local server + auto-reload; ES modules and fetch resolve like production. |
+| 🚀 **Deploy** | One click to Cloudflare Pages, Vercel, or Netlify (their CLI + your login). |
+| 📤 **Export** | Backlog → Markdown, CSV, **Jira** CSV, **Trello** CSV. |
+| 📜 **Git per build** | The workspace is a git repo; one commit per task. History view + **undo a task**. |
+| 📊 **Analytics** | Retro (with optional AI narrative), burndown, cost-by-epic/model, estimate accuracy, portfolio dashboard. |
+| 💾 **Templates** | Save a project's brief as a reusable template; import/share as a file. |
+
+## How it works
+
+```
+idea
+ └─ stack?      pick platform + framework (or a saved default)
+ └─ intake?     PM asks clarifying questions if the request is vague
+ └─ plan mode?  Quick (one PM) or Deep (planning council → approve epics)
+ └─ decompose   → a routed, epic-tagged backlog with a cost estimate
+ └─ approve     → auto-run, or gate the backlog / gate again before dev
+ └─ build       toposort deps · design → code → test · Tester→Dev feedback loop
+ └─ done        working files + retro + deploy/export/preview
+```
+
+Each task runs on a real Pi session; Pi reports its own token usage and dollar cost, so
+"actual" cost is authoritative. Estimates live in code (models are bad at guessing their own
+token use) and **self-calibrate** from measured runs.
+
+## Examples
+
+Real, unedited output from a full build, kept in [`examples/`](examples/):
+
+- **[Tip calculator](examples/tip-calculator/)** — PM → design → 3× code → test, $0.46,
+  tester PASS. Three separate files (`index.html`, `styles.css`, `app.js`) that run on
+  double-click (`file://`) *and* over http — the regression artifact for the
+  ["runs on double-click" guarantee](#caveats-read-before-shipping-publicly).
+
+## CLI (same engine, for scripting/CI)
+
+```bash
+npm start                                         # the cockpit (the normal way to use it)
+npm run build -- --live --mini                    # cheap end-to-end proof (~$0.10)
+npm run build -- --live --lock anthropic "idea"   # full pipeline on one provider
+npm run build -- --live --mini --resume           # resume a halted/finished build (skips done tasks)
+npm run bakeoff -- --capability design "Design a pricing page"   # model bake-off
+npm test                                          # 134 tests
+npm run typecheck
+```
+
+## Configuration & data
+
+- **Keys** are stored at `~/.projectinator/config.json` (chmod 0600) — never in the repo.
+- **Settings** (in the app): API keys, preferred provider, default workflow, default stack,
+  model assignments, budget cap + alert %, estimate accuracy.
+- **User data** lives under `~/.projectinator/` (config, calibration, templates, exports).
+  Builds go to `.workspace/` in the repo.
+
+## Caveats (read before shipping publicly)
+
+- **It spends your API money.** The cost tracking is honest; keep it visible.
+- **Web-login is experimental and parked.** Driving your paid ChatGPT/Claude/Gemini *web*
+  subscriptions violates those providers' ToS and risks your account — vendors actively
+  enforce this. It is hidden behind `PROJECTINATOR_WEB=1` and should stay that way. Use the
+  API-key path.
+- **React = CDN, no build step** (runs by opening `index.html`). Vite/npm builds and
+  mobile/desktop toolchains are future work.
+
+## License
+
+MIT — see [LICENSE](LICENSE). © 2026 Stepan Manookian.
+
+## Roadmap
+
+See [`TODO.md`](./TODO.md). Internal architecture + how-to: [`docs/INTERNAL.md`](./docs/INTERNAL.md).

package/bin/projectinator.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// Launcher for `projectinator` / `npx github:smanookian/projectinator`.
+// Runs the Ink TUI (TypeScript) through tsx — no build step, no compiled dist.
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const entry = join(root, "src", "tui.tsx");
+
+// `node --import tsx <entry>` registers tsx's loader, then runs the TS entry.
+const res = spawnSync(process.execPath, ["--import", "tsx", entry], {
+  stdio: "inherit",
+  cwd: root,
+});
+
+if (res.error) {
+  console.error("Failed to launch Projectinator:", res.error.message);
+  process.exit(1);
+}
+process.exit(res.status ?? 0);

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "projectinator",
+  "version": "0.1.0",
+  "description": "Your AI build team in the terminal — hand it an app idea, a PM model plans a Scrum backlog, and the best model per role designs, codes, and tests it into working files. Bring your own API key.",
+  "type": "module",
+  "private": false,
+  "license": "MIT",
+  "author": "Stepan Manookian",
+  "homepage": "https://github.com/smanookian/projectinator#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/smanookian/projectinator.git"
+  },
+  "bugs": {
+    "url": "https://github.com/smanookian/projectinator/issues"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "cli",
+    "tui",
+    "ink",
+    "agent",
+    "scrum",
+    "code-generation",
+    "app-builder",
+    "anthropic",
+    "openai",
+    "gemini"
+  ],
+  "bin": {
+    "projectinator": "bin/projectinator.mjs"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "start": "tsx src/tui.tsx",
+    "prepublishOnly": "npm run typecheck && npm test",
+    "demo": "tsx src/demo.ts",
+    "dev:task": "tsx src/run-dev.ts",
+    "pm": "tsx src/run-pm.ts",
+    "build": "tsx src/run-build.ts",
+    "scout": "tsx src/run-scout.ts",
+    "research": "tsx src/run-research.ts",
+    "web": "tsx src/run-web.ts",
+    "bakeoff": "tsx src/run-bakeoff.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.2.17",
+    "ink-testing-library": "^4.0.0",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "0.80.7",
+    "@inkjs/ui": "2.0.0",
+    "ink": "7.1.0",
+    "ink-spinner": "5.0.0",
+    "playwright": "1.61.1",
+    "react": "19.2.7",
+    "tsx": "4.23.1",
+    "typebox": "1.1.38"
+  }
+}

package/src/bakeoff.ts

@@ -0,0 +1,220 @@
+// Model bake-off — the founding idea: run ONE task across several models, then
+// compare cost, latency, and quality so you can pick the best model per role and
+// feed that back into the routing registry.
+//
+// v1 covers TEXT roles (plan, design, test-reasoning) where the deliverable is
+// text a judge can score. Code bake-off (per-candidate sandbox + real test
+// scoring) is a later step.
+
+import {
+  AuthStorage,
+  ModelRegistry,
+  createAgentSession,
+  defineTool,
+  type AgentSession,
+} from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import type { Capability, Difficulty, Provider, Task } from "./types.js";
+import { resolvePiModel } from "./executor.js";
+import { buildRolePrompt } from "./roles.js";
+import { estimateTokens } from "./estimate.js";
+import { addSessionCost } from "./session-cost.js";
+
+export interface Candidate {
+  provider: Provider;
+  model: string;
+}
+
+export interface BakeoffEntry {
+  provider: Provider;
+  model: string;
+  output: string;
+  cost: number;
+  ms: number;
+  outputTokens: number;
+  error?: string;
+}
+
+export interface JudgeScore {
+  model: string;
+  score: number; // 0-10
+  reason: string;
+}
+
+export interface BakeoffResult {
+  task: Task;
+  entries: BakeoffEntry[];
+  scores: JudgeScore[];
+  winner?: string; // "provider/model"
+  judge?: string; // judge model id
+}
+
+function lastAssistantText(session: AgentSession): string {
+  const msgs = session.messages as Array<{ role?: string; content?: unknown }>;
+  for (let i = msgs.length - 1; i >= 0; i--) {
+    const m = msgs[i];
+    if (m?.role !== "assistant") continue;
+    const c = m.content;
+    if (typeof c === "string") return c;
+    if (Array.isArray(c)) {
+      return c
+        .map((p: unknown) => (typeof p === "string" ? p : p && typeof p === "object" && "text" in p ? String((p as { text: unknown }).text) : ""))
+        .join("")
+        .trim();
+    }
+  }
+  return "";
+}
+
+const id = (c: Candidate) => `${c.provider}/${c.model}`;
+
+/** Run one candidate on the task, capturing output, cost, and latency. */
+async function runCandidate(task: Task, cand: Candidate): Promise<BakeoffEntry> {
+  const base: BakeoffEntry = { provider: cand.provider, model: cand.model, output: "", cost: 0, ms: 0, outputTokens: 0 };
+  try {
+    const authStorage = AuthStorage.create();
+    const registry = ModelRegistry.create(authStorage);
+    const model = resolvePiModel(registry, cand.provider, cand.model);
+    const { session } = await createAgentSession({
+      model,
+      authStorage,
+      modelRegistry: registry,
+      thinkingLevel: "medium",
+      noTools: "all",
+    });
+    try {
+      const t0 = Date.now();
+      await session.prompt(buildRolePrompt(task, ""));
+      const ms = Date.now() - t0;
+      const stats = session.getSessionStats();
+      addSessionCost(stats.cost);
+      const out: BakeoffEntry = {
+        ...base,
+        output: lastAssistantText(session),
+        cost: Math.round(stats.cost * 10000) / 10000,
+        ms,
+        outputTokens: stats.tokens.output,
+      };
+      if (stats.tokens.total === 0) out.error = "returned 0 tokens (key likely can't access this model)";
+      return out;
+    } finally {
+      session.dispose(); // dispose even when prompt() throws (expected for inaccessible models)
+    }
+  } catch (e) {
+    return { ...base, error: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+// ---- judge: score every output on one rubric, forced structured output ----
+
+const JudgeSchema = Type.Object(
+  {
+    scores: Type.Array(
+      Type.Object({
+        option: Type.String({ description: "the option letter, e.g. A" }),
+        score: Type.Number({ description: "0-10 quality for this deliverable" }),
+        reason: Type.String({ description: "one sentence" }),
+      }),
+    ),
+    winner: Type.String({ description: "the option letter of the best output" }),
+  },
+  { additionalProperties: true },
+);
+type JudgeRaw = Static<typeof JudgeSchema>;
+
+function buildJudgeTool() {
+  let captured: JudgeRaw | undefined;
+  const tool = defineTool({
+    name: "submit_scores",
+    label: "Submit Scores",
+    description: "Submit a 0-10 quality score and one-sentence reason for every option, plus the winning option letter.",
+    parameters: JudgeSchema,
+    execute: async (_id, params: JudgeRaw) => {
+      captured = params;
+      return { content: [{ type: "text", text: `Scored ${params.scores.length} options; winner ${params.winner}.` }], details: {} };
+    },
+  });
+  return { tool, get: () => captured };
+}
+
+/** Judge anonymised outputs (A, B, C…) on one rubric for the task's capability. */
+async function judge(task: Task, entries: BakeoffEntry[], judgeCand: Candidate): Promise<{ scores: JudgeScore[]; winner?: string; judgeId: string }> {
+  const scored = entries.filter((e) => !e.error && e.output);
+  if (scored.length < 2) return { scores: [], winner: undefined, judgeId: id(judgeCand) };
+
+  const letters = scored.map((_, i) => String.fromCharCode(65 + i)); // A, B, C…
+  const blocks = scored.map((e, i) => `### Option ${letters[i]}\n${e.output}`).join("\n\n");
+  const authStorage = AuthStorage.create();
+  const registry = ModelRegistry.create(authStorage);
+  const model = resolvePiModel(registry, judgeCand.provider, judgeCand.model);
+  const { tool, get } = buildJudgeTool();
+  const { session } = await createAgentSession({
+    model,
+    authStorage,
+    modelRegistry: registry,
+    thinkingLevel: "medium",
+    noTools: "all",
+    customTools: [tool],
+    tools: ["submit_scores"],
+  });
+
+  const prompt = [
+    `You are judging ${scored.length} anonymous attempts at the same ${task.capability} task. Be a strict, fair critic.`,
+    `Task: ${task.title}`,
+    "",
+    `Score each option 0-10 on how well it delivers a high-quality ${task.capability} result (correctness, completeness, clarity, usefulness). Then pick the single best.`,
+    "Call submit_scores exactly once with a score+reason for EVERY option letter and the winner.",
+    "",
+    blocks,
+  ].join("\n");
+
+  try {
+    await session.prompt(prompt);
+    let raw = get();
+    for (let i = 0; i < 2 && !raw; i++) {
+      await session.prompt("Call submit_scores now with a score for every option letter and the winner.");
+      raw = get();
+    }
+    addSessionCost(session.getSessionStats().cost);
+    if (!raw) return { scores: [], winner: undefined, judgeId: id(judgeCand) };
+
+    const byLetter = new Map(letters.map((l, i) => [l, scored[i]!]));
+    const scores: JudgeScore[] = raw.scores
+      .map((s) => {
+        const e = byLetter.get(s.option.trim().toUpperCase().slice(0, 1));
+        return e ? { model: id(e), score: s.score, reason: s.reason } : undefined;
+      })
+      .filter((x): x is JudgeScore => !!x);
+    const winEntry = byLetter.get(String(raw.winner).trim().toUpperCase().slice(0, 1));
+    return { scores, winner: winEntry ? id(winEntry) : undefined, judgeId: id(judgeCand) };
+  } finally {
+    session.dispose();
+  }
+}
+
+export interface BakeoffOptions {
+  /** Model that scores the outputs. Defaults to the first candidate. */
+  judge?: Candidate;
+  onProgress?: (msg: string) => void;
+}
+
+/** Run the full bake-off: every candidate on the task, then judge. */
+export async function runBakeoff(task: Task, candidates: Candidate[], opts: BakeoffOptions = {}): Promise<BakeoffResult> {
+  const log = opts.onProgress ?? (() => {});
+  const entries: BakeoffEntry[] = [];
+  for (const c of candidates) {
+    log(`running ${id(c)}…`);
+    const e = await runCandidate(task, c);
+    log(e.error ? `  ${id(c)}: ERROR ${e.error}` : `  ${id(c)}: $${e.cost.toFixed(4)}  ${(e.ms / 1000).toFixed(1)}s  ${e.outputTokens} tok`);
+    entries.push(e);
+  }
+  const judgeCand = opts.judge ?? candidates[0]!;
+  log(`judging with ${id(judgeCand)}…`);
+  const { scores, winner, judgeId } = await judge(task, entries, judgeCand);
+  return { task, entries, scores, winner, judge: judgeId };
+}
+
+/** Convenience: build a one-off Task for a capability/difficulty from a prompt. */
+export function bakeoffTask(prompt: string, capability: Capability, difficulty: Difficulty = "medium"): Task {
+  return { id: "BAKE", title: prompt, capability, difficulty, dependsOn: [], estTokens: estimateTokens(capability, difficulty) };
+}

package/src/build-state.ts

@@ -0,0 +1,46 @@
+// Build persistence — checkpoint a run so a halt/crash/cancel can resume without
+// re-paying for finished tasks. The orchestrator itself stays fs-free; this module
+// (and run-build) own the disk I/O.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import type { Task, TaskOutcome } from "./types.js";
+
+export interface BuildState {
+  id: string;
+  /** The original idea/request text, for display in the projects list. */
+  idea?: string;
+  /** Workflow used: auto-run, or approval-gated. */
+  mode?: "auto" | "approval";
+  tasks: Task[];
+  /** Full record of every task run, including feedback-loop retries (append-only). */
+  outcomes: TaskOutcome[];
+  totalCost: number;
+  status: "running" | "complete" | "halted";
+  haltReason?: string;
+  /** Per-project budget cap (USD). Overrides the global default when set. */
+  budgetCapUSD?: number;
+  /** Cached AI retro narrative (generated on demand). */
+  retroNarrative?: string;
+}
+
+export function newBuildState(id: string, tasks: Task[], idea?: string, mode?: "auto" | "approval"): BuildState {
+  return { id, idea, mode, tasks, outcomes: [], totalCost: 0, status: "running" };
+}
+
+export function saveState(state: BuildState, path: string): void {
+  writeFileSync(path, JSON.stringify(state, null, 2) + "\n");
+}
+
+export function loadState(path: string): BuildState | undefined {
+  if (!existsSync(path)) return undefined;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as BuildState;
+  } catch (e) {
+    throw new Error(`Bad build state at ${path}: ${e instanceof Error ? e.message : e}`);
+  }
+}
+
+/** Which task ids are already finished (last outcome wins). Used to skip on resume. */
+export function completedIds(state: BuildState): Set<string> {
+  return new Set(state.outcomes.map((o) => o.taskId));
+}

package/src/burndown.ts

@@ -0,0 +1,35 @@
+// Burndown — tasks remaining and cumulative spend across the build. There are no
+// timestamps in build-state, so the X axis is task-completion order (step 1..N),
+// which is the natural timeline for a build. Retries add a step (and cost) without
+// burning down a task, so they show up as flat-remaining / rising-cost.
+
+import type { BuildState } from "./build-state.js";
+
+export interface BurndownStep {
+  taskId: string;
+  remaining: number; // distinct tasks still to do after this step
+  cumCost: number; // cumulative spend through this step
+  retry: boolean; // this step re-ran an already-done task
+}
+
+export interface Burndown {
+  taskCount: number;
+  totalCost: number;
+  steps: BurndownStep[];
+}
+
+const round2 = (n: number) => Math.round(n * 100) / 100;
+
+export function computeBurndown(state: BuildState): Burndown {
+  const taskCount = state.tasks.length;
+  const done = new Set<string>();
+  let cum = 0;
+  const steps: BurndownStep[] = [];
+  for (const o of state.outcomes) {
+    const retry = done.has(o.taskId);
+    done.add(o.taskId);
+    cum += o.cost;
+    steps.push({ taskId: o.taskId, remaining: taskCount - done.size, cumCost: round2(cum), retry });
+  }
+  return { taskCount, totalCost: round2(cum), steps };
+}

package/src/calibration.ts

@@ -0,0 +1,88 @@
+// Self-calibrating token estimates. After each real task, we record its measured
+// token usage per (capability, difficulty). estimateTokens uses the running average
+// once there are enough samples, so estimates sharpen with use. Persisted globally.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { Capability, Difficulty } from "./types.js";
+
+interface Sample {
+  input: number; // total input tokens (fresh + cache-read)
+  output: number;
+  cachedFraction: number; // share of input served from cache
+  n: number; // sample count (capped so recent runs still move the average)
+}
+
+type Calibration = Record<string, Sample>;
+
+const MIN_SAMPLES = 2; // trust calibration only after a couple of runs
+const MAX_N = 20; // cap so old runs don't dominate
+
+function calPath(): string {
+  return join(homedir(), ".projectinator", "calibration.json");
+}
+const key = (c: Capability, d: Difficulty) => `${c}/${d}`;
+
+function load(): Calibration {
+  try {
+    if (!existsSync(calPath())) return {};
+    return JSON.parse(readFileSync(calPath(), "utf-8")) as Calibration;
+  } catch {
+    return {};
+  }
+}
+
+function save(cal: Calibration): void {
+  try {
+    mkdirSync(join(homedir(), ".projectinator"), { recursive: true });
+    writeFileSync(calPath(), JSON.stringify(cal, null, 2) + "\n");
+  } catch {
+    /* best effort — never break a build on a calibration write */
+  }
+}
+
+/** Fold a real measurement into the running average for its bucket. */
+export function recordActual(
+  capability: Capability,
+  difficulty: Difficulty,
+  inputTotal: number,
+  output: number,
+  cachedFraction: number,
+): void {
+  if (!(inputTotal > 0)) return;
+  const cal = load();
+  const k = key(capability, difficulty);
+  const prev = cal[k];
+  if (!prev) {
+    cal[k] = { input: inputTotal, output, cachedFraction, n: 1 };
+  } else {
+    const n = Math.min(prev.n, MAX_N);
+    cal[k] = {
+      input: (prev.input * n + inputTotal) / (n + 1),
+      output: (prev.output * n + output) / (n + 1),
+      cachedFraction: (prev.cachedFraction * n + cachedFraction) / (n + 1),
+      n: prev.n + 1,
+    };
+  }
+  save(cal);
+}
+
+/** All recorded samples keyed "capability/difficulty" (for the accuracy view). */
+export function allSamples(): Record<string, { input: number; output: number; cachedFraction: number; n: number }> {
+  return load();
+}
+
+/** Calibrated estimate for a bucket, once enough samples exist. */
+export function calibratedTokens(
+  capability: Capability,
+  difficulty: Difficulty,
+): { input: number; output: number; cachedInputFraction: number } | undefined {
+  const s = load()[key(capability, difficulty)];
+  if (!s || s.n < MIN_SAMPLES) return undefined;
+  return {
+    input: Math.round(s.input),
+    output: Math.round(s.output),
+    cachedInputFraction: Math.min(0.95, Math.max(0, s.cachedFraction)),
+  };
+}