freddie 0.0.121 → 0.0.122

package/AGENTS.md

@@ -52,9 +52,7 @@ Matrix wired: shim passes `matrixSource: process.env.FREDDIE_MATRIX_URL || <repo
 
 `agent.model_preference: []` in `~/.freddie/config.yaml` is an array of `{ provider, model? }` objects; `resolveCallLLM` tries each in order, skipping unavailable (sampler-gated) and marking failures with backoff.
 
-`src/agent/acptoapi-bridge.js` `max_tokens` defaults to 4096 — never lower. 1024 silently truncates generation tasks.
-
-`src/agent/llm_resolver.js::acpChat()` speaks the kilo ACP protocol: POST `/session` → GET `/event` (SSE) → POST `/session/<id>/message`. Streams `message.part.updated` events to assemble content; terminates on `session.idle`. **`/event` must be opened BEFORE `/message` POST or messages drop.** `ACP_BACKENDS`: kilo on `http://localhost:4780`, opencode on `http://localhost:4790`. kilo + opencode ACP backends return content only, no tool_calls — for multi-iteration tool-using loops, use OpenAI-compatible providers (mistral, openrouter, sambanova, groq).
+ACP protocol detail (`acpChat`, kilo/opencode backends, `/event`-before-`/message`, max_tokens 4096 floor) — see rs-learn (recall "Freddie ACP protocol detail").
 
 ## Plugin architecture
 
@@ -81,6 +79,17 @@ Thin shims (resolved through host, do not bypass): `src/plugins/manager.js`, `sr
 
 `plugins/gm-skill/plugin.js` registers ONE canonical skill named `gm-skill`. Resolution order: (1) `~/.claude/skills/gm-skill/SKILL.md`, (2) `node_modules/gm-cc/skills/gm-skill/SKILL.md`. All other `gm-*` platform variants (gm-cc, gm-codex, gm-cursor, gm-jetbrains, gm-kilo, gm-oc, gm-vscode, gm-zed, gm-gc, gm-copilot-cli) are DEPRECATED — do not register them. `src/host/host_helpers.js::loadCcFromNodeModules` carries `CC_EXCLUDE = new Set(['gm-cc'])` so the gm-cc npm package is not auto-discovered as a cc-plugin. test.js asserts exactly one gm-prefixed skill is registered, named `gm-skill`.
 
+## Learning: gm rs-learn is THE memory mechanism
+
+freddie learns through **gm rs-learn**, in-process, via `src/learn/gm-learn.js`. This is the single canonical learning store; the local-SQLite store is gone and the third-party providers (`plugins/memory-*/`) are legacy opt-in only.
+
+- `src/learn/gm-learn.js` lazy-loads gm-plugkit's wasm via the ESM `createPlugkit()` export (`gm-plugkit/plugkit-wasm-wrapper.js`), caches one instance process-wide, and exposes `memorize`/`recall`/`autoRecall`/`prune`/`projectNamespace`. Every call degrades to a no-op (never throws into a turn) when gm/wasm is absent. First call cold-loads the wasm + BAAI/bge-small-en-v1.5 embed model, so it is lazy off the hot path. The wasm resolves `.gm/rs-learn.db` from process cwd; namespace is per active project (`projectNamespace()`).
+- **The learning loop (workflow):** every turn (`src/agent/machine.js`) auto-recalls salient memories for the prompt on entry (injected as a "Relevant memories (gm rs-learn)" system part) and auto-learns a deduped `Q:..A:..` salient fact on substantive, non-error completion (`autoLearnTurn`, dedupe cos>=0.92, min len 40). `src/context/engine.js` `ContextPlugins.memory` does query-aware recall over the same store.
+- **The `memory` tool** (`plugins/memory/handler.js`) is the explicit manual surface over the same store: `add`->memorize, `search`->recall (score-ranked), `list`->broad recall, `forget`->prune by explicit key.
+- **gm-plugkit in-process API:** `createPlugkit()` is consumed by importing the wrapper file directly (`index.js` is CJS; the export lives on the ESM wrapper). The wrapper's CLI IIFE is guarded by `_isCliEntry` so importing it does not start the daemon.
+- Legacy migration: `node scripts/migrate-memory-to-gm.mjs [namespace]` drains old `memory_local` rows into rs-learn. `src/cli/memory_setup.js` defaults `memory.provider='gm'` (no key/config); third-party providers stay behind explicit `configureProvider`.
+- **Browser / gh-pages path:** `src/learn/gm-learn.js` is environment-aware. Where `node:module` is unavailable (e.g. thebird on gh-pages) it skips the `createPlugkit()` import and instead routes memorize-fire/recall/auto-recall/prune through a host bridge: `globalThis.__GM_DISPATCH__(verb, body) -> json|Promise<json>` (the host's already-loaded in-page plugkit.wasm) and `globalThis.__GM_NAMESPACE__` (string or fn -> active-workspace namespace). gm-learn probes both lazily each call (so a cold-loading wasm is picked up once ready) and degrades to no-op when the bridge is absent. This makes freddie LEARN in-browser with no node deps.
+
 ## Multi-project workspace
 
 Freddie supports multiple isolated projects, each with its own home directory and plugin set. Registry at `~/.freddie/projects.json` stores `{ active, projects: [{name, path, created_at}] }`. Default project (`~/.freddie`) is protected from deletion.
@@ -102,7 +111,12 @@ All web UI for freddie + thebird lives in `anentrypoint-design`. Consumers must
 - **thebird** consumes the same SDK. Bespoke windowing (`wm.js`, `launcher.js`, `shell.js`) and any context-menu / theme-toggle DOM should migrate into the SDK as reusable kits; do not extend them in thebird.
 - Theme toggle: SDK owns the controller. Consumers import it; they do NOT reimplement localStorage + `prefers-color-scheme` listeners.
 
-Build: `node scripts/build.mjs` in `C:/dev/anentrypoint-design` emits `dist/247420.js` + `dist/247420.css`. Rebuild after SDK edits or `component is not a function` kills mount silently. `server.js` serves SDK from `node_modules/anentrypoint-design/dist/`.
+Build: `node scripts/build.mjs` in `C:/dev/anentrypoint-design` emits `dist/247420.js` + `dist/247420.css`. Rebuild after SDK edits or `component is not a function` kills mount silently. `server.js` serves SDK from `node_modules/anentrypoint-design/dist/`. To witness a local SDK edit, rebuild then `cp dist/247420.{js,css}` into freddie's `node_modules/anentrypoint-design/dist/` (server aliases `sdk.js`/`sdk.css` → `247420.*`). SPA routes are `#fd-<page>` (e.g. `#fd-env`), not `#/<page>` — navigate by clicking the nav link when browser-witnessing.
+
+GUI key/path/conversation endpoints (freddie-owned `plugins/gui-*`, consumed by the SDK pages):
+- **Keys** (`plugins/gui-auth`): `GET /api/auth` (per-provider env|stored|none + masked `fingerprint`, never the raw value), `POST /api/auth {provider,key}` (stores via auth store), `DELETE /api/auth/:provider`. The SDK `env` page (labelled "keys") renders a masked-input + save/remove per provider. `GET /api/env` (`plugins/gui-env`) now reports auth-store keys too, not just `process.env`.
+- **Conversations** (`plugins/gui-sessions`): `GET /api/sessions/:id` (single), `DELETE /api/sessions/:id` (purges messages + FTS), alongside the existing list/messages/search.
+- **Paths** (`plugins/gui-projects`): full CRUD already (`GET/POST/DELETE /api/projects`, `POST /api/projects/active`).
 
 Theme attribute scoping: `class="ds-247420"` on `<html>`, `data-theme="dark|light"` on `<body>`. Putting both on the same node breaks the descendant selector and themes do not switch.
 
