useathena 0.1.0

package/README.md

@@ -0,0 +1,258 @@
+# Athena
+
+Athena captures the tacit knowledge hidden in real work so AI agents can become more autonomous, reliable, and less dependent on repeated human correction.
+
+Most agent failures in expert work are not caused by missing public facts. They happen because the agent lacks the unwritten judgment an expert applies without noticing: tone boundaries, account-specific exceptions, when to escalate, what not to assume, what "good enough" looks like, and which correction from last time should generalize to this time.
+
+Athena watches the moments where that judgment becomes visible, turns them into evidence-backed hypotheses, validates them, and serves the right rules back to agents before they act.
+
+```text
+work -> corrections -> tacit hypotheses -> validated rules -> agent briefs -> outcomes -> better rules
+```
+
+```bash
+npx useathena onboard --yes
+```
+
+## Product thesis
+
+Athena is a local-first tacit judgment layer for agents.
+
+The user should not have to write a giant operating manual for every assistant. Instead, Athena should learn from the normal feedback loop:
+
+- The user edits, rejects, approves, or redirects agent output.
+- Athena captures that judgment moment as immutable evidence.
+- A model-backed engine infers candidate rules with supporting examples and boundaries.
+- The user reviews rules before they become durable.
+- Agents call Athena for a brief before acting.
+- Outcomes feed back into confidence, stale detection, and counterexamples.
+
+The north-star metric is a declining correction rate per served brief.
+
+## MVP
+
+The MVP is not a broad knowledge base. It is a working closed loop for tacit judgment:
+
+1. Capture high-signal judgment events from real workflows.
+   - CLI and MCP capture for manual or agent-recorded events.
+   - Claude Code hook for explicit `remember:` / `athena:` notes and redirect-shaped prompts.
+   - Chrome extension sensor for LinkedIn and Gmail draft edits: paste a generated draft, edit it, send it, and Athena captures the before/after as a correction or approval.
+
+2. Store evidence locally and safely.
+   - SQLite is the source of truth.
+   - Raw captured instances are private by default.
+   - Every learned rule cites the evidence that produced it.
+   - Agents can propose evidence and outcomes, but cannot directly mutate durable rules.
+
+3. Infer tacit rules from evidence.
+   - The hypothesis engine clusters examples by domain.
+   - It infers cues, expectancies, goals, rules, and boundary conditions.
+   - It replay-validates against held-out examples before a rule can be served.
+   - Inference is model-backed, not a fake deterministic string matcher.
+
+4. Validate before serving; review is optional.
+   - Replay-validated rules are served to agents immediately, flagged with caveats.
+   - Rules graduate to confidently-served on their own through repeated upheld
+     outcomes — no human in the loop required.
+   - `athena review` is an accelerator and audit surface: approving promotes a rule
+     instantly, rejecting retires it (kept for audit). It is never a gate.
+
+5. Brief agents before they act.
+   - MCP exposes exactly four tools: `athena_brief`, `athena_open`, `athena_record`, and `athena_search`.
+   - A brief returns applicable rules, confidence, boundaries, citations, do-not-assume items, open questions, and a readiness verdict.
+
+6. Learn from outcomes.
+   - Agents record whether their briefed output was accepted, corrected, abandoned, or unknown.
+   - Rules gain trust when upheld and lose trust when overridden.
+   - Repeated counterexamples make rules stale.
+
+## What exists now
+
+Current build status: early but end-to-end.
+
+Implemented:
+
+- Core schema and typed domain model.
+- SQLite store with invariants and lexical search.
+- Capture ingestion with structured diffs.
+- LLM-backed hypothesis engine.
+- Model-agnostic providers: `cli:claude`, `cli:codex`, Anthropic API,
+  OpenAI-compatible APIs, and local models via Ollama / LM Studio / vLLM.
+- Golden-scenario eval harness.
+- Brief compilation, outcome recording, and autonomous rule promotion
+  (validated rules graduate to active through upheld outcomes).
+- MCP server with the four-tool agent surface (`athena mcp`).
+- CLI with a first-run `athena setup` wizard, plus init, status, capture, learn,
+  review, brief, rules, open, record, serve, and hook install.
+- Claude Code sensor hook (installed by `athena setup` or `athena hook install`).
+- Localhost API for browser sensors.
+- Chrome extension v0.1 for LinkedIn and Gmail draft-edit capture.
+- One-command onboarding: `npx useathena onboard --yes` (npm package `useathena`,
+  binary `athena`; GitHub installs work too).
+
+Still rough or planned:
+
+- Chrome Web Store extension (today: load-unpacked from the installed package).
+- Chrome extension selector hardening and browser automation smoke tests.
+- Embeddings or semantic search, if lexical search stops being enough.
+- Team/workspace promotion flows for sharing vetted derived rules.
+
+## Architecture
+
+```text
+src/core       Types, ids, refs, fixtures
+src/store      SQLite store and enforced invariants
+src/capture    SensorEvent -> immutable JudgmentInstance ingestion
+src/engine     Model-backed hypothesis inference and replay validation
+src/serve      Agent brief compilation and outcome recording
+src/eval       Golden scenarios, harness, and judges
+src/mcp        MCP tools for agents
+src/cli        CLI command logic and interactive review loop
+src/api        Localhost API for browser sensors
+src/model      ModelClient interface and CLI-backed providers
+apps/chrome-extension
+               MV3 sensor for LinkedIn and Gmail
+docs           Schema and research notes
+```
+
+Important contracts:
+
+- [`docs/schema.md`](docs/schema.md) is the product/domain contract.
+- [`docs/research/2026-06-11-tacit-capture-research.md`](docs/research/2026-06-11-tacit-capture-research.md) contains the research and competitive landscape behind the design.
+- [`apps/chrome-extension/README.md`](apps/chrome-extension/README.md) documents the browser sensor capture policy.
+
+## Install
+
+Requires Node 22.5+ (Athena uses the built-in `node:sqlite` module).
+
+```bash
+npx useathena onboard          # interactive
+npx useathena onboard --yes    # accept every default
+```
+
+Working from a branch, or without registry access? The same flow runs straight
+from GitHub for anyone with repo access:
+
+```bash
+npx github:ErikLit005/athena onboard
+```
+
+Onboarding does everything: creates the local store, detects which model providers
+you have (claude CLI, codex CLI, Anthropic or OpenAI API keys, a running Ollama),
+verifies the one you pick with a real inference call, installs itself globally so
+hooks survive the npx cache, wires up Claude Code (sensor hook + MCP registration),
+and prints the browser-extension setup. `--yes` takes the first detected provider
+and says yes to all of it; opt out per-piece with `--no-hook`, `--skip-test`, or
+`--model <spec>`.
+
+Model providers are spec strings, set once by `setup` (or per-run via `ATHENA_MODEL`):
+
+```text
+cli:claude[:model]          Claude subscription via the claude CLI — no API key
+cli:codex[:model]           ChatGPT subscription via the codex CLI — no API key
+anthropic[:model]           Anthropic API (ANTHROPIC_API_KEY)
+openai:<model>              OpenAI API (OPENAI_API_KEY)
+openai:<model>@<baseUrl>    any OpenAI-compatible server (LM Studio, vLLM, …)
+ollama:<model>              local Ollama
+```
+
+## Local development
+
+```bash
+git clone https://github.com/ErikLit005/athena.git && cd athena
+npm install
+npm run verify      # typecheck + tests
+```
+
+Useful commands:
+
+```bash
+npm run typecheck
+npm test
+npm run eval
+npm run build       # compile to dist/ (what a global install runs)
+npm run athena -- status
+```
+
+The default store path is `~/.athena/athena.db`. Override it with `ATHENA_DB` for tests or isolated local experiments. Config (model choice, optional API keys) lives in `~/.athena/config.json`.
+
+## Running Athena locally
+
+Initialize the local store and print MCP setup instructions (or run `athena setup` for the guided version):
+
+```bash
+npm run athena -- init
+```
+
+Capture an example correction:
+
+```bash
+npm run athena -- capture correction \
+  --summary "edited a LinkedIn connection note to be warmer and less salesy" \
+  --domain linkedin.outreach \
+  --before "Would love to connect and discuss how we can help your team." \
+  --after "Saw your post on GTM hiring. Would be glad to connect."
+```
+
+Learn candidate rules from captured evidence:
+
+```bash
+npm run athena -- learn --domain linkedin.outreach
+```
+
+Review inferred rules:
+
+```bash
+npm run athena -- review
+```
+
+Ask for the kind of brief an agent should get before acting:
+
+```bash
+npm run athena -- brief "draft a LinkedIn connection note to a GTM leader" --domain linkedin.outreach
+```
+
+Start the localhost API for the Chrome extension:
+
+```bash
+npm run athena -- serve
+```
+
+## Design principles
+
+- Instances are immutable evidence; hypotheses are revisable views over evidence.
+- Behavior is ground truth; rationale is labeled hypothesis.
+- Everything cites.
+- Privacy fields are mandatory on capture-derived records.
+- SQLite is the source of truth; markdown is a projection.
+- The engine is model-backed and model-agnostic.
+- The agent surface stays small and auditable.
+- Rules earn trust autonomously — replay validation to be served, upheld outcomes
+  to be served confidently. Human review accelerates and audits; it never gates.
+- Human interaction concentrates at critical moments: briefs say `ask_human` when
+  athena's knowledge is thin or contradictory, and counterexamples surface for audit.
+
+## Where to help
+
+Good near-term contribution areas:
+
+- Hardening the Chrome extension against LinkedIn and Gmail DOM changes.
+- Adding browser smoke tests for the extension capture flow.
+- Publishing the Chrome extension to the Web Store.
+- Expanding eval scenarios from real corrections, especially cases with subtle boundaries or counterexamples.
+
+Before changing core behavior, read [`docs/schema.md`](docs/schema.md). Before changing product direction, read the research notes and keep the north-star metric in mind: fewer repeated corrections per served brief.
+
+## Broader vision
+
+The first wedge is personal: Athena should make one person's agents learn their standards, preferences, and judgment over time.
+
+The broader vision is an evidence-backed judgment layer for teams and organizations:
+
+- Personal tacit rules stay private by default.
+- Vetted derived rules can be promoted to a workspace.
+- Agents can be briefed with context-specific judgment before they write, decide, escalate, or act.
+- Experts spend less time repeating corrections and more time reviewing high-leverage rules.
+- Organizations accumulate operational judgment without pretending every important rule can be written down in advance.
+
+If Athena works, an agent should not merely remember what happened. It should learn how the expert decided.

