useathena 0.1.0

package/dist/store/store.js

@@ -0,0 +1,269 @@
+import { DatabaseSync } from "node:sqlite";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+/**
+ * The single storage truth: one SQLite file per workspace.
+ * Domain invariants live at this boundary:
+ * - instances are immutable (no overwrite),
+ * - hypotheses cannot exist without supporting evidence.
+ * FTS5 gives the lexical retrieval lane; embeddings are a later, optional lane.
+ */
+const SEARCH_TEXT_CAP = 100_000;
+export class AthenaStore {
+    db;
+    constructor(path) {
+        if (path !== ":memory:")
+            mkdirSync(dirname(path), { recursive: true });
+        this.db = new DatabaseSync(path);
+        this.db.exec("PRAGMA journal_mode = WAL;");
+        this.migrate();
+    }
+    close() {
+        this.db.close();
+    }
+    migrate() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS instances (
+        id TEXT PRIMARY KEY, kind TEXT NOT NULL, domain TEXT NOT NULL,
+        actor_id TEXT NOT NULL, observed_at TEXT NOT NULL, data TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_instances_domain ON instances(domain, observed_at);
+      CREATE TABLE IF NOT EXISTS hypotheses (
+        id TEXT PRIMARY KEY, status TEXT NOT NULL, domain TEXT NOT NULL,
+        created_at TEXT NOT NULL, data TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_hypotheses_status ON hypotheses(status, domain);
+      CREATE TABLE IF NOT EXISTS sources (
+        id TEXT PRIMARY KEY, kind TEXT NOT NULL, access_state TEXT NOT NULL,
+        captured_at TEXT NOT NULL, data TEXT NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS objects (
+        id TEXT PRIMARY KEY, kind TEXT NOT NULL, name TEXT NOT NULL, data TEXT NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS object_aliases (
+        alias TEXT NOT NULL, object_id TEXT NOT NULL, PRIMARY KEY (alias, object_id)
+      );
+      CREATE TABLE IF NOT EXISTS relations (
+        from_id TEXT NOT NULL, to_id TEXT NOT NULL, kind TEXT NOT NULL,
+        valid_from TEXT NOT NULL, data TEXT NOT NULL,
+        PRIMARY KEY (from_id, to_id, kind, valid_from)
+      );
+      CREATE TABLE IF NOT EXISTS outcomes (
+        id TEXT PRIMARY KEY, brief_id TEXT NOT NULL, recorded_at TEXT NOT NULL, data TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_outcomes_brief ON outcomes(brief_id);
+      CREATE TABLE IF NOT EXISTS briefs (
+        id TEXT PRIMARY KEY, compiled_at TEXT NOT NULL, data TEXT NOT NULL
+      );
+      CREATE VIRTUAL TABLE IF NOT EXISTS search_index USING fts5(ref, lane, text);
+    `);
+    }
+    // --- instances (immutable) ---
+    saveInstance(instance) {
+        const existing = this.db
+            .prepare("SELECT id FROM instances WHERE id = ?")
+            .get(instance.id);
+        if (existing) {
+            throw new Error(`instance ${instance.id} already exists — instances are immutable`);
+        }
+        this.db
+            .prepare("INSERT INTO instances (id, kind, domain, actor_id, observed_at, data) VALUES (?, ?, ?, ?, ?, ?)")
+            .run(instance.id, instance.kind, instance.situation.domain, instance.actorId, instance.observedAt, JSON.stringify(instance));
+        this.index(`athena://instance/${instance.id}`, "instance", instanceSearchText(instance));
+    }
+    getInstance(id) {
+        return this.getData("instances", id);
+    }
+    listInstances(filter = {}) {
+        const where = [];
+        const params = [];
+        if (filter.kind) {
+            where.push("kind = ?");
+            params.push(filter.kind);
+        }
+        if (filter.domain) {
+            where.push("domain = ?");
+            params.push(filter.domain);
+        }
+        if (filter.actorId) {
+            where.push("actor_id = ?");
+            params.push(filter.actorId);
+        }
+        if (filter.since) {
+            where.push("observed_at >= ?");
+            params.push(filter.since);
+        }
+        const sql = `SELECT data FROM instances ${where.length ? `WHERE ${where.join(" AND ")}` : ""}
+      ORDER BY observed_at DESC LIMIT ${filter.limit ?? 200}`;
+        return this.db.prepare(sql).all(...params).map((rowData));
+    }
+    // --- hypotheses (revisable views over evidence) ---
+    saveHypothesis(hypothesis) {
+        if (hypothesis.supportingInstanceIds.length === 0) {
+            throw new Error(`hypothesis ${hypothesis.id} has no supporting instances — everything cites`);
+        }
+        this.upsert("hypotheses", "INSERT INTO hypotheses (id, status, domain, created_at, data) VALUES (?, ?, ?, ?, ?) " +
+            "ON CONFLICT(id) DO UPDATE SET status = excluded.status, domain = excluded.domain, data = excluded.data", [hypothesis.id, hypothesis.status, hypothesis.domain, hypothesis.createdAt, JSON.stringify(hypothesis)]);
+        this.index(`athena://hypothesis/${hypothesis.id}`, "hypothesis", hypothesisSearchText(hypothesis));
+    }
+    getHypothesis(id) {
+        return this.getData("hypotheses", id);
+    }
+    listHypotheses(filter = {}) {
+        const where = [];
+        const params = [];
+        if (filter.status) {
+            where.push("status = ?");
+            params.push(filter.status);
+        }
+        if (filter.domain) {
+            where.push("domain = ?");
+            params.push(filter.domain);
+        }
+        const sql = `SELECT data FROM hypotheses ${where.length ? `WHERE ${where.join(" AND ")}` : ""}
+      ORDER BY created_at DESC LIMIT ${filter.limit ?? 200}`;
+        return this.db.prepare(sql).all(...params).map((rowData));
+    }
+    // --- explicit layer ---
+    saveSource(source) {
+        this.upsert("sources", "INSERT INTO sources (id, kind, access_state, captured_at, data) VALUES (?, ?, ?, ?, ?) " +
+            "ON CONFLICT(id) DO UPDATE SET access_state = excluded.access_state, data = excluded.data", [source.id, source.kind, source.accessState, source.capturedAt, JSON.stringify(source)]);
+        this.index(`athena://source/${source.id}`, "source", `${source.title}\n${source.content.slice(0, SEARCH_TEXT_CAP)}`);
+    }
+    getSource(id) {
+        return this.getData("sources", id);
+    }
+    saveObject(object) {
+        this.upsert("objects", "INSERT INTO objects (id, kind, name, data) VALUES (?, ?, ?, ?) " +
+            "ON CONFLICT(id) DO UPDATE SET kind = excluded.kind, name = excluded.name, data = excluded.data", [object.id, object.kind, object.name, JSON.stringify(object)]);
+        this.db.prepare("DELETE FROM object_aliases WHERE object_id = ?").run(object.id);
+        const insertAlias = this.db.prepare("INSERT OR IGNORE INTO object_aliases (alias, object_id) VALUES (?, ?)");
+        for (const alias of [object.name, ...object.aliases]) {
+            insertAlias.run(alias.toLowerCase(), object.id);
+        }
+    }
+    getObject(id) {
+        return this.getData("objects", id);
+    }
+    listObjects(kind) {
+        const sql = kind
+            ? "SELECT data FROM objects WHERE kind = ? ORDER BY name"
+            : "SELECT data FROM objects ORDER BY name";
+        const rows = kind ? this.db.prepare(sql).all(kind) : this.db.prepare(sql).all();
+        return rows.map((rowData));
+    }
+    resolveObject(alias) {
+        return this.db
+            .prepare("SELECT o.data FROM object_aliases a JOIN objects o ON o.id = a.object_id WHERE a.alias = ?")
+            .all(alias.toLowerCase())
+            .map((rowData));
+    }
+    saveRelation(relation) {
+        this.db
+            .prepare("INSERT INTO relations (from_id, to_id, kind, valid_from, data) VALUES (?, ?, ?, ?, ?) " +
+            "ON CONFLICT(from_id, to_id, kind, valid_from) DO UPDATE SET data = excluded.data")
+            .run(relation.fromId, relation.toId, relation.kind, relation.validFrom, JSON.stringify(relation));
+    }
+    listRelations(objectId) {
+        return this.db
+            .prepare("SELECT data FROM relations WHERE from_id = ? OR to_id = ?")
+            .all(objectId, objectId)
+            .map((rowData));
+    }
+    // --- serving layer ---
+    saveBrief(brief) {
+        this.upsert("briefs", "INSERT INTO briefs (id, compiled_at, data) VALUES (?, ?, ?) ON CONFLICT(id) DO UPDATE SET data = excluded.data", [brief.id, brief.compiledAt, JSON.stringify(brief)]);
+    }
+    getBrief(id) {
+        return this.getData("briefs", id);
+    }
+    saveOutcome(outcome) {
+        this.upsert("outcomes", "INSERT INTO outcomes (id, brief_id, recorded_at, data) VALUES (?, ?, ?, ?) " +
+            "ON CONFLICT(id) DO UPDATE SET data = excluded.data", [outcome.id, outcome.briefId, outcome.recordedAt, JSON.stringify(outcome)]);
+    }
+    getOutcome(id) {
+        return this.getData("outcomes", id);
+    }
+    listOutcomes(briefId) {
+        const rows = briefId
+            ? this.db.prepare("SELECT data FROM outcomes WHERE brief_id = ? ORDER BY recorded_at DESC").all(briefId)
+            : this.db.prepare("SELECT data FROM outcomes ORDER BY recorded_at DESC").all();
+        return rows.map((rowData));
+    }
+    // --- stats ---
+    counts() {
+        const byColumn = (table, column) => {
+            const rows = this.db
+                .prepare(`SELECT ${column} AS key, COUNT(*) AS n FROM ${table} GROUP BY ${column}`)
+                .all();
+            return Object.fromEntries(rows.map((row) => [row.key, row.n]));
+        };
+        const total = (table) => this.db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get().n;
+        return {
+            instances: byColumn("instances", "kind"),
+            hypotheses: byColumn("hypotheses", "status"),
+            sources: total("sources"),
+            outcomes: total("outcomes"),
+            briefs: total("briefs"),
+        };
+    }
+    // --- search (lexical lane) ---
+    search(query, lane, limit = 20) {
+        const match = ftsQuery(query);
+        if (!match)
+            return [];
+        const rows = lane
+            ? this.db
+                .prepare("SELECT ref, lane, rank FROM search_index WHERE search_index MATCH ? AND lane = ? ORDER BY rank LIMIT ?")
+                .all(match, lane, limit)
+            : this.db
+                .prepare("SELECT ref, lane, rank FROM search_index WHERE search_index MATCH ? ORDER BY rank LIMIT ?")
+                .all(match, limit);
+        return rows.map((row) => {
+            const r = row;
+            return { ref: r.ref, lane: r.lane, score: -r.rank };
+        });
+    }
+    // --- helpers ---
+    upsert(_table, sql, params) {
+        this.db.prepare(sql).run(...params);
+    }
+    getData(table, id) {
+        const row = this.db.prepare(`SELECT data FROM ${table} WHERE id = ?`).get(id);
+        return row ? rowData(row) : undefined;
+    }
+    index(ref, lane, text) {
+        this.db.prepare("DELETE FROM search_index WHERE ref = ?").run(ref);
+        this.db.prepare("INSERT INTO search_index (ref, lane, text) VALUES (?, ?, ?)").run(ref, lane, text);
+    }
+}
+function rowData(row) {
+    return JSON.parse(row.data);
+}
+/** Quote each token so user input can never be FTS5 syntax. Tokens AND together. */
+function ftsQuery(query) {
+    const tokens = query.match(/[\p{L}\p{N}_]+/gu);
+    if (!tokens || tokens.length === 0)
+        return undefined;
+    return tokens.map((t) => `"${t}"`).join(" ");
+}
+function instanceSearchText(instance) {
+    return [
+        instance.situation.summary,
+        instance.situation.domain,
+        instance.situation.task ?? "",
+        instance.situation.cues.join(" "),
+        instance.diff?.summary ?? "",
+        instance.probeAnswers.map((p) => p.answer).join(" "),
+    ].join("\n");
+}
+function hypothesisSearchText(hypothesis) {
+    return [
+        hypothesis.rule,
+        hypothesis.domain,
+        hypothesis.cues.join(" "),
+        hypothesis.appliesWhen.join(" "),
+        hypothesis.doesNotApplyWhen.join(" "),
+        hypothesis.inferredRationale ?? "",
+    ].join("\n");
+}

package/docs/schema.md

@@ -0,0 +1,368 @@
+# athena Core Schema v1
+
+Status: design draft (2026-06-11). This is the contract everything else hangs off.
+Evidence base: `docs/research/2026-06-11-tacit-capture-research.md`.
+
+Mission framing: athena captures **tacit knowledge** from real work so agents become
+**truly autonomous and reliable** — no hand-holding, no repeated corrections.
+
+## Design rules
+
+1. **Instances are immutable evidence; rules are revisable views over evidence.**
+   A `JudgmentInstance` is never edited after capture. A `TacitHypothesis` can change
+   status/confidence but its rule text changes only by supersession (new version, old
+   one retired with a pointer). No silent rewrites — this is what makes evidence links honest.
+2. **Behavior is ground truth; rationale is labeled hypothesis.** Stated reasons (probe
+   answers, inferred rationale) are stored but never as facts.
+3. **Everything cites.** A hypothesis without `supportingInstanceIds` cannot exist.
+   A brief item without a `ref` cannot be served.
+4. **Privacy zone fields are mandatory on every capture-derived record** — cheap now,
+   impossible to retrofit. Raw instances default to private/non-promotable.
+5. **One storage truth (SQLite), markdown as derived projection.** Pages are generated,
+   never authoritative.
+6. **No taxonomy ahead of evidence.** Enums start minimal; `custom`/free-text escape
+   hatches instead of 19-member unions. We add members when real data forces it.
+7. **Bi-temporal-lite.** Records that represent claims about the world carry
+   `validFrom`/`validUntil` so "what was true then" survives "what is true now" (Zep's
+   one great idea, without the graph database).
+
+## IDs
+
+Prefixed ULIDs: `ins_` instance, `hyp_` hypothesis, `obj_` object, `src_` source,
+`out_` outcome, `brf_` brief, `act_` actor, `sen_` sensor. Sortable by creation time.
+
+---
+
+## 1. Capture layer
+
+### SensorEvent — the sensor contract
+
+Every capture surface (Chrome extension, Claude Code hook, MCP tool, CLI, connector)
+emits this one shape. Sensors are dumb: they observe and emit; all interpretation
+happens in the engine. This is what keeps the GTM extension and the dev-tool sensors
+siblings instead of separate products.
+
+```ts
+type SensorEvent = {
+  sensorId: string;            // sen_chrome_gmail, sen_claude_code, sen_mcp, sen_cli
+  emittedAt: string;           // ISO 8601
+  kind: InstanceKind;
+  situation: SituationInput;   // whatever context the sensor can see
+  before?: ArtifactInput;      // agent/template output, if any
+  after?: ArtifactInput;       // human's version, if any
+  probeAnswers?: ProbeAnswer[];
+  actorHint?: string;          // sensor's best guess at who acted
+  raw?: unknown;               // sensor-native payload, kept for audit, never interpreted
+};
+```
+
+### JudgmentInstance — the atomic evidence unit
+
+A moment where tacit knowledge became visible. Immutable after creation.
+
+```ts
+type InstanceKind =
+  | "correction"      // human edited agent/template output  ← the high-signal core
+  | "override"        // human ignored/reversed a suggestion
+  | "decision"        // human chose between alternatives
+  | "escalation"      // human got stuck and asked someone
+  | "failed_attempt"  // an approach that didn't work
+  | "approval"        // human explicitly accepted agent output (positive signal!)
+  | "manual_note";    // "remember this" — self-report, lowest evidential weight
+
+type JudgmentInstance = {
+  id: InstanceId;
+  kind: InstanceKind;
+  observedAt: string;
+  situation: Situation;
+  before?: Artifact;           // what the agent produced
+  after?: Artifact;            // what the human made it
+  diff?: StructuredDiff;       // computed at ingest, the engine's main food
+  probeAnswers: ProbeAnswer[]; // [] if no probe asked/answered
+  sensorId: string;
+  actorId: ActorId;
+  sourceRefs: SourceId[];      // explicit-layer evidence this moment touched
+  objectIds: ObjectId[];       // entities involved (resolved at ingest)
+  // privacy zone — defaults shown
+  visibility: "user_private_raw";   // | "derived" | "workspace"
+  canPromote: false;                // raw stays raw; derived twins can promote
+  canUseForAgents: false;
+};
+```
+
+Note: **approvals are instances too.** Positive signal (uncorrected output in a
+situation where a rule fired) is how hypotheses gain validity without pestering the user.
+
+### Situation — the retrieval key
+
+What makes an instance findable and clusterable. Kept small; the engine can recompute
+embeddings, but these fields are the durable semantics.
+
+```ts
+type Situation = {
+  summary: string;           // one line, natural language: "drafting cold outreach to enterprise CTO"
+  domain: string;            // dot-path subdomain: "email.outreach", "code.review", "crm.deal_update"
+  task?: string;             // what was being attempted
+  cues: string[];            // salient features the engine/probes identified
+  objectIds: ObjectId[];     // who/what this was about
+  app?: string;              // gmail | hubspot | claude-code | ...
+  agent?: { runtime?: string; model?: string };  // recorded, never required (model-agnostic)
+};
+```
+
+`domain` is the validity-regime boundary: hypotheses do not transfer across domains
+without re-confirmation (fractionated expertise — Kahneman/Klein).
+
+### ProbeAnswer — the micro-interview
+
+CDM-derived probe types, RPD-shaped. One or two per correction, max.
+
+```ts
+type ProbeKind =
+  | "cue"          // "What told you this was off?"
+  | "expectancy"   // "What did you expect to see instead?"
+  | "goal"         // "What were you protecting here?"
+  | "boundary"     // "One-off, or always?" / "Would this hold if X were different?"
+  | "transfer";    // "Does this apply to other accounts/projects too?"
+
+type ProbeAnswer = {
+  probe: ProbeKind;
+  question: string;          // exactly as asked
+  answer: string;            // verbatim — never summarized at capture time
+  askedAt: string;
+  dismissed?: boolean;       // user skipped — that's signal too (don't re-ask soon)
+};
+```
+
+### Artifact / StructuredDiff
+
+```ts
+type Artifact = {
+  mediaType: string;         // text/plain, text/markdown, text/x-diff, application/json
+  content: string;           // capped at ingest (e.g. 64KB); overflow → RawSource + ref
+  contentHash: string;
+  sourceRef?: SourceId;      // full original, if archived
+};
+
+type StructuredDiff = {
+  summary: string;                       // engine-written: "changed greeting from casual to formal title"
+  hunks: { before: string; after: string; label?: string }[];
+  magnitude: "trivial" | "minor" | "substantive" | "rewrite";
+};
+```
+
+---
+
+## 2. Learning layer
+
+### TacitHypothesis — the learning object (THE product)
+
+RPD-shaped: cues, expectancies, goal, action — plus boundaries, evidence, calibration.
+
+```ts
+type HypothesisStatus =
+  | "candidate"   // inferred, not yet replay-validated — NOT served to agents
+  | "validated"   // passed replay against held-out instances — servable with caveats
+  | "active"      // confirmed by review or repeated outcomes — served confidently
+  | "stale"       // staleness timer or contradictions — served only with warning, queued for revalidation
+  | "retired";    // superseded, rejected, or decayed to zero — kept for audit, never served
+
+type TacitHypothesis = {
+  id: HypothesisId;
+  status: HypothesisStatus;
+
+  // The rule (RPD byproducts)
+  rule: string;              // "When drafting outreach to enterprise contacts at Acme, use formal titles."
+  cues: string[];            // signals that this situation is *this kind* of situation
+  expectancies: string[];    // what you'd observe if the rule is working — and misfire signals
+  goal?: string;             // what the rule protects ("don't burn exec relationships")
+  domain: string;            // validity regime — same dot-path vocabulary as Situation.domain
+  appliesWhen: string[];     // boundary conditions, human-readable, checkable
+  doesNotApplyWhen: string[];// counter-boundaries (from counterexamples + boundary probes)
+
+  // Evidence — the load-bearing links
+  supportingInstanceIds: InstanceId[];
+  counterexampleInstanceIds: InstanceId[];
+  inferredRationale?: string;   // engine's explanation — labeled hypothesis, not fact
+
+  // Calibration
+  confidence: number;           // 0..1, set by engine, moved by outcomes — never by actor seniority
+  validity: {
+    fires: number;              // times served in a brief
+    upheld: number;             // served → output uncorrected
+    overridden: number;         // served → output corrected anyway (auto-counterexample)
+    lastFiredAt?: string;
+  };
+  replay: {                     // the validation gate
+    tested: number;             // held-out instances tested against
+    reproduced: number;         // where the rule predicted the human's edit
+    lastRunAt?: string;
+  };
+
+  // Lifecycle
+  createdAt: string;
+  lastConfirmedAt?: string;     // last supporting evidence or upheld outcome
+  staleAfter: string;           // hard timer — unconfirmed past this → status: stale
+  supersededById?: HypothesisId;
+
+  // Governance
+  visibility: "user_private" | "derived" | "workspace";
+  review: ReviewState;
+};
+
+type ReviewState =
+  | { state: "unreviewed" }
+  | { state: "approved" | "edited" | "rejected"; byActorId: ActorId; at: string; note?: string };
+```
+
+State machine:
+
+```
+candidate --replay pass--> validated --review approve | N upheld outcomes--> active
+candidate --replay fail--> retired
+validated/active --staleAfter exceeded | counterexamples > threshold--> stale
+stale --revalidation (replay + review)--> active        stale --decay--> retired
+any --superseded--> retired (supersededById set)
+```
+
+Deliberately absent (memodis lessons): no `WorkflowEpisode` as a persisted domain object —
+clustering is an engine implementation detail, not schema. No parallel `sourceRefs`/`sourceIds`
+duplication. No 7-level scope taxonomy — `domain` + `visibility` carry it.
+
+---
+
+## 3. Explicit layer (thin, boring, essential)
+
+Explicit knowledge grounds tacit extraction (entity vocabulary, situation tagging) and
+fills agent briefs with facts. It is deliberately commodity — gbrain-style, no innovation here.
+
+```ts
+type RawSource = {
+  id: SourceId;
+  kind: "document" | "email" | "thread" | "page" | "repo_doc" | "transcript" | "manual";
+  title: string;
+  content: string;             // or contentRef for large bodies
+  contentHash: string;
+  origin: { sensorId?: string; connector?: string; uri?: string };
+  capturedAt: string;
+  accessState: "private" | "workspace" | "restricted" | "revoked";
+};
+
+type KnowledgeObject = {
+  id: ObjectId;
+  kind: "person" | "org" | "project" | "repo" | "process" | "custom";
+  name: string;
+  aliases: string[];           // emails, handles, domains, nicknames — resolution keys
+  properties: Record<string, string>;
+  validFrom: string;
+  validUntil?: string;
+};
+
+type ObjectRelation = {
+  fromId: ObjectId;
+  toId: ObjectId;
+  kind: string;                // free vocabulary: works_at, owns, blocks, part_of...
+  sourceRefs: SourceId[];      // relations cite too
+  validFrom: string;
+  validUntil?: string;         // contradiction = close interval + open new one, never delete
+};
+```
+
+Markdown pages (per object, per domain) are **projections** generated from sources +
+hypotheses + relations. Stored in `.athena/pages/` for humans and git; rebuilt, never edited
+as truth.
+
+---
+
+## 4. Serving layer
+
+### Brief — the one agent-facing read (replaces memodis packets + coordinate maps)
+
+Compact payload + dereferenceable pointers. Persisted for audit and outcome linkage.
+
+```ts
+type Brief = {
+  id: BriefId;
+  task: string;                // as the agent stated it
+  compiledAt: string;
+
+  rules: {
+    hypothesisId: HypothesisId;
+    rule: string;
+    confidence: number;
+    appliesBecause: string;    // which cues matched this task
+    boundaries: string[];      // doesNotApplyWhen, surfaced inline
+    ref: Ref;
+  }[];
+
+  facts: {
+    statement: string;
+    ref: Ref;                  // citation into explicit layer — mandatory
+  }[];
+
+  doNotAssume: string[];       // caveats: ambiguities, contradictions, stale knowledge
+  openQuestions: string[];     // what athena knows it doesn't know (gbrain's honesty, kept)
+
+  readiness: "act" | "act_with_caveats" | "inspect_first" | "ask_human";
+  refs: Ref[];                 // additional evidence worth opening, ranked
+};
+
+type Ref = string;             // athena://hypothesis/hyp_x | athena://instance/ins_x
+                               // athena://source/src_x#L10-40 | athena://object/obj_x
+```
+
+`Ref` is the coordinate system's survivor: a plain dereferenceable pointer, no taxonomy.
+
+### AgentOutcome — the feedback loop closer
+
+```ts
+type AgentOutcome = {
+  id: OutcomeId;
+  briefId: BriefId;            // which serving this outcome judges
+  result: "uncorrected"        // human accepted → upheld++ for every served rule
+        | "corrected"          // human edited → correctionInstanceId links the new instance,
+                               //   overridden++ for served rules the correction contradicts
+        | "abandoned"
+        | "unknown";
+  correctionInstanceId?: InstanceId;
+  recordedAt: string;
+};
+```
+
+This closes the loop: **brief → action → outcome → instance → hypothesis update**, and
+gives us the north-star metric directly: correction rate per served brief, over time.
+
+### MCP surface (4 tools, not 19)
+
+| Tool | Does |
+|---|---|
+| `athena_brief(task, domain?)` | compile + persist a Brief |
+| `athena_open(ref)` | dereference any `athena://` ref |
+| `athena_record(event)` | SensorEvent in: outcome, correction, manual note, rule *proposal* |
+| `athena_search(query, lane?)` | direct lexical+semantic search when the agent wants to explore |
+
+No durable-mutation tools. `athena_record` proposals enter the review queue like any sensor event.
+
+---
+
+## 5. Storage mapping
+
+SQLite, one file per workspace (`.athena/athena.db`):
+- `instances`, `hypotheses`, `sources`, `objects`, `relations`, `outcomes`, `briefs`
+  — JSON column + extracted indexed columns (id, kind, domain, status, observedAt, visibility).
+- FTS5 over instance summaries/diffs, hypothesis rules, source content.
+- `sqlite-vec` over situation/rule/source embeddings (optional lane — everything works without it).
+- WAL mode; single-writer per file is acceptable for local; server mode serializes per workspace.
+
+Markdown projection in `.athena/pages/` — derived, git-friendly, regenerated.
+
+## 6. Open questions (carry into eval-harness design)
+
+- Probe selection policy: when is a correction worth a probe at all (magnitude threshold? novelty?),
+  and probe-budget per user per day (extension lesson from memodis: budget was right).
+- Replay scoring: what counts as "reproduced the human's edit" — LLM judge with rubric, or
+  string/structure similarity floor? (Likely: LLM judge, calibrated against a hand-labeled set.)
+- Confidence math: start with ExpeL-style counters + replay rate; resist Bayesian theater until
+  the eval harness can tell us if it helps.
+- Cross-actor aggregation (team mode): hypotheses are per-actor in v1; enterprise merge is a
+  governed promotion, not an automatic union.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "useathena",
+  "version": "0.1.0",
+  "description": "athena captures tacit knowledge from real work so agents become truly autonomous and reliable.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ErikLit005/athena.git"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.5"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "apps/chrome-extension",
+    "docs/schema.md",
+    "scripts/prepare.mjs"
+  ],
+  "scripts": {
+    "test": "node --import tsx --test src/**/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "verify": "npm run typecheck && npm test",
+    "build": "tsc -p tsconfig.build.json",
+    "prepare": "node scripts/prepare.mjs",
+    "eval": "node --import tsx src/eval/run-eval.ts",
+    "mcp": "node --import tsx src/mcp-server.ts",
+    "athena": "node --import tsx src/cli.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "tsx": "^4.22.3",
+    "typescript": "^5.5.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "bin": {
+    "athena": "bin/athena"
+  }
+}