@@ -149,7 +163,8 @@ src/host/{contract,host,host_helpers,index}.js  # plugin contract + discovery +
 plugins/<name>/{plugin,handler}.js               # ~150 plugins: tools, platforms, memory, gui, core
 skills/                          # bundled skill bundles (creative/, software-development/, ops/, data/, planning/)
 website/                         # flatspace docs site: flatspace.config.mjs + theme.mjs + content/pages/*.yaml
-bin/freddie.js                   # commander CLI: tools, skills, profile, skin, sessions, search, gateway, acp, run, cron, batch, dashboard, help-all
+bin/freddie.js                   # commander CLI: tools, skills, profile, skin, sessions, search, gateway, acp, run, cron, batch, dashboard, help-all + user-facing key/path/conversation verbs: auth, project, session, doctor, setup
+src/cli/stdin_secret.js          # readStdinSecret — masked/piped key entry (never argv) for `auth set`
 ```
 
 ## Adding a tool
@@ -211,6 +226,17 @@ export default {
 
 `makePlatform('myname', opts)` in `src/gateway/platforms.js` instantiates the adapter via `*Adapter$` name match.
 
+## User-facing CLI: keys, paths, conversations
+
+The first-run user surface lives in `plugins/core-cli/plugin.js` (registered via `pi.cli`). Keep these terse and friendly — they are the zero-to-first-conversation path, so errors print one line, never a stack:
+
+- **Keys** — `freddie auth list|set <provider>|rm <provider>|test [provider]|show`. `set` reads the key from stdin/masked-TTY via `src/cli/stdin_secret.js` (never argv — argv leaks to shell history/`ps`); stores through `src/auth.js` `getAuthStore()`. `list` shows env var + `[set]/[--]` + source `(env|stored|none)`. Unknown provider prints the valid list (`isKnownAuthProvider` guard), never a silent no-op. `test` reuses acptoapi `isAvailable` — does NOT reimplement provider HTTP.
+- **Paths/workspaces** — `freddie project list|create <name> <path>|use <name>|rm <name>|current` over `src/projects.js`. `list` marks the active project `[*]` and shows its home path. `rm default` surfaces the projects.js guard as a friendly error. Mirrors the `gui-projects` HTTP CRUD.
+- **Conversations** — `freddie session list|show <id>|rm <id>` over `src/sessions.js`. `session list` shows the auto-derived title (first user prompt). `freddie run --resume [id]` continues the most-recent (or matched) conversation: `src/cli/interactive.js` loads prior `getMessages` into `state.messages`. The REPL also has `/sessions`, `/resume <id>`, `/keys`, `/project` slash commands.
+- **Onboarding** — `freddie doctor` (one-glance health: env checks via `src/cli/doctor.js` `runDoctor()` + provider keys + active project/home + saved-conversation count) and `freddie setup` (guided first-run via `src/cli/setup.js` `setupWizard`). Reuse these modules — do not reimplement.
+
+`src/sessions.js` exposes `getSession(id)`, `deleteSession(id)` (purges messages + rebuilds the external-content `messages_fts` index), `setSessionTitle`, and auto-derives a title from the first user prompt in `appendMessage`. **All session calls are async (libsql) — every callsite must `await`** (a bare call silently rejects and the conversation is never persisted; this was the REPL history-loss bug).
+
 ## Profile-safe code
 
 - Always `getFreddieHome()` for state paths. Never `path.join(os.homedir(), '.freddie')`.
@@ -276,8 +302,7 @@ On Windows, test.js must call `closeDb()` and log-stream `closeAll()` before exi
 
 ## Cross-project Rust gotchas
 
-- **rs-plugkit exec utility verbs**: binary advertises `exec:status`, `exec:close`, `exec:sleep` in hook help. If the Cmd enum is missing variants, use `exec:wait <secs>` for waits and read task output files via `fs.readFileSync` instead of `exec:status`.
-- **rs-exec timeout alias**: both `--timeout` (long-form) and `--timeout-ms` (plugin convention) are accepted on `Cmd::Exec` and `Cmd::Bash`.
+rs-plugkit exec utility verbs + rs-exec timeout aliases — see rs-learn (recall "Freddie cross-project Rust gotchas").
 
 ## Plugsdk integration
 
@@ -287,9 +312,7 @@ On Windows, test.js must call `closeDb()` and log-stream `closeAll()` before exi
 
 ## opencode CLI shim
 
-On Windows, use the npm install: `npm install -g opencode-ai` → `C:\Users\user\AppData\Roaming\npm\opencode.cmd`. The bun-installed shim (`C:\Users\user\.bun\bin\opencode.exe`) is broken — its wrapper looks for `C:\Users\user\node_modules\opencode-ai\bin\opencode` and fails with `MODULE_NOT_FOUND`. Do NOT `bun install -g opencode-ai`.
-
-Start ACP daemon: `& 'C:\Users\user\AppData\Roaming\npm\opencode.cmd' serve --port 4790 --hostname 127.0.0.1`. Verify via `GET http://127.0.0.1:4790/` returning 200. `OPENCODE_SERVER_PASSWORD is not set` warning is harmless for localhost.
+Windows: use the npm install (`opencode.cmd`), not the broken bun shim; ACP daemon on 4790 — see rs-learn (recall "Freddie opencode CLI shim Windows").
 
 ## scripts/sync-upstream.mjs
 