package/apps/chrome-extension/README.md

@@ -0,0 +1,35 @@
+# athena sensor (Chrome extension)
+
+Captures the judgment behind your edits of drafted messages and sends it to **your own
+local athena** — nothing leaves your machine.
+
+## Capture policy (the contract)
+
+The extension captures in exactly two situations:
+
+1. **Draft edits.** You paste a substantial draft (≥ 80 chars — e.g. agent output) into a
+   LinkedIn note/message or Gmail compose body. The pasted text is the "before". When you
+   send (button or Cmd/Ctrl+Enter), the final text is the "after". Edited → `correction`,
+   unchanged → `approval`.
+2. **Explicit saves.** Right-click a selection → "athena: remember this" → `manual_note`.
+
+Everything else is out of scope by construction: no keystroke logging, no page scraping,
+no capture of messages you typed from scratch, only whitelisted domains
+(linkedin.com, mail.google.com), and the only network destination is `http://127.0.0.1`.
+A pause toggle lives in the toolbar popup.
+
+All captures land as `user_private_raw` instances — they become rules only through the
+engine and your review (`athena review`).
+
+## Install
+
+1. Start the local API: `athena serve` (prints the token).
+2. `chrome://extensions` → enable Developer mode → "Load unpacked" → select this folder.
+3. Extension options → paste the token → Save → Test connection.
+4. Work normally. Check captures with `athena status`, learn with `athena learn`.
+
+## Known limitations (v0.1)
+
+- LinkedIn/Gmail DOM selectors are best-effort and will need maintenance as those UIs change.
+- Drafts typed from scratch are deliberately not captured (no "before" to learn from).
+- No browser-automation smoke test yet — port the memodis harness when this stabilizes.

