useathena 0.2.0 → 0.3.0

package/README.md

@@ -107,11 +107,23 @@ Implemented:
   (`athena serve install`, done by setup) so capture survives reboots.
 - Chrome extension v0.1 for LinkedIn and Gmail draft-edit capture.
 - `athena export`: one JSON bundle of everything learned (`--redact` for sharing).
+- Knowledge connectors — Notion, Slack, and Google (Drive + Gmail):
+  `athena connect <provider>` is a guided flow, also offered during onboarding.
+  Notion uses an internal integration token (the pages you share are the
+  privacy boundary); Slack uses an app created from a printed manifest
+  (read-only scopes, public channels you are a member of); Google is a
+  gcloud-style browser sign-in (loopback + PKCE, read-only Drive docs and sent
+  mail — expect the "unverified app" interstitial during friend testing).
+  Synced content becomes cited, searchable sources that feed briefs; re-sync
+  runs every few hours inside the serve service, or on demand via `athena sync`.
 - One-command onboarding: `npx useathena onboard --yes` (npm package `useathena`,
   binary `athena`; GitHub installs work too).
 
 Still rough or planned:
 
+- Fact extraction from connected sources with stated-vs-observed provenance.
+- Google consent-screen verification (today: unverified-app interstitial,
+  100-user cap — fine for friend testing).
 - 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.
@@ -161,9 +173,15 @@ Onboarding does everything: creates the local store, detects which model provide
 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),
-installs the browser-sensor API as a login service, and prints the extension setup
-with its token. `--yes` takes the first detected provider and says yes to all of it;
-opt out per-piece with `--no-hook`, `--no-service`, `--skip-test`, or `--model <spec>`.
+installs the browser-sensor API as a login service, offers to connect a knowledge
+source (Notion — so briefs have real facts on day one), and prints the extension
+setup with its token. `--yes` takes the first detected provider and says yes to all
+of it (knowledge sources need a token paste, so non-interactive runs print the
+`athena connect` pointer instead); opt out per-piece with `--no-hook`,
+`--no-service`, `--no-connect`, `--skip-test`, or `--model <spec>`.
+
+Already installed? `athena update` pulls the latest published version and
+restarts the background serve service on the new code.
 
 Model providers are spec strings, set once by `setup` (or per-run via `ATHENA_MODEL`):
 

package/dist/cli/commands.js