@@ -358,3 +381,5 @@ Sampler integration: agent-loop failures feed acptoapi's per-provider backoff (5
 - `website/theme.mjs` renders structured YAML via 247420 design vocabulary, not raw markdown. Consumes `page.hero` (heading/subheading/accent/body/badges/ctas), `page.sections[]` (rotating rail color green→purple→mascot→sun→flame→sky by section index, optional `lede` + per-item `benefit` italic), `page.examples[]` (railed link list with mono numeric ranks + ↗ glyph). Falls back to `page.body` markdown for prose. Style block inlined so rail/dot/chip/btn classes work without ds-247420 SDK CSS loading first. Prefer enriching hero+sections+examples over expanding body markdown.
 - **YAML colon-space trap**: in `website/content/pages/*.yaml`, any value containing `: ` outside backticks (e.g. `[linux, macos, windows]`, `requiresEnv: ['MY_KEY']` snippets) MUST be double-quoted. The parser otherwise interprets the embedded colon as a mapping and the file fails to load.
 - SSR innerHTML injection beats client dispatch for site pages — emit HTML with rail/dot/chip/btn classes + inline styles so it paints before the SDK loads.
+
+@.gm/next-step.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "freddie",
-  "version": "0.0.121",
+  "version": "0.0.122",
   "type": "module",
   "description": "Open JS agent harness built on pi-mono, floosie, xstate, and anentrypoint-design",
   "bin": {
@@ -28,11 +28,12 @@
     "@mariozechner/pi-coding-agent": "^0.70.6",
     "@mariozechner/pi-tui": "^0.70.6",
     "acptoapi": "^1.0.115",
-    "anentrypoint-design": "^0.0.144",
+    "anentrypoint-design": "latest",
     "commander": "^14.0.0",
     "express": "^5.0.0",
     "flatspace": "^1.0.18",
     "floosie": "^0.6.14",
+    "gm-plugkit": "^2.0.1535",
     "gm-skill": "latest",
     "js-yaml": "^4.1.0",
     "libsql-plugkit-client": "^0.0.10",

package/plugins/core-cli/plugin.js

@@ -5,7 +5,11 @@ import { makePlatform } from '../../src/gateway/platforms.js'
 import { AcpServer } from '../../src/acp/server.js'
 import { COMMANDS_BY_CATEGORY } from '../../src/commands/registry.js'
 import { getActiveSkin, listBuiltinSkins, setActiveSkin } from '../../src/skin/engine.js'
-import { listSessions, search } from '../../src/sessions.js'
+import { listSessions, getSession, getMessages, deleteSession, search } from '../../src/sessions.js'
+import { listAuthProviders, isKnownAuthProvider, envForProvider, hasUsableSecret, getAuthStore, clearProviderAuth, tokenFingerprint } from '../../src/auth.js'
+import { listProjects, getActiveProject, createProject, deleteProject, setActiveProject } from '../../src/projects.js'
+import { displayFreddieHome, getFreddieHome } from '../../src/home.js'
+import { readStdinSecret } from '../../src/cli/stdin_secret.js'
 
 export default {
     name: 'core-cli', surfaces: 'pi',
@@ -50,11 +54,13 @@ export default {
                 for (const c of cmds) console.log(`  /${c.name}${c.args_hint ? ' ' + c.args_hint : ''}\t${c.description}`)
             }
         } })