package/apps/chrome-extension/background.js

@@ -0,0 +1,97 @@
+// athena sensor — service worker.
+// Routes events from content scripts to the local athena API (127.0.0.1 only).
+// The capture policy lives in the content scripts; this file only transports.
+
+const DEFAULTS = { athenaPort: 4517, athenaToken: "", paused: false };
+
+async function settings() {
+  return chrome.storage.local.get(DEFAULTS);
+}
+
+async function postEvent(event) {
+  const { athenaPort, athenaToken, paused } = await settings();
+  if (paused) return { ok: false, error: "paused" };
+  if (!athenaToken) return { ok: false, error: "no token — open the options page" };
+  try {
+    const response = await fetch(`http://127.0.0.1:${athenaPort}/events`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${athenaToken}`,
+      },
+      body: JSON.stringify(event),
+    });
+    if (!response.ok) {
+      const body = await response.json().catch(() => ({}));
+      return { ok: false, error: body.error || `api ${response.status}` };
+    }
+    return { ok: true, body: await response.json() };
+  } catch (error) {
+    return { ok: false, error: `athena not reachable — is "athena serve" running? (${error})` };
+  }
+}
+
+async function health() {
+  const { athenaPort } = await settings();
+  try {
+    const response = await fetch(`http://127.0.0.1:${athenaPort}/health`);
+    return { ok: response.ok };
+  } catch {
+    return { ok: false };
+  }
+}
+
+function flashBadge(ok) {
+  chrome.action.setBadgeBackgroundColor({ color: ok ? "#2da44e" : "#cf222e" });
+  chrome.action.setBadgeText({ text: ok ? "✓" : "!" });
+  setTimeout(() => chrome.action.setBadgeText({ text: "" }), 2500);
+}
+
+function domainForUrl(url) {
+  try {
+    const host = new URL(url).hostname;
+    if (host === "mail.google.com") return "email";
+    if (host.endsWith("linkedin.com")) return "linkedin";
+    return "web";
+  } catch {
+    return "web";
+  }
+}
+
+chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {
+  if (message && message.type === "athena-event") {
+    postEvent(message.event).then((result) => {
+      flashBadge(result.ok);
+      sendResponse(result);
+    });
+    return true;
+  }
+  if (message && message.type === "athena-health") {
+    health().then(sendResponse);
+    return true;
+  }
+  return false;
+});
+
+chrome.runtime.onInstalled.addListener(() => {
+  chrome.contextMenus.create({
+    id: "athena-remember",
+    title: "athena: remember this",
+    contexts: ["selection"],
+  });
+});
+
+chrome.contextMenus.onClicked.addListener((info, tab) => {
+  if (info.menuItemId !== "athena-remember" || !info.selectionText) return;
+  const event = {
+    kind: "manual_note",
+    situation: {
+      summary: `remember from ${tab && tab.title ? tab.title.slice(0, 80) : "page"}`,
+      domain: domainForUrl(tab ? tab.url : ""),
+      app: "chrome",
+    },
+    after: info.selectionText.slice(0, 8000),
+    raw: { url: tab ? tab.url : undefined },
+  };
+  postEvent(event).then((result) => flashBadge(result.ok));
+});