@@ -40,6 +40,11 @@ export function cmdStatus(store) {
     if (counts.facts > 0) {
         lines.splice(3, 0, `  ${bold(String(counts.facts))} fact${counts.facts === 1 ? "" : "s"} about ${bold(String(store.listObjects().length))} entities`);
     }
+    const connections = store.listConnections();
+    if (counts.sources > 0 || connections.length > 0) {
+        const from = connections.length > 0 ? ` from ${connections.map((c) => c.provider).join(", ")}` : "";
+        lines.push(`  ${bold(String(counts.sources))} source${counts.sources === 1 ? "" : "s"} synced${from} ${dim("(athena connect to add more)")}`);
+    }
     if (counts.unmatchedDrafts > 0) {
         lines.push(`  ${bold(String(counts.unmatchedDrafts))} agent draft${counts.unmatchedDrafts === 1 ? "" : "s"} awaiting an observed outcome`);
     }

package/dist/cli/connect.js

@@ -0,0 +1,120 @@
+import { createInterface } from "node:readline/promises";
+import { newId } from "../core/ids.js";
+import { connectors, syncConnection } from "../connect/sync.js";
+import { deleteSecret, saveSecret } from "../connect/secrets.js";
+import { bold, dim, green, red, yellow } from "./format.js";
+/** `athena connect [provider]` — guided token-paste connect; no args lists connections. */
+export async function runConnect(store, args) {
+    const provider = args.find((a) => !a.startsWith("--"));
+    if (!provider) {
+        console.log(renderConnections(store));
+        return;
+    }
+    if (!connectors[provider]) {
+        throw new Error(`unknown provider: ${provider} — available: ${Object.keys(connectors).join(", ")}`);
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        await connectProvider(store, provider, rl);
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * The guided connect flow, on a caller-owned readline so the setup wizard can
+ * embed it (two open readline interfaces on one stdin double-echo keystrokes).
+ * A failed validation re-prompts — a typo'd paste is common; with `allowSkip`,
+ * an empty paste backs out instead of erroring.
+ */
+export async function connectProvider(store, provider, rl, { allowSkip = false } = {}) {
+    const connector = connectors[provider];
+    console.log(`${bold(`Connect ${connector.label}`)}\n`);
+    connector.instructions.forEach((step, i) => console.log(`  ${i + 1}. ${step}`));
+    if (connector.extra) {
+        console.log(`\n${connector.extra.split("\n").map((line) => `     ${line}`).join("\n")}`);
+    }
+    const acquired = connector.acquire
+        ? await connector.acquire(rl, (line) => console.log(dim(`  ${line}`)))
+        : await pasteToken(connector, provider, rl, allowSkip);
+    if (!acquired)
+        return false;
+    const existing = store.listConnections(provider)[0];
+    const connection = existing
+        ? { ...existing, label: acquired.label }
+        : { id: newId("con"), provider, label: acquired.label, createdAt: new Date().toISOString() };
+    saveSecret(connection.id, acquired.secret);
+    store.saveConnection(connection);
+    console.log(dim("first sync…"));
+    const result = await syncConnection(store, connection, (line) => console.log(dim(`  ${line}`)));
+    console.log(`${green("✓")} connected ${bold(acquired.label)} — ${bold(String(result.added))} sources synced` +
+        (result.updated || result.unchanged ? dim(` (${result.updated} updated, ${result.unchanged} unchanged)`) : ""));
+    console.log(dim(`new and changed content arrives on the next sync (athena sync ${provider})`));
+    return true;
+}
+async function pasteToken(connector, provider, rl, allowSkip) {
+    while (true) {
+        const skipHint = allowSkip ? dim(", Enter to skip") : "";
+        const token = (await rl.question(`\nPaste the token (${dim(connector.tokenHint ?? "")}${skipHint}): `)).trim();
+        if (!token) {
+            if (!allowSkip)
+                throw new Error("no token given — nothing connected");
+            console.log(dim(`skipped — connect later with: athena connect ${provider}`));
+            return undefined;
+        }
+        process.stdout.write(dim("checking the token… "));
+        try {
+            const label = await connector.validate(token);
+            console.log(`${green("✓")} ${label}`);
+            return { secret: token, label };
+        }
+        catch (error) {
+            console.log(red(`✗ ${error instanceof Error ? error.message : String(error)}`));
+        }
+    }
+}
+export async function runDisconnect(store, args) {
+    const provider = args.find((a) => !a.startsWith("--"));
+    if (!provider)
+        throw new Error("usage: athena disconnect <provider>");
+    const connection = store.listConnections(provider)[0];
+    if (!connection) {
+        console.log(yellow(`no ${provider} connection found`));
+        return;
+    }
+    deleteSecret(connection.id);
+    store.deleteConnection(connection.id);
+    console.log(`${green("✓")} disconnected ${connection.label} — synced sources stay (and remain searchable)`);
+}
+export async function runSync(store, args) {
+    const provider = args.find((a) => !a.startsWith("--"));
+    const targets = provider ? store.listConnections(provider) : store.listConnections();
+    if (targets.length === 0) {
+        console.log(yellow(provider ? `no ${provider} connection — run: athena connect ${provider}` : "no connections yet — run: athena connect notion"));
+        return;
+    }
+    for (const connection of targets) {
+        console.log(`${bold(connection.provider)} ${dim(connection.label)} …`);
+        try {
+            const result = await syncConnection(store, connection, (line) => console.log(dim(`  ${line}`)));
+            console.log(`${green("✓")} +${result.added} new, ${result.updated} updated, ${result.unchanged} unchanged`);
+        }
+        catch (error) {
+            console.log(red(`✗ ${error instanceof Error ? error.message : String(error)}`));
+            process.exitCode = 1;
+        }
+    }
+}
+export function renderConnections(store) {
+    const connections = store.listConnections();
+    if (connections.length === 0) {
+        return `no connections yet — available: ${Object.keys(connectors).join(", ")}\nconnect one with: ${bold("athena connect notion")}`;
+    }
+    return connections
+        .map((c) => {
+        const synced = c.lastSyncedAt ? `last sync ${c.lastSyncedAt.slice(0, 16).replace("T", " ")}` : "never synced";
+        const error = c.lastError ? ` ${red(`✗ ${c.lastError.slice(0, 80)}`)}` : "";
+        return `${bold(c.provider)}  ${c.label}  ${dim(synced)}${error}`;
+    })
+        .join("\n");
+}

package/dist/cli/format.js

@@ -57,6 +57,30 @@ export function hitRate(upheld, overridden) {
     const text = `${upheld}/${total} upheld`;
     return rate >= 0.7 ? green(text) : rate >= 0.4 ? yellow(text) : red(text);
 }
+/** The wizard's opening: a banner (figlet "ANSI Shadow"), the version, and the one-line promise. */
+export function banner(version) {
+    const art = [
+        " █████╗ ████████╗██╗  ██╗███████╗███╗   ██╗ █████╗ ",
+        "██╔══██╗╚══██╔══╝██║  ██║██╔════╝████╗  ██║██╔══██╗",
+        "███████║   ██║   ███████║█████╗  ██╔██╗ ██║███████║",
+        "██╔══██║   ██║   ██╔══██║██╔══╝  ██║╚██╗██║██╔══██║",
+        "██║  ██║   ██║   ██║  ██║███████╗██║ ╚████║██║  ██║",
+        "╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝╚══════╝╚═╝  ╚═══╝╚═╝  ╚═╝",
+    ];
+    return [
+        "",
+        ...art.map((line) => `  ${cyan(line)}`),
+        "",
+        `  agents that learn the tacit knowledge behind how you work  ${dim(`v${version}`)}`,
+        "",
+    ].join("\n");
+}
+/** A section divider: `── title · 2/4 ─────…` — structure without a TUI dependency. */
+export function section(title, hint = "", step = "") {
+    const label = `── ${title} ${step ? `· ${step} ` : ""}`;
+    const rule = "─".repeat(Math.max(0, 56 - label.length));
+    return `\n${dim("──")} ${bold(title)}${step ? dim(` · ${step}`) : ""} ${dim(rule)}${hint ? `\n${dim(`   ${hint}`)}` : ""}`;
+}
 export function wrap(text, indent, width = 88) {
     const words = text.split(/\s+/);
     const lines = [];

package/dist/cli/service.js

@@ -43,6 +43,13 @@ Restart=always
 WantedBy=default.target
 `;
 }
+export function serviceInstalled(platform = process.platform) {
+    if (platform === "darwin")
+        return existsSync(join(homedir(), "Library", "LaunchAgents", `${SERVICE_LABEL}.plist`));
+    if (platform === "linux")
+        return existsSync(join(homedir(), ".config", "systemd", "user", SYSTEMD_UNIT));
+    return false;
+}
 export function installService(athenaBin, platform = process.platform) {
     const logPath = join(dirname(dbPath()), "serve.log");
     if (platform === "darwin") {

package/dist/cli/setup.js

@@ -6,22 +6,27 @@ import { createInterface } from "node:readline/promises";
 import { configPath, dbPath, loadConfig, saveConfig } from "../config.js";
 import { loadOrCreateServeToken } from "../api/server.js";
 import { DEFAULT_ANTHROPIC_MODEL, modelClientFromSpec, SUPPORTED_SPECS } from "../model/registry.js";
+import { connectors } from "../connect/sync.js";
 import { installService } from "./service.js";
-import { bold, cyan, dim, green, red, yellow } from "./format.js";
+import { connectProvider } from "./connect.js";
+import { readPackageInfo } from "./update.js";
+import { banner, bold, cyan, dim, green, red, section, yellow } from "./format.js";
 /**
  * First-run wizard (aliases: setup, onboard): pick a model provider, prove it
- * answers, wire up the sensors. `npx useathena onboard --yes` is the one-command
- * path: it accepts every default, including a global self-install when running
- * from the npx cache (hooks and MCP registrations must outlive cache pruning).
- * Granular escape hatches: --model <spec>, --hook/--no-hook, --no-service, --skip-test.
+ * answers, wire up the sensors, offer a knowledge source. `npx useathena onboard
+ * --yes` is the one-command path: it accepts every default, including a global
+ * self-install when running from the npx cache (hooks and MCP registrations must
+ * outlive cache pruning). Granular escape hatches: --model <spec>, --hook/--no-hook,
+ * --no-service, --no-connect, --skip-test.
  */
 const OLLAMA_TAGS_URL = "http://127.0.0.1:11434/api/tags";
-export async function runSetup(args, packageRoot) {
+export async function runSetup(args, packageRoot, store) {
     const interactive = process.stdin.isTTY === true && !args.includes("--yes");
     const rl = interactive ? createInterface({ input: process.stdin, output: process.stdout }) : null;
     try {
-        console.log(`${bold("athena setup")}\n`);
+        console.log(banner(readPackageInfo(packageRoot).version));
         console.log(`${green("✓")} store ready at ${bold(dbPath())}`);
+        console.log(section("model", "powers rule inference — capture works without it", "1/4"));
         const config = loadConfig();
         const spec = await chooseModelSpec(args, config, rl);
         config.model = spec;
@@ -31,14 +36,16 @@ export async function runSetup(args, packageRoot) {
             await testModel(spec, config);
         }
         const home = await ensureDurableInstall(rl, packageRoot);
-        const mcpRegistered = await offerClaudeCode(args, rl, home.bin);
-        if (!mcpRegistered) {
-            console.log(`\n${bold("connect your agent (MCP):")}`);
+        console.log(section("your agent", "how agents read athena's briefs and record what happens", "2/4"));
+        const claude = await offerClaudeCode(args, rl, home.bin);
+        if (!claude.mcp) {
+            console.log(`${bold("connect your agent (MCP):")}`);
             console.log(`  claude mcp add --scope user athena -- ${home.bin} mcp`);
             console.log(dim(`  (other MCP clients: stdio command "${home.bin} mcp")`));
         }
+        console.log(section("background capture", "sensors watch for judgment moments while you work", "3/4"));
         const serviceRunning = await offerServeService(args, rl, home.bin);
-        console.log(`\n${bold("browser sensor")} ${dim("(LinkedIn and Gmail draft edits)")}:`);
+        console.log(`${bold("browser sensor")} ${dim("(LinkedIn and Gmail draft edits)")}:`);
         console.log(`  1. chrome://extensions → Developer mode → Load unpacked → ${join(home.root, "apps", "chrome-extension")}`);
         if (serviceRunning) {
             console.log(`  2. extension options page → token ${bold(loadOrCreateServeToken())}`);
@@ -46,11 +53,22 @@ export async function runSetup(args, packageRoot) {
         else {
             console.log(`  2. run ${bold("athena serve")} and paste the printed token into the extension options page`);
         }
-        console.log(`\n${bold("the loop:")} capture runs in the background — then`);
-        console.log(`  ${cyan("athena learn")}            infer tacit rules from captured evidence`);
-        console.log(`  ${cyan("athena rules")}            see what athena believes (and how confidently)`);
-        console.log(`  ${cyan('athena brief "task"')}     the judgment an agent gets before acting`);
-        console.log(dim(`\nrules serve themselves once replay-validated; they graduate to confident\nthrough upheld outcomes — or faster via: athena review`));
+        const knowledge = await offerConnectors(args, rl, store);
+        const recap = (ok, label, detail) => `  ${ok ? green("✓") : yellow("○")} ${label.padEnd(13)} ${ok ? detail : dim(detail)}`;
+        console.log(`\n${dim("─".repeat(56))}`);
+        console.log(`${green("✓")} ${bold("athena is set up")}\n`);
+        console.log(recap(true, "model", spec));
+        console.log(recap(claude.hook || claude.mcp, "Claude Code", claude.mcp ? "sensor hook + MCP registered" : claude.hook ? "hook installed — MCP command above" : "athena hook install"));
+        console.log(recap(serviceRunning, "background", serviceRunning ? "serve service runs at login" : "athena serve install"));
+        console.log(recap(false, "browser", "load the Chrome extension — steps above (optional)"));
+        console.log(recap(knowledge.connected.length > 0, "knowledge", knowledge.connected.length > 0
+            ? `${knowledge.connected.join(", ")} connected` +
+                (knowledge.missing.length > 0 ? dim(`  (more: athena connect <${knowledge.missing.join("|")}>)`) : "")
+            : `athena connect <${knowledge.missing.join("|")}>`));
+        console.log(`\n${bold("try it:")}`);
+        console.log(`  ${cyan('athena brief "draft the weekly update"')}   ${dim("what an agent gets before acting")}`);
+        console.log(`  ${cyan("athena status")}                            ${dim("what athena has captured and learned")}`);
+        console.log(dim("\ncapture runs in the background; rules appear after real work and\ngraduate through upheld outcomes — or faster via: athena review"));
     }
     finally {
         rl?.close();
@@ -70,7 +88,6 @@ async function chooseModelSpec(args, config, rl) {
         }
         return auto.auto;
     }
-    console.log(`\n${bold("model provider")} ${dim("— powers rule inference; capture works without it")}`);
     options.forEach((option, index) => {
         console.log(`  ${bold(String(index + 1))}. ${option.name}  ${dim(option.hint)}`);
     });
@@ -92,6 +109,17 @@ async function chooseModelSpec(args, config, rl) {
 }
 async function buildProviderOptions(config) {
     const options = [];
+    // Returning users keep what they have by pressing Enter — re-running setup
+    // must never feel like reconfiguring from scratch.
+    if (config.model) {
+        const current = config.model;
+        options.push({
+            name: `keep ${current}`,
+            hint: "your current model — Enter keeps it",
+            auto: current,
+            resolve: async () => current,
+        });
+    }
     if (onPath("claude")) {
         options.push({
             name: "cli:claude",
@@ -229,7 +257,7 @@ async function offerServeService(args, rl, athenaBin) {
         return false;
     let wanted = args.includes("--yes");
     if (!wanted && rl) {
-        const answer = (await rl.question(`\nRun the browser-sensor API at login? ${dim("(background service for athena serve)")} [Y/n] `))
+        const answer = (await rl.question(`Run the browser-sensor API at login? ${dim("(background service for athena serve)")} [Y/n] `))
             .trim()
             .toLowerCase();
         wanted = answer === "" || answer === "y" || answer === "yes";
@@ -240,40 +268,84 @@ async function offerServeService(args, rl, athenaBin) {
     console.log(result.installed ? `${green("✓")} ${result.message}` : yellow(`  ${result.message}`));
     return result.installed;
 }
+/**
+ * Knowledge sources fix the day-zero brief: without them athena knows nothing
+ * until the tacit loop warms up. Never blocking, never silent — declining (or
+ * running non-interactively, where a token paste is impossible) prints exactly
+ * how to connect later, and a re-run shows what is already connected.
+ */
+async function offerConnectors(args, rl, store) {
+    const state = () => {
+        const connected = [...new Set(store.listConnections().map((c) => c.provider))];
+        return { connected, missing: Object.keys(connectors).filter((p) => !connected.includes(p)) };
+    };
+    if (args.includes("--no-connect"))
+        return state();
+    console.log(section("knowledge sources", "your docs and channels give briefs real facts on day one", "4/4"));
+    const existing = store.listConnections();
+    for (const connection of existing) {
+        console.log(`${green("✓")} ${connection.provider} connected — ${connection.label}`);
+    }
+    const { missing } = state();
+    if (missing.length === 0)
+        return state();
+    if (!rl) {
+        console.log(`  connect later with ${bold(`athena connect <${missing.join("|")}>`)} ${dim("(guided, ~2 minutes each)")}`);
+        return state();
+    }
+    for (const provider of missing) {
+        const answer = (await rl.question(`Connect ${connectors[provider].label} now? ${dim(`(${connectors[provider].connectHint})`)} [Y/n] `))
+            .trim()
+            .toLowerCase();
+        if (answer !== "" && answer !== "y" && answer !== "yes") {
+            console.log(dim(`  later: athena connect ${provider}`));
+            continue;
+        }
+        console.log("");
+        try {
+            await connectProvider(store, provider, rl, { allowSkip: true });
+        }
+        catch (error) {
+            console.log(red(`✗ connect failed: ${String(error instanceof Error ? error.message : error).slice(0, 200)}`));
+            console.log(dim(`  retry later with: athena connect ${provider}`));
+        }
+    }
+    return state();
+}
 /** Wire up Claude Code end to end: sensor hook + MCP registration. */
 async function offerClaudeCode(args, rl, athenaBin) {
     if (args.includes("--no-hook"))
-        return false;
+        return { hook: false, mcp: false };
     const hasClaudeDir = existsSync(join(homedir(), ".claude"));
     let wanted = args.includes("--hook") || (args.includes("--yes") && hasClaudeDir);
     if (!wanted && rl && hasClaudeDir) {
-        const answer = (await rl.question(`\nWire up Claude Code? ${dim("(sensor hook + MCP registration)")} [Y/n] `))
+        const answer = (await rl.question(`Wire up Claude Code? ${dim("(sensor hook + MCP registration)")} [Y/n] `))
             .trim()
             .toLowerCase();
         wanted = answer === "" || answer === "y" || answer === "yes";
     }
     if (!wanted)
-        return false;
+        return { hook: false, mcp: false };
     const { settingsPath, changed } = installClaudeCodeHook(athenaBin);
     console.log(changed
         ? `${green("✓")} hook installed in ${settingsPath} ${dim("(restart Claude Code sessions to pick it up)")}`
         : `${green("✓")} hook already installed in ${settingsPath}`);
     if (!onPath("claude"))
-        return false;
+        return { hook: true, mcp: false };
     const existing = spawnSync("claude", ["mcp", "get", "athena"], { stdio: "ignore" });
     if (existing.status === 0) {
         console.log(`${green("✓")} MCP server already registered with Claude Code`);
-        return true;
+        return { hook: true, mcp: true };
     }
     const added = spawnSync("claude", ["mcp", "add", "--scope", "user", "athena", "--", athenaBin, "mcp"], {
         encoding: "utf8",
     });
     if (added.status === 0) {
         console.log(`${green("✓")} MCP server registered with Claude Code (scope: user)`);
-        return true;
+        return { hook: true, mcp: true };
     }
     console.log(yellow(`could not register MCP automatically: ${(added.stderr ?? "").trim().slice(-200)}`));
-    return false;
+    return { hook: true, mcp: false };
 }
 /**
  * Merge the UserPromptSubmit hook into ~/.claude/settings.json. Any previous

package/dist/cli/update.js

@@ -0,0 +1,81 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { installService, serviceInstalled } from "./service.js";
+import { bold, dim, green, red, yellow } from "./format.js";
+export function compareVersions(a, b) {
+    const left = a.split(".").map(Number);
+    const right = b.split(".").map(Number);
+    for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+        const diff = (left[i] ?? 0) - (right[i] ?? 0);
+        if (diff !== 0)
+            return Math.sign(diff);
+    }
+    return 0;
+}
+export function planUpdate(opts) {
+    if (opts.devCheckout)
+        return "dev-checkout";
+    return compareVersions(opts.current, opts.latest) < 0 ? "install" : "up-to-date";
+}
+export function readPackageInfo(packageRoot) {
+    const pkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+    return { name: pkg.name, version: pkg.version };
+}
+export async function fetchLatestVersion(name, timeoutMs = 10_000) {
+    const response = await fetch(`https://registry.npmjs.org/${name}/latest`, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!response.ok)
+        throw new Error(`npm registry lookup failed: HTTP ${response.status}`);
+    const body = (await response.json());
+    if (!body.version)
+        throw new Error("npm registry reply had no version");
+    return body.version;
+}
+export function nudgeLine(current, latest) {
+    if (compareVersions(current, latest) >= 0)
+        return undefined;
+    return `\n${yellow("↑")} ${latest} is out (you run ${current}) — update with ${bold("athena update")}`;
+}
+/** One quiet line at the end of `athena status` when the registry is ahead; silent offline. */
+export async function updateNudge(packageRoot) {
+    try {
+        const { name, version } = readPackageInfo(packageRoot);
+        return nudgeLine(version, await fetchLatestVersion(name, 1_500));
+    }
+    catch {
+        return undefined;
+    }
+}
+function globalAthenaBin() {
+    const prefix = spawnSync("npm", ["prefix", "-g"], { encoding: "utf8" }).stdout?.trim();
+    if (!prefix)
+        return undefined;
+    const bin = join(prefix, "bin", "athena");
+    return existsSync(bin) ? bin : undefined;
+}
+export async function runUpdate(packageRoot, athenaBin) {
+    const { name, version } = readPackageInfo(packageRoot);
+    const latest = await fetchLatestVersion(name);
+    const plan = planUpdate({ current: version, latest, devCheckout: existsSync(join(packageRoot, ".git")) });
+    if (plan === "dev-checkout") {
+        console.log(`${yellow("dev checkout")} at ${packageRoot} — update with ${bold("git pull")} (running ${version}, registry has ${latest})`);
+        return;
+    }
+    if (plan === "up-to-date") {
+        console.log(`${green("✓")} athena ${version} is up to date`);
+        return;
+    }
+    console.log(dim(`updating ${name} ${version} → ${latest} (npm install -g)…`));
+    const install = spawnSync("npm", ["install", "-g", `${name}@latest`], { encoding: "utf8" });
+    if (install.status !== 0) {
+        console.log(red(`✗ update failed: ${(install.stderr ?? "").trim().slice(-300)}`));
+        console.log(yellow(`  retry manually: npm install -g ${name}@latest`));
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`${green("✓")} athena ${latest} installed`);
+    if (serviceInstalled()) {
+        const result = installService(globalAthenaBin() ?? athenaBin);
+        console.log(result.installed ? `${green("✓")} serve service restarted on ${latest}` : yellow(result.message));
+    }
+}

package/dist/cli.js

@@ -15,6 +15,9 @@ import { maybeAutoLearn } from "./serve/auto-learn.js";
 import { recordOutcome } from "./serve/outcome.js";
 import { loadConfig } from "./config.js";
 import { installClaudeCodeHook, runSetup } from "./cli/setup.js";
+import { readPackageInfo, runUpdate, updateNudge } from "./cli/update.js";
+import { runConnect, runDisconnect, runSync } from "./cli/connect.js";
+import { syncDueConnections } from "./connect/sync.js";
 import { bold, dim, green, red, yellow } from "./cli/format.js";
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 const athenaBin = join(packageRoot, "bin", "athena");
@@ -23,7 +26,7 @@ const HELP = `${bold("athena")} — agents that learn the tacit knowledge behind
 usage: athena <command> [args]
 
   ${bold("setup")} [--model spec] [--yes]
-                            first-run wizard: store, model provider, sensors, MCP
+                            first-run wizard: store, model, sensors, MCP, knowledge sources
                             (alias: onboard — npx useathena onboard --yes)
   ${bold("init")}                      create the local store and print MCP setup
   ${bold("status")}                    what athena has captured, learned, and served
@@ -39,10 +42,14 @@ usage: athena <command> [args]
   ${bold("record")} outcome <briefId> <uncorrected|corrected|abandoned>
   ${bold("record")} output <briefId> <text|@file>   register an agent draft for automatic outcomes
   ${bold("export")} [--out f] [--redact]  one JSON bundle of everything learned (for analysis)
+  ${bold("connect")} [provider]       connect a knowledge source, guided (no args: list connections)
+  ${bold("disconnect")} <provider>    remove a connection (already-synced sources stay)
+  ${bold("sync")} [provider]          pull new and changed content from connected sources now
   ${bold("open")} <athena://ref | id>  inspect any entity
   ${bold("hook")} install [--print]    install the Claude Code sensor hook into ~/.claude/settings.json
   ${bold("serve")} [--port n]          local API for browser sensors (default 127.0.0.1:4517)
   ${bold("serve")} install|uninstall   run the API at login (launchd/systemd user service)
+  ${bold("update")}                    update to the latest published version (restarts serve)
   ${bold("mcp")}                       run the MCP stdio server (claude mcp add athena -- athena mcp)
 
 store: ${dbPath()}  ${dim("(override with ATHENA_DB)")}
@@ -57,6 +64,10 @@ async function main() {
         console.log(HELP);
         return;
     }
+    if (command === "version" || command === "--version") {
+        console.log(readPackageInfo(packageRoot).version);
+        return;
+    }
     if (command === "hook") {
         await runHook(args);
         return;
@@ -66,7 +77,7 @@ async function main() {
         switch (command) {
             case "setup":
             case "onboard": {
-                await runSetup(args, packageRoot);
+                await runSetup(args, packageRoot, store);
                 break;
             }
             case "init": {
@@ -76,9 +87,13 @@ async function main() {
                 console.log(dim(`\nfor the guided version (model provider, sensors): athena setup`));
                 break;
             }
-            case "status":
+            case "status": {
                 console.log(cmdStatus(store));
+                const nudge = await updateNudge(packageRoot);
+                if (nudge)
+                    console.log(nudge);
                 break;
+            }
             case "rules": {
                 const domain = flag(args, "domain");
                 console.log(cmdRules(store, {
@@ -194,18 +209,41 @@ async function main() {
                 console.log(`${green("●")} athena API listening on ${bold(`http://127.0.0.1:${actualPort}`)}`);
                 console.log(`  token: ${bold(token)} ${dim("(paste into the extension options page)")}`);
                 console.log(dim("  ctrl-c to stop"));
+                // Connected sources ride the same long-lived process: check every 30
+                // minutes, sync whatever is due (the runner enforces its own 4h cadence).
+                const syncLog = (line) => console.log(dim(`  sync: ${line}`));
+                void syncDueConnections(store, syncLog);
+                const syncTimer = setInterval(() => void syncDueConnections(store, syncLog), 30 * 60 * 1000);
                 await new Promise((resolve) => {
                     process.on("SIGINT", () => {
+                        clearInterval(syncTimer);
                         server.close();
                         resolve();
                     });
                     process.on("SIGTERM", () => {
+                        clearInterval(syncTimer);
                         server.close();
                         resolve();
                     });
                 });
                 break;
             }
+            case "update": {
+                await runUpdate(packageRoot, athenaBin);
+                break;
+            }
+            case "connect": {
+                await runConnect(store, args);
+                break;
+            }
+            case "disconnect": {
+                await runDisconnect(store, args);
+                break;
+            }
+            case "sync": {
+                await runSync(store, args);
+                break;
+            }
             case "mcp": {
                 // stdio transport: stdout belongs to the protocol, so print nothing.
                 const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
@@ -321,4 +359,11 @@ async function reviewLoop(store) {
         readline.close();
     }
 }
-await main();
+try {
+    await main();
+}
+catch (error) {
+    // One clean line for expected operational failures; stack traces are for bugs.
+    console.error(red(`✗ ${error instanceof Error ? error.message : String(error)}`));
+    process.exit(1);
+}