-        C({ name: 'run', description: 'Interactive REPL', action: async () => {
+        C({ name: 'run', description: 'Interactive REPL (--resume [id] continues a past conversation)', options: [{ flag: '--resume [id]', default: '' }], action: async (opts) => {
             const { interactive } = await import('../../src/cli/interactive.js')
             let callLLM = null
             try { ({ callLLM } = await import('../../src/agent/pi-bridge.js')) } catch {}
-            await interactive({ callLLM })
+            // --resume with no value = continue the most recent session; --resume <id> = that one.
+            const resume = opts.resume === true ? true : (opts.resume || null)
+            await interactive({ callLLM, resume })
         } })
         C({ name: 'exec', description: 'Run a single prompt through the agent and exit', options: [{ flag: '--prompt <prompt>', required: true }, { flag: '--model <model>', default: '' }, { flag: '--provider <provider>', default: '' }, { flag: '--skill <skill>', default: '' }, { flag: '--cwd <cwd>', default: '' }, { flag: '--timeout <ms>', default: '60000' }, { flag: '--witness <path>', default: '' }], action: async (opts) => {
             const { runTurn } = await import('../../src/agent/machine.js')
@@ -93,8 +99,8 @@ export default {
             if (action === 'providers') { for (const p of listKnownProviders()) console.log(p); return }
             const result = await discoverAndPersist({ provider })
             for (const [p, r] of Object.entries(result)) {
-                if (r.error) console.log(`${p.padEnd(12)} ✗ ${r.error}`)
-                else console.log(`${p.padEnd(12)} ✓ ${r.models.length} models — ${r.models.slice(0, 5).join(', ')}${r.models.length > 5 ? ', …' : ''}`)
+                if (r.error) console.log(`${p.padEnd(12)} [fail] ${r.error}`)
+                else console.log(`${p.padEnd(12)} [ok] ${r.models.length} models - ${r.models.slice(0, 5).join(', ')}${r.models.length > 5 ? ', ...' : ''}`)
             }
         } })
         C({ name: 'dashboard', description: 'Boot web dashboard', options: [{ flag: '--port <port>', default: '0' }, { flag: '--cwd <dir>', default: '' }], action: async (opts) => {
@@ -104,5 +110,126 @@ export default {
             console.log('dashboard:', d.url)
             process.on('SIGINT', async () => { await d.stop(); process.exit(0) })
         } })
+
+        // --- Key management: `freddie auth list|set|rm|test|show` ---------------
+        C({ name: 'auth', description: 'Manage provider API keys (list|set <provider>|rm <provider>|test [provider]|show)', args: [{ name: 'action', default: 'list' }, { name: 'provider' }], action: async (action, provider) => {
+            const known = (p) => { if (!isKnownAuthProvider(p)) { console.error(`unknown provider: ${p}\nknown: ${listAuthProviders().join(', ')}`); process.exit(1) } }
+            if (action === 'list' || action === 'show') {
+                for (const p of listAuthProviders()) {
+                    const env = envForProvider(p) || ''
+                    const inEnv = !!(env && process.env[env])
+                    const stored = !inEnv && !!(await getAuthStore().getCredential(env))
+                    const src = inEnv ? 'env' : (stored ? 'stored' : 'none')
+                    console.log(`${p.padEnd(12)} ${env.padEnd(22)} ${(await hasUsableSecret(p)) ? '[set]' : '[--]'} (${src})`)
+                }
+                return
+            }
+            if (action === 'set') {
+                known(provider)
+                const env = envForProvider(provider)
+                const key = await readStdinSecret(`${env} (key, hidden): `)
+                if (!key) { console.error('no key provided'); process.exit(1) }
+                await getAuthStore().setCredential(env, key)
+                console.log(`stored ${env} (${tokenFingerprint(key)})`)
+                return
+            }
+            if (action === 'rm') { known(provider); await clearProviderAuth(provider); console.log(`removed key for ${provider}`); return }
+            if (action === 'test') {
+                const sdk = await import('acptoapi').catch(() => null)
+                const targets = provider ? [provider] : listAuthProviders()
+                for (const p of targets) {
+                    if (provider) known(p)
+                    const has = await hasUsableSecret(p)
+                    if (!has) { console.log(`${p.padEnd(12)} [--] no key`); continue }
+                    let reachable = true
+                    try { if (sdk?.isAvailable) reachable = sdk.isAvailable(p) } catch {}
+                    console.log(`${p.padEnd(12)} ${reachable ? '[ok]' : '[backoff]'} key present`)
+                }
+                return
+            }
+            console.error('usage: freddie auth [list|set <provider>|rm <provider>|test [provider]|show]'); process.exit(1)
+        } })
+
+        // --- Path/workspace management: `freddie project list|create|use|rm|current` ---
+        C({ name: 'project', description: 'Manage workspace projects (list|create <name> <path>|use <name>|rm <name>|current)', args: [{ name: 'action', default: 'list' }, { name: 'name' }, { name: 'projectPath' }], action: async (action, name, projectPath) => {
+            if (action === 'list') {
+                const active = getActiveProject()
+                for (const p of listProjects()) console.log(`${p.name === active.name ? '[*]' : '[ ]'} ${p.name.padEnd(16)} ${p.path}\t${(p.created_at || '').slice(0, 10)}`)
+                return
+            }
+            if (action === 'current') { const a = getActiveProject(); console.log(`${a.name}\t${a.path}`); return }
+            if (action === 'create') {
+                if (!name || !projectPath) { console.error('usage: freddie project create <name> <absolute-path>'); process.exit(1) }
+                try { const p = createProject({ name, projectPath }); console.log(`created project ${p.name} -> ${p.path}`) }
+                catch (e) { console.error('error:', e.message); process.exit(1) }
+                return
+            }
+            if (action === 'use') {
+                if (!name) { console.error('usage: freddie project use <name>'); process.exit(1) }
+                try { const p = setActiveProject(name); console.log(`active project: ${p.name} (${p.path})`) }
+                catch (e) { console.error('error:', e.message); process.exit(1) }
+                return
+            }
+            if (action === 'rm') {
+                if (!name) { console.error('usage: freddie project rm <name>'); process.exit(1) }
+                try { deleteProject(name); console.log(`removed project ${name}`) }
+                catch (e) { console.error('error:', e.message); process.exit(1) }
+                return
+            }
+            console.error('usage: freddie project [list|create <name> <path>|use <name>|rm <name>|current]'); process.exit(1)
+        } })
+
+        // --- Conversation management: `freddie session list|show|rm` -----------
+        C({ name: 'session', description: 'Manage conversations (list|show <id>|rm <id>)', args: [{ name: 'action', default: 'list' }, { name: 'id' }], action: async (action, id) => {
+            if (action === 'list') {
+                const rows = await listSessions()
+                if (!rows.length) { console.log('(no conversations yet — run `freddie run`)'); return }
+                for (const s of rows) console.log(`${s.id.slice(0, 8)}\t${new Date(s.updated_at).toISOString().slice(0, 16).replace('T', ' ')}\t${s.title || '(untitled)'}`)
+                return
+            }
+            if (action === 'show') {
+                if (!id) { console.error('usage: freddie session show <id>'); process.exit(1) }
+                const rows = await listSessions(500)
+                const target = rows.find(s => s.id === id || s.id.startsWith(id))
+                if (!target) { console.error('no session matching:', id); process.exit(1) }
+                const s = await getSession(target.id)
+                console.log(`# ${s.title || '(untitled)'}  [${s.id.slice(0, 8)}]  ${s.model || ''}  ${new Date(s.created_at).toISOString().slice(0, 16).replace('T', ' ')}`)
+                for (const m of await getMessages(target.id)) console.log(`\n${m.role}: ${m.content || (m.tool_calls ? '[tool call]' : '')}`)
+                return
+            }
+            if (action === 'rm') {
+                if (!id) { console.error('usage: freddie session rm <id>'); process.exit(1) }
+                const rows = await listSessions(500)
+                const target = rows.find(s => s.id === id || s.id.startsWith(id))
+                if (!target) { console.error('no session matching:', id); process.exit(1) }
+                await deleteSession(target.id); console.log(`removed session ${target.id.slice(0, 8)}`)
+                return
+            }
+            console.error('usage: freddie session [list|show <id>|rm <id>]'); process.exit(1)
+        } })
+
+        // --- Onboarding: `freddie doctor` one-glance health --------------------
+        C({ name: 'doctor', description: 'Health check: keys, active project, conversations, environment', action: async () => {
+            const { runDoctor } = await import('../../src/cli/doctor.js')
+            console.log('# environment')
+            for (const c of runDoctor()) console.log(`  ${c.ok ? '[ok]' : '[--]'} ${c.name.padEnd(16)} ${c.value || c.fix || ''}`)
+            console.log('\n# provider keys')
+            let anyKey = false
+            for (const p of listAuthProviders()) { const ok = await hasUsableSecret(p); if (ok) anyKey = true; if (ok) console.log(`  [ok] ${p}`) }
+            if (!anyKey) console.log('  [--] no provider keys set — run `freddie auth set <provider>` or `freddie setup`')
+            const proj = getActiveProject()
+            console.log(`\n# workspace\n  active project: ${proj.name}\n  home: ${displayFreddieHome()}  (${getFreddieHome()})`)
+            const sessions = await listSessions(500)
+            console.log(`\n# conversations\n  ${sessions.length} saved (latest: ${sessions[0] ? (sessions[0].title || sessions[0].id.slice(0, 8)) : 'none'})`)
+        } })
+
+        // --- Onboarding: `freddie setup` guided first-run ----------------------
+        C({ name: 'setup', description: 'Guided first-run: pick provider, store a key, configure defaults', action: async () => {
+            const { setupWizard, getSetupStatus } = await import('../../src/cli/setup.js')
+            await setupWizard({})
+            const st = getSetupStatus()
+            console.log(`\nsetup complete — provider: ${st.provider}, skin: ${st.skin}`)
+            console.log('next: `freddie run` to start a conversation, or `freddie doctor` to verify')
+        } })
     },
 }

package/plugins/gm-skill/plugin.js

@@ -39,11 +39,23 @@ function parseFrontmatter(md) {
 export default {
     name: 'gm-skill',
     surfaces: 'pi',
-    register({ pi }) {
+    register({ pi, log }) {
+        const warn = (msg, data) => { try { (log && log.warn) ? log.warn(msg, data) : console.warn(`[gm-skill] ${msg}`, data || '') } catch {} }
         const skillPath = resolveSkillMd()
-        if (!skillPath) return
-        const raw = fs.readFileSync(skillPath, 'utf8')
-        const { fields, body } = parseFrontmatter(raw)
+        if (!skillPath) {
+            warn('SKILL.md unresolvable; gm-skill not registered. Run `bun x gm-plugkit@latest spool` to provision it, or install the gm-skill package.', {
+                searched: ['~/.agents/skills/gm-skill/SKILL.md', '~/.claude/skills/gm-skill/SKILL.md', 'node_modules: gm-skill, gm-cc'],
+            })
+            return
+        }
+        let raw, fields, body
+        try {
+            raw = fs.readFileSync(skillPath, 'utf8')
+            ;({ fields, body } = parseFrontmatter(raw))
+        } catch (e) {
+            warn('failed reading/parsing SKILL.md; gm-skill not registered', { file: skillPath, error: e && e.message })
+            return
+        }
         pi.skills.register({
             name: 'gm-skill',
             description: fields.description || 'AI-native software engineering harness',

package/plugins/gui-auth/plugin.js

@@ -0,0 +1,45 @@
+import { listAuthProviders, isKnownAuthProvider, envForProvider, hasUsableSecret, getAuthStore, clearProviderAuth, tokenFingerprint } from '../../src/auth.js'
+
+// Dashboard key management. Mirrors the `freddie auth` CLI verbs so users can
+// set/inspect/remove provider API keys from the web UI without env vars or a
+// restart. GET never returns raw secret values — only presence, source, and a
+// masked fingerprint.
+async function providerState(p) {
+    const env = envForProvider(p) || ''
+    const inEnv = !!(env && process.env[env])
+    const stored = inEnv ? null : await getAuthStore().getCredential(env)
+    const value = inEnv ? process.env[env] : (stored?.value || '')
+    return {
+        provider: p,
+        env,
+        set: await hasUsableSecret(p),
+        source: inEnv ? 'env' : (stored ? 'stored' : 'none'),
+        fingerprint: value ? tokenFingerprint(value) : '',
+    }
+}
+
+export default {
+    name: 'gui-auth',
+    surfaces: 'gui',
+    register({ gui }) {
+        gui.route('GET', '/api/auth', async (_, res) => {
+            const rows = []
+            for (const p of listAuthProviders()) rows.push(await providerState(p))
+            res.json(rows)
+        })
+        gui.route('POST', '/api/auth', async (req, res) => {
+            const { provider, key } = req.body || {}
+            if (!isKnownAuthProvider(provider)) return res.status(400).json({ error: 'unknown provider', known: listAuthProviders() })
+            if (!key || typeof key !== 'string' || !key.trim()) return res.status(400).json({ error: 'key required' })
+            const env = envForProvider(provider)
+            await getAuthStore().setCredential(env, key.trim())
+            res.json(await providerState(provider))
+        })
+        gui.route('DELETE', '/api/auth/:provider', async (req, res) => {
+            const provider = req.params.provider
+            if (!isKnownAuthProvider(provider)) return res.status(400).json({ error: 'unknown provider', known: listAuthProviders() })
+            await clearProviderAuth(provider)
+            res.json(await providerState(provider))
+        })
+    },
+}

package/plugins/gui-chat/plugin.js

@@ -6,16 +6,33 @@ export default {
         gui.route('POST', '/api/chat', async (req, res) => {
             const { prompt, sessionId: incomingSessionId = null, cwd, skill, provider, model } = req.body || {}
             if (!prompt) return res.status(400).json({ error: 'prompt required' })
-            res.setHeader('Content-Type', 'text/event-stream')
-            res.setHeader('Cache-Control', 'no-cache')
-            res.setHeader('Connection', 'keep-alive')
-            const send = (event, data) => res.write('event: ' + event + '\ndata: ' + JSON.stringify(data) + '\n\n')
+            // Content negotiation: the SDK dashboard chat client does a plain
+            // fetch().json() and reads `.result`/`.messages` — it is NOT an
+            // EventSource consumer. Default to a single JSON response so that
+            // path works; stream SSE only when the caller explicitly asks via
+            // `Accept: text/event-stream` (curl / EventSource clients).
+            const wantsSse = String(req.headers.accept || '').includes('text/event-stream')
             let sessionId = incomingSessionId
             if (!sessionId) {
                 try {
                     sessionId = await createSession({ platform: 'web', title: prompt.slice(0, 80), cwd: cwd || null, skill: skill || null, model: model || null })
                 } catch (_) { sessionId = null }
             }
+
+            if (!wantsSse) {
+                try {
+                    const out = await runTurn({ prompt, timeoutMs: 120000, cwd, skill, provider, model })
+                    if (out.error) return res.status(500).json({ error: out.error, sessionId })
+                    return res.json({ result: out.result || '', messages: out.messages || [], iterations: out.iterations, sessionId })
+                } catch (e) {
+                    return res.status(500).json({ error: String(e.message || e), sessionId })
+                }
+            }
+
+            res.setHeader('Content-Type', 'text/event-stream')
+            res.setHeader('Cache-Control', 'no-cache')
+            res.setHeader('Connection', 'keep-alive')
+            const send = (event, data) => res.write('event: ' + event + '\ndata: ' + JSON.stringify(data) + '\n\n')
             send('start', { ts: Date.now(), sessionId })
             try {
                 const out = await runTurn({ prompt, timeoutMs: 120000, cwd, skill, provider, model })

package/plugins/gui-env/plugin.js

@@ -1,7 +1,20 @@
+import { getAuthStore } from '../../src/auth.js'
 const ENV_KEYS = ['ANTHROPIC_API_KEY','OPENAI_API_KEY','GROQ_API_KEY','OPENROUTER_API_KEY','TELEGRAM_BOT_TOKEN','DISCORD_BOT_TOKEN','SLACK_BOT_TOKEN','SLACK_SIGNING_SECRET','WHATSAPP_API_TOKEN','SIGNAL_CLI_URL','MATRIX_HOMESERVER','MATTERMOST_URL','HONCHO_API_KEY','MEM0_API_KEY','SUPERMEMORY_API_KEY','BYTEROVER_API_KEY','HINDSIGHT_API_KEY','OPENVIKING_API_KEY','RETAINDB_API_KEY','SERPAPI_KEY','REPLICATE_API_TOKEN','SMTP_HOST','TWILIO_SID','HASS_TOKEN']
 export default {
     name: 'gui-env', surfaces: 'gui',
     register({ gui }) {
-        gui.route('GET', '/api/env', (_, res) => res.json(ENV_KEYS.map(k => ({ key: k, set: !!process.env[k] }))))
+        // A key set via `freddie auth set` (or the dashboard) lives in the auth
+        // store, not process.env. Report it as set with its source so the env
+        // page reflects the real key state, not just the shell environment.
+        gui.route('GET', '/api/env', async (_, res) => {
+            const store = getAuthStore()
+            const out = []
+            for (const k of ENV_KEYS) {
+                if (process.env[k]) { out.push({ key: k, set: true, source: 'env' }); continue }
+                const cred = await store.getCredential(k)
+                out.push({ key: k, set: !!cred?.value, source: cred?.value ? 'stored' : 'none' })
+            }
+            res.json(out)
+        })
     },
 }

package/plugins/gui-sessions/plugin.js

@@ -1,9 +1,15 @@
-import { listSessions, search, getMessages } from '../../src/sessions.js'
+import { listSessions, search, getMessages, getSession, deleteSession } from '../../src/sessions.js'
 export default {
     name: 'gui-sessions', surfaces: 'gui',
     register({ gui }) {
         gui.route('GET', '/api/sessions', async (_, res) => res.json(await listSessions()))
+        gui.route('GET', '/api/sessions/:id', async (req, res) => {
+            const s = await getSession(req.params.id)
+            if (!s) return res.status(404).json({ error: 'session not found' })
+            res.json(s)
+        })
         gui.route('GET', '/api/sessions/:id/messages', async (req, res) => res.json(await getMessages(req.params.id)))
+        gui.route('DELETE', '/api/sessions/:id', async (req, res) => res.json(await deleteSession(req.params.id)))
         gui.route('GET', '/api/search', async (req, res) => res.json(await search(String(req.query.q || ''))))
     },
 }

package/plugins/memory/handler.js

@@ -1,52 +1,29 @@
-import { db } from '../../src/db.js'
-import { getConfigValue } from '../../src/config.js'
-import { createMemoryProvider } from '../../src/plugins/memory/provider.js'
+// memory tool — the explicit manual surface over freddie's primary learning store, gm rs-learn.
+// add -> memorize (semantic embed), search -> recall (vector top-k), list -> broad recall,
+// forget -> prune by key. All routed in-process through src/learn/gm-learn.js; no local SQLite.
+import { memorize, recall, prune, projectNamespace } from '../../src/learn/gm-learn.js'
 
-async function init() {
-    const d = await db()
-    await d.exec(`CREATE TABLE IF NOT EXISTS memory_local (id INTEGER PRIMARY KEY AUTOINCREMENT, content TEXT NOT NULL, ts INTEGER NOT NULL)`)
-    if (!d._fts5_unavailable) {
-        try { await d.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS memory_local_fts USING fts5(content, content='memory_local', content_rowid='id')`) } catch (e) { d._fts5_unavailable = true }
-        try { await d.exec(`CREATE TRIGGER IF NOT EXISTS memory_local_ai AFTER INSERT ON memory_local BEGIN INSERT INTO memory_local_fts(rowid, content) VALUES (new.id, new.content); END`) } catch (e) { d._fts5_unavailable = true }
-    }
-    return d
-}
-
-function provider() {
-    const name = getConfigValue('memory.provider')
-    if (!name) return null
-    try { return createMemoryProvider(name, {}) } catch { return null }
-}
+async function ns(args) { return args.namespace || await projectNamespace() }
 
 const ACTIONS = {
-    add: async ({ content }) => {
-        if (!content) return { error: 'content required' }
-        const p = provider()
-        if (p) { await p.syncTurn([{ role: 'note', content }]); return { stored: 'remote' } }
-        const d = await init()
-        const info = await d.prepare(`INSERT INTO memory_local (content, ts) VALUES (?, ?)`).run(content, Date.now())
-        return { id: Number(info.lastInsertRowid), stored: 'local' }
+    add: async (args) => {
+        if (!args.content) return { error: 'content required' }
+        const key = await memorize(args.content, { namespace: await ns(args) })
+        return key ? { key, stored: 'rs-learn' } : { stored: 'noop', note: 'gm rs-learn unavailable' }
+    },
+    search: async (args) => {
+        const limit = args.limit || 10
+        const hits = await recall(args.query || '', { limit, namespace: await ns(args) })
+        return { items: hits.map(h => ({ content: h.text, score: h.score, key: h.key })) }
     },
-    search: async ({ query, limit = 10 }) => {
-        const p = provider()
-        if (p) return await p.prefetch(query)
-        const d = await init()
-        const likePattern = `%${query}%`
-        if (d._fts5_unavailable) {
-            const rows = await d.prepare(`SELECT id, content, ts FROM memory_local WHERE content LIKE ? ORDER BY ts DESC LIMIT ?`).all(likePattern, limit)
-            return { items: rows }
-        }
-        try {
-            const rows = await d.prepare(`SELECT m.id, m.content, m.ts FROM memory_local_fts f JOIN memory_local m ON m.id = f.rowid WHERE memory_local_fts MATCH ? ORDER BY rank LIMIT ?`).all(query, limit)
-            return { items: rows }
-        } catch {
-            const rows = await d.prepare(`SELECT id, content, ts FROM memory_local WHERE content LIKE ? ORDER BY ts DESC LIMIT ?`).all(likePattern, limit)
-            return { items: rows }
-        }
+    list: async (args) => {
+        // No native list verb; surface the most relevant memories via a broad recall.
+        const hits = await recall(args.query || 'project notes facts decisions', { limit: 50, namespace: await ns(args) })
+        return { items: hits.map(h => ({ content: h.text, score: h.score, key: h.key })) }
     },
-    list: async () => {
-        const d = await init()
-        return { items: await d.prepare(`SELECT id, content, ts FROM memory_local ORDER BY id DESC LIMIT 50`).all() }
+    forget: async (args) => {
+        if (!args.key) return { error: 'key required to forget (prune is by explicit key, never blind similarity-delete)' }
+        return await prune(args.key)
     },
 }
 
@@ -55,8 +32,8 @@ export const _tool = ({
     toolset: 'core',
     schema: {
         name: 'memory',
-        description: 'Add/search/list memory. Routes to configured provider or local SQLite fallback.',
-        parameters: { type: 'object', properties: { action: { type: 'string', enum: Object.keys(ACTIONS) }, content: { type: 'string' }, query: { type: 'string' }, limit: { type: 'number' } }, required: ['action'] },
+        description: 'Add/search/list/forget long-term memory, backed by gm rs-learn (semantic vector recall). add embeds a fact; search returns score-ranked semantic hits; list surfaces relevant memories; forget prunes by key.',
+        parameters: { type: 'object', properties: { action: { type: 'string', enum: Object.keys(ACTIONS) }, content: { type: 'string' }, query: { type: 'string' }, key: { type: 'string' }, namespace: { type: 'string' }, limit: { type: 'number' } }, required: ['action'] },
     },
     handler: async (args) => {
         const fn = ACTIONS[args.action]