package/apps/chrome-extension/gmail.js

@@ -0,0 +1,107 @@
+// athena sensor — Gmail content script.
+//
+// Same capture policy as LinkedIn: track ONLY pasted drafts (>= 80 chars)
+// into a compose body; capture on send (click or Cmd/Ctrl+Enter);
+// edited -> correction, unchanged -> approval. Untracked mail is never read.
+
+(() => {
+  const MIN_DRAFT_CHARS = 80;
+  const tracked = new WeakMap();
+  let lastTracked = null;
+
+  function composeBodyOf(target) {
+    if (!target || !target.closest) return null;
+    return target.closest("div[role='textbox'][contenteditable='true']");
+  }
+
+  document.addEventListener(
+    "paste",
+    (event) => {
+      try {
+        const body = composeBodyOf(event.target);
+        if (!body) return;
+        setTimeout(() => {
+          const value = body.innerText || "";
+          if (value.trim().length >= MIN_DRAFT_CHARS) {
+            tracked.set(body, { before: value, at: Date.now() });
+            lastTracked = body;
+          }
+        }, 80);
+      } catch {
+        // sensor must never break the page
+      }
+    },
+    true,
+  );
+
+  function containerOf(node) {
+    return node && node.closest ? node.closest("[role='dialog'], .iN, table") : null;
+  }
+
+  function subjectFor(node) {
+    const container = containerOf(node);
+    const input = (container || document).querySelector("input[name='subjectbox']");
+    return input && input.value ? input.value.trim().slice(0, 80) : "";
+  }
+
+  function emitIfTracked(body) {
+    try {
+      const state = body && tracked.get(body);
+      if (!state) return;
+      tracked.delete(body);
+      if (body === lastTracked) lastTracked = null;
+      const after = body.innerText || "";
+      if (after.trim().length === 0) return;
+      const unchanged = after.trim() === state.before.trim();
+      const subject = subjectFor(body);
+      chrome.runtime.sendMessage({
+        type: "athena-event",
+        event: {
+          kind: unchanged ? "approval" : "correction",
+          situation: {
+            summary:
+              (unchanged ? "sent pasted draft unchanged" : "edited pasted draft before sending") +
+              (subject ? ` (email: ${subject})` : " (email)"),
+            domain: "email.compose",
+            app: "gmail",
+          },
+          before: state.before,
+          after,
+          raw: { url: location.href },
+        },
+      });
+    } catch {
+      // sensor must never break the page
+    }
+  }
+
+  document.addEventListener(
+    "click",
+    (event) => {
+      try {
+        const button =
+          event.target && event.target.closest ? event.target.closest("div[role='button'], button") : null;
+        if (!button) return;
+        const label = (button.getAttribute("aria-label") || button.textContent || "").trim();
+        if (!/^send\b/i.test(label)) return;
+        const container = containerOf(button);
+        const body = container ? container.querySelector("div[role='textbox'][contenteditable='true']") : null;
+        emitIfTracked(body || lastTracked);
+      } catch {
+        // sensor must never break the page
+      }
+    },
+    true,
+  );
+
+  document.addEventListener(
+    "keydown",
+    (event) => {
+      if ((event.metaKey || event.ctrlKey) && event.key === "Enter") {
+        const body = composeBodyOf(event.target);
+        if (body) emitIfTracked(body);
+      }
+    },
+    true,
+  );
+})();

package/apps/chrome-extension/linkedin.js

@@ -0,0 +1,123 @@
+// athena sensor — LinkedIn content script.
+//
+// Capture policy (the whole point — read before editing):
+// - We track a field ONLY when the user pastes a substantial draft (>= 80 chars)
+//   into a note/message field. The pasted text is the "before".
+// - On send (button click or Cmd/Ctrl+Enter) we capture the final text:
+//   edited -> correction, unchanged -> approval. Tracking is then cleared.
+// - Untracked typing is NEVER captured. Nothing else on the page is read.
+
+(() => {
+  const MIN_DRAFT_CHARS = 80;
+  const tracked = new WeakMap();
+  let lastTracked = null;
+
+  function fieldOf(target) {
+    if (!target || !target.closest) return null;
+    return target.closest("textarea, [contenteditable='true']");
+  }
+
+  function valueOf(field) {
+    if (!field) return "";
+    return field.value !== undefined ? field.value : field.innerText || "";
+  }
+
+  document.addEventListener(
+    "paste",
+    (event) => {
+      try {
+        const field = fieldOf(event.target);
+        if (!field) return;
+        setTimeout(() => {
+          const value = valueOf(field);
+          if (value.trim().length >= MIN_DRAFT_CHARS) {
+            tracked.set(field, { before: value, at: Date.now() });
+            lastTracked = field;
+          }
+        }, 80);
+      } catch {
+        // sensor must never break the page
+      }
+    },
+    true,
+  );
+
+  function dialogOf(field) {
+    return field && field.closest ? field.closest("[role='dialog']") : null;
+  }
+
+  function isConnectionNote(field) {
+    const dialog = dialogOf(field);
+    if (!dialog) return false;
+    return /add a note|invitation|invite|connect/i.test(dialog.textContent || "");
+  }
+
+  function recipientOf(field) {
+    const dialog = dialogOf(field);
+    if (!dialog) return "";
+    const heading = dialog.querySelector("h2, h1, strong");
+    return heading ? (heading.textContent || "").trim().slice(0, 60) : "";
+  }
+
+  function emitIfTracked(field) {
+    try {
+      const state = field && tracked.get(field);
+      if (!state) return;
+      tracked.delete(field);
+      if (field === lastTracked) lastTracked = null;
+      const after = valueOf(field);
+      if (after.trim().length === 0) return;
+      const unchanged = after.trim() === state.before.trim();
+      const note = isConnectionNote(field);
+      const recipient = recipientOf(field);
+      chrome.runtime.sendMessage({
+        type: "athena-event",
+        event: {
+          kind: unchanged ? "approval" : "correction",
+          situation: {
+            summary:
+              (unchanged ? "sent pasted draft unchanged" : "edited pasted draft before sending") +
+              (note ? " (LinkedIn connection note" : " (LinkedIn message") +
+              (recipient ? ` to ${recipient})` : ")"),
+            domain: note ? "linkedin.connection_note" : "linkedin.message",
+            app: "linkedin",
+          },
+          before: state.before,
+          after,
+          raw: { url: location.href },
+        },
+      });
+    } catch {
+      // sensor must never break the page
+    }
+  }
+
+  document.addEventListener(
+    "click",
+    (event) => {
+      try {
+        const button = event.target && event.target.closest ? event.target.closest("button") : null;
+        if (!button) return;
+        const label = (button.getAttribute("aria-label") || button.textContent || "").trim();
+        if (!/^send\b/i.test(label)) return;
+        const dialog = button.closest("[role='dialog']");
+        const field = dialog ? fieldOf(dialog.querySelector("textarea, [contenteditable='true']")) : lastTracked;
+        if (field) emitIfTracked(field);
+      } catch {
+        // sensor must never break the page
+      }
+    },
+    true,
+  );
+
+  document.addEventListener(
+    "keydown",
+    (event) => {
+      if ((event.metaKey || event.ctrlKey) && event.key === "Enter") {
+        const field = fieldOf(event.target);
+        if (field) emitIfTracked(field);
+      }
+    },
+    true,
+  );
+})();

package/apps/chrome-extension/manifest.json

@@ -0,0 +1,27 @@
+{
+  "manifest_version": 3,
+  "name": "athena sensor",
+  "version": "0.1.0",
+  "description": "Captures the judgment behind your edits of drafted messages — locally, to your own athena. No cloud, no telemetry.",
+  "permissions": ["storage", "contextMenus"],
+  "host_permissions": [
+    "https://www.linkedin.com/*",
+    "https://mail.google.com/*",
+    "http://127.0.0.1/*"
+  ],
+  "background": { "service_worker": "background.js" },
+  "content_scripts": [
+    {
+      "matches": ["https://www.linkedin.com/*"],
+      "js": ["linkedin.js"],
+      "run_at": "document_idle"
+    },
+    {
+      "matches": ["https://mail.google.com/*"],
+      "js": ["gmail.js"],
+      "run_at": "document_idle"
+    }
+  ],
+  "action": { "default_popup": "popup.html", "default_title": "athena" },
+  "options_page": "options.html"
+}