freddie 0.0.41

package/AGENTS.md

@@ -0,0 +1,180 @@
+# Freddie — Agent Guide
+
+Instructions for AI coding assistants working on Freddie.
+
+## Substrate (do not reimplement)
+
+- `@mariozechner/pi-coding-agent` — agent + tools + interactive TUI. Use `AgentSession`, `BashExecutionComponent`, `ModelRegistry`, `InteractiveMode`, `FileAuthStorageBackend`, `ExtensionRunner`.
+- `@mariozechner/pi-agent-core` — `Agent`, `agentLoop`, `runAgentLoop`, `streamProxy`. Wrap in xstate, do not rewrite.
+- `@mariozechner/pi-ai` — `complete`, `completeSimple`, `AssistantMessageEventStream`, `registerApiProvider`, `getModel`, `calculateCost`, `parseStreamingJson`, `isContextOverflow`. THE provider layer.
+- `@mariozechner/pi-tui` — TUI primitives (Ink-equivalent).
+- `floosie` v0.6.14 — `ProcessorMachine` (xstate). Use for gateway pipelines.
+- `anentrypoint-design` v0.0.27 — webjsx + ripple-ui. Use for any web UI; do NOT add React. Source in C:/dev/anentrypoint-design; freddie links via `file:../anentrypoint-design`.
+- `xstate` v5 — every long-lived state machine (agent turns, gateway lifecycle, approvals).
+
+## Layout
+
+```
+src/home.js                      # getFophHome, applyProfileOverride
+src/config.js                    # loadConfig, saveConfigValue, DEFAULT_CONFIG, _config_version migrations
+src/sessions.js                  # better-sqlite3 + FTS5
+src/auth.js                      # FileAuthStore for credentials
+src/tools/registry.js            # tool registration + dispatch
+src/tools/{bash,read,write,edit,grep,todo,memory,delegate,web_search,image_gen,browser}.js
+src/tools/environments/{local,docker,ssh,index}.js  # execution environments
+src/toolsets.js                  # _FREDDIE_CORE_TOOLS, getEnabledToolSchemas
+src/agent/machine.js             # xstate turn machine
+src/agent/pi-bridge.js           # @mariozechner/pi-ai callLLM adapter
+src/agent/compress/{tokens,policy,prompt,prune,fallback,compressor,index}.js  # context compressor
+src/commands/registry.js         # CommandDef + resolveCommand + gateway/telegram/slack views
+src/commands/profile.js          # profile CRUD
+src/cli/interactive.js           # readline REPL, skin-aware
+src/context/engine.js            # context block builders (file, skills, memory)
+src/cron/{scheduler,cron-parse}.js  # persistent cron jobs
+src/batch.js                     # parallel batch runner
+src/web/{server,index.html}      # dashboard (express + anentrypoint-design webjsx)
+src/gateway/run.js               # Gateway + hooks
+src/gateway/platforms/*.js       # webhook + api_server + 16 functional adapters
+src/acp/server.js                # JSON-RPC stdio
+src/plugins/manager.js           # PluginManager
+src/plugins/memory/{provider,_index,honcho,mem0,supermemory,byterover,hindsight,holographic,openviking,retaindb}.js
+src/skills/index.js              # SKILL.md loader
+src/skin/engine.js               # _BUILTIN_SKINS + load/get/set
+src/observability/log.js         # structured logs
+src/observability/debug.js       # /debug registry
+skills/                          # bundled skill bundles (creative/, software-development/, ops/, data/, planning/)
+website/                         # flatspace docs site: flatspace.config.mjs + theme.mjs + content/pages/*.yaml + docs/ (build output)
+bin/freddie.js                     # commander CLI: tools, skills, profile, skin, sessions, search, gateway, acp, run, cron, batch, dashboard, help-all
+```
+
+## Adding a tool
+
+```js
+import { registry } from './tools/registry.js'
+
+registry.register({
+    name: 'my_tool',
+    toolset: 'core',
+    schema: { name: 'my_tool', description: '…', parameters: { type: 'object', properties: { x: { type: 'string' } }, required: ['x'] } },
+    handler: async (args, ctx) => ({ ok: true, x: args.x }),
+    checkFn: () => !!process.env.MY_KEY,
+    requiresEnv: ['MY_KEY'],
+})
+```
+
+Drop the file in `src/tools/`. Auto-discovered by `discoverBuiltinTools()`.
+
+## Adding a slash command
+
+Add a `CommandDef` to `COMMAND_REGISTRY` in `src/commands/registry.js`:
+
+```js
+{ name: 'mycmd', description: '…', category: 'Session', aliases: ['mc'], args_hint: '[arg]' }
+```
+
+Dispatch happens against the canonical name resolved via `resolveCommand()`. Gateway/telegram/slack views derive automatically.
+
+## Adding a gateway platform
+
+1. Drop `src/gateway/platforms/<name>.js`
+2. Extend `EventEmitter`, implement `start/stop/send`, emit `'message'`
+3. `Gateway.register('name', adapter)` wires inbound to the agent
+
+## Profile-safe code
+
+- Always `getFophHome()` for state paths. Never `path.join(os.homedir(), '.freddie')`.
+- Always `displayFophHome()` for user-visible messages (returns `~/.freddie` or `~/.freddie/profiles/<name>`).
+- Profile operations are HOME-anchored: `getProfilesRoot()` returns `~/.freddie/profiles` regardless of active profile.
+
+## Cache safety
+
+Slash commands that mutate system-prompt state default to deferred invalidation; opt-in `--now` for immediate. Mid-conversation prompt rewrites blow the cache and cost real money.
+
+## Testing
+
+One `test.js` at project root. ≤200 lines. Plain assertions, real data, real services. No mocks. No fixtures. No `tests/` dir. New behavior = extend `test.js`, not a new test file.
+
+## Substrate gotchas
+
+- `pi-coding-agent` ships a photon-rs wasm; install needs network. Verified working on Windows.
+- `pi-ai` reads provider keys via `findEnvKeys` / `getEnvApiKey`. Match its env var names (`ANTHROPIC_API_KEY`, etc.).
+- `floosie.ProcessorMachine` is an xstate machine. Compose, don't fork.
+- **Browser inline `<script type="module">` syntax errors** — When a pageerror reports "missing ) after argument list" with no file:line info, extract the script body to a separate `.js` file and run `node --check path/to/file.js`. Browsers swallow line numbers for inline modules; node's V8 parser prints exact line. Essential for debugging unbalanced parens in webjsx-style nested `h()` calls. (Confirmed 2026-04-30: freddie dashboard app.js, line 133.)
+
+## Subsystem guide
+
+| Concern | Freddie location |
+|---|---|
+| Agent loop | `src/agent/machine.js` (xstate) + `@mariozechner/pi-agent-core` |
+| CLI entry | `bin/freddie.js` (commander) + pi-coding-agent InteractiveMode |
+| Tool registry | `src/tools/registry.js` + `src/tools/{bash,read,write,edit,grep}.js` |
+| Toolsets | `src/toolsets.js` |
+| Session store | `src/sessions.js` (better-sqlite3 + FTS5) |
+| Home + profiles | `src/home.js` |
+| Structured logging | `src/observability/log.js` |
+| Config | `src/config.js` |
+| Commands | `src/commands/registry.js` |
+| Skin engine | `src/skin/engine.js` |
+| Gateway + platforms | `src/gateway/run.js` + `src/gateway/platforms/*.js` |
+| ACP (JSON-RPC stdio) | `src/acp/server.js` |
+| TUI | substrate (`pi-tui` + pi-coding-agent) |
+| Plugins + memory | `src/plugins/manager.js` + `src/plugins/memory/provider.js` |
+| Skills loader | `src/skills/index.js` — content drops into `~/.freddie/skills/` |
+| Context compressor | `src/agent/compress/{tokens,policy,prompt,prune,fallback,compressor,index}.js` |
+| Documentation site | `website/` (flatspace + content/pages/*.yaml + theme.mjs) |
+| Cron scheduler | `src/cron/{scheduler,cron-parse}.js` |
+| Batch runner | `src/batch.js` |
+| Execution environments | `src/tools/environments/{local,docker,ssh}.js` (modal/daytona/singularity = explicit residual) |
+| Dashboard | `src/web/{server,index.html}` (anentrypoint-design webjsx) |
+| Auth store | `src/auth.js` (FileAuthStore) + pi-ai key resolution |
+| Context engine | `src/context/engine.js` |
+| Browser tool | `src/tools/browser.js` (puppeteer-core, lazy) |
+| Image gen | `src/tools/image_gen.js` (openai/replicate) |
+| Web search | `src/tools/web_search.js` (DDG/SerpAPI) |
+| Todo | `src/tools/todo.js` |
+| Memory tool | `src/tools/memory.js` |
+| Delegate | `src/tools/delegate.js` |
+| Bundled skills | `skills/` (5 categories, 12 SKILL.md placeholders) |
+| Integration tests | one `test.js` at root per gm policy |
+
+## Cross-project Rust gotchas
+
+- **rs-plugkit exec utility verbs** (2026-04-30) — The plugkit.exe binary advertises `exec:status`, `exec:close`, `exec:sleep` in hook help, but the Cmd enum was missing Status/Close/Sleep variants. Fix applied to c:\dev\rs-plugkit\src\main.rs; awaiting CI rebuild. Until rebuilt: use `exec:wait <secs>` for waits, read task output files directly via fs.readFileSync instead of exec:status.
+- **rs-exec timeout alias** — Both `--timeout` (long-form) and `--timeout-ms` (plugin convention) are accepted due to alias added to c:\dev\rs-exec\src\main.rs. Both Cmd::Exec and Cmd::Bash support either form.
+
+## Integration test status (2026-04-30)
+
+All 21 named integration tests in `test.js` pass (exit 0). Subsystem coverage:
+- agent loop, CLI, gateway, plugins, skills, sessions, cron, batch, dashboard, ACP, web, context-engine, compressor, auth, observability
+
+## Windows libuv cleanup caveat
+
+`test.js` adds explicit cleanup hooks before exit (`closeDb()`, `closeAll()` for log streams) to prevent libuv handle-teardown crash on Windows. Without these, exit hangs or returns non-zero. Critical for stability on Windows hosts.
+
+## LLM backends and acptoapi
+
+- **acptoapi bridge** — Integrated at `src/agent/acptoapi-bridge.js` + `src/agent/llm_resolver.js` (commit 5f55f1e). Localhost API (default port 4800) converting OpenAI/Anthropic SDK calls to multiple backends: Kilo Code, opencode, Claude CLI, Anthropic API, Gemini, Ollama, Bedrock. Endpoint `/v1/chat/completions`, OpenAI-compatible, accepts `Bearer none` auth.
+- **LLM resolver priority** — (1) explicit `callLLM` arg, (2) pi-bridge if `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GROQ_API_KEY` / `OPENROUTER_API_KEY` env set, (3) acptoapi if `/v1/models` returns 200, (4) throw with actionable error. Configurable via `FREDDIE_LLM_URL` and `FREDDIE_LLM_MODEL` env vars.
+- **acptoapi Claude backend tool-call mismatch** — acptoapi's Claude backend returns Anthropic-style XML `<function_calls><invoke name="bash">…</invoke></function_calls>` in message content, not OpenAI `tool_calls` JSON array. This breaks the agent's tool-loop auto-fire. Workaround: use real Anthropic API key + pi-bridge for proper tool dispatch, or use structured `callLLM` stubs in tests.
+
+## Learning audit
+
+- 2026-05-01: 5 items queried (pi-ai keys, profile paths, cache safety, floosie composition, browser errors); rs-learn store unavailable (exec:recall returned no results). 0 items migrated. New facts (anentrypoint-design build, dashboard live-rerender caveat, libuv spawn caveat) ingested directly into rs-learn; audit will retry in future sessions.
+- 2026-05-01 (session 2): 5 items queried (pi-ai env keys, profile safe paths, cache safety, floosie composition, browser syntax errors). rs-learn store still empty. 0 items migrated. Refined anentrypoint-design source/dist skew entry in AGENTS.md to include silent-failure pageerror diagnostic. New fact `reference/anentrypoint-design-dist-rebuild` ingested.
+
+## Dashboard web UI caveats
+
+- **anentrypoint-design v0.0.27 source/dist skew** — Published npm package lags behind source in C:/dev/anentrypoint-design. New components (EmptyState, etc.) present in source but missing from dist/247420.js until rebuild. Run `node scripts/build.mjs` in the design repo (emits dist/247420.js ~441KB + 247420.css; build ~150ms); warning "[247420] missing css: vendor/rippleui-1.12.1.css" is benign. Skip rebuild and browser-witness new component usage: silent pageerror "component is not a function" kills app mount with no output in #app. freddie/package.json uses `file:../anentrypoint-design` so npm install always mirrors rebuilt dist without publish cycles.
+- **Live page rerender caveat** — AppState.body caching (page computed once at navigation, body saved) breaks for live routes like #/chat where AppState is mutated mid-flight (SSE pushes new messages). Fix: detect live routes in rerender(), recompute body: `if (AppState.hash === '#/chat') { Promise.resolve(PAGES['#/chat']()).then(b => { AppState.body = b; _mount() }); return }`. Any future live-streaming pages (cron output, traces) need the same treatment.
+- **libuv spawn caveat** — Spawning createDashboard() from exec:nodejs and keeping process alive triggers libuv UV_HANDLE_CLOSING crash on shutdown. Reliable alternative: boot via `node bin/freddie.js dashboard --port <port>`. Liveness checks: exec:browser → page.goto → window.__debug.dashboard() returns {booted, ts, framework, route}; window.__debug.chat() exposes {messages, streaming, draft}; window.__debug.sendChat(text) drives round-trips.
+
+## Residual complement (NOT ported this session)
+
+Genuinely out of session reach, with reasons:
+
+- **Real credentials per platform** — adapters work; setup needs you to provide TELEGRAM_BOT_TOKEN, DISCORD_BOT_TOKEN, SLACK_BOT_TOKEN, etc. before `start()` succeeds. Listed in each adapter's `getRequiredEnv()`.
+- **Memory provider API accounts** — 8 provider modules call real endpoints. Test runs construct objects but don't hit external APIs without keys (HONCHO_API_KEY etc.).
+- **modal / daytona / singularity environments** — only local/docker/ssh ported. The other three are heavyweight remote-execution deps (Modal SDK, Daytona Cloud, Singularity containers).
+- **Bedrock / codex provider adapters** — `pi-ai` covers Anthropic/OpenAI/Groq. Adding bedrock/codex requires registering custom providers via `pi-ai`'s `registerApiProvider`.
+- **TUI Ink rewrite** — `pi-tui` IS the substrate (architectural choice, not a port).
+- **15k pytest tests** — single `test.js` per gm policy.

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.0.8] - 2026-05-02
+
+### Changed
+- Redesigned flatspace GitHub Pages with pro-rata anentrypoint-design patterns
+  - home: Hero + Manifesto + quick-start section with npm install + 3 CLI commands
+  - architecture: Crumb breadcrumbs + Section subsystems + Receipt tech specs
+  - tools: Core/Environment/External tool groups with full descriptions
+  - platforms: Chat/Messaging/Enterprise/Generic platform categories (16 adapters)
+  - skills: Manifesto listing 5 bundled skill categories
+  - cli: Install component + Top Commands section with 4+ commands + usage examples
+  - development: Changelog + integration test status (21/21 passing) + AGENTS.md link
+
+### Build
+- flatspace build outputs 7 HTML pages + .nojekyll to website/docs/
+- All pages generated without errors, validated via HTTP and browser witness
+- Dark theme with gold headings, blue links, responsive layout
+
+## [0.0.7] - 2026-04-30
+
+- Use npm anentrypoint-design instead of file: link so CI can install it
+
+## [0.0.6] - 2026-04-25
+
+- Redesign dashboard web view with anentrypoint-design pro-rata patterns
+
+## Previous Releases
+
+See git history for earlier versions.

package/README.md

@@ -0,0 +1,130 @@
+# Freddie
+ 
+An open JS agent harness built on pi-mono, xstate, floosie, and anentrypoint-design. Features a full gateway, context compressor, multi-platform adapters, and a live dashboard — built with:
+
+- [`@mariozechner/pi-coding-agent`](https://www.npmjs.com/package/@mariozechner/pi-coding-agent) — agent + tools + interactive TUI substrate
+- [`@mariozechner/pi-agent-core`](https://www.npmjs.com/package/@mariozechner/pi-agent-core) — agent loop primitives
+- [`@mariozechner/pi-ai`](https://www.npmjs.com/package/@mariozechner/pi-ai) — provider abstraction (Anthropic / OpenAI / Groq / …)
+- [`@mariozechner/pi-tui`](https://www.npmjs.com/package/@mariozechner/pi-tui) — TUI primitives
+- [`floosie`](https://www.npmjs.com/package/floosie) — gateway stream pipeline (xstate-backed)
+- [`xstate`](https://www.npmjs.com/package/xstate) — agent turn machine + lifecycle state machines
+- [`anentrypoint-design`](https://www.npmjs.com/package/anentrypoint-design) — webjsx + ripple-ui design system (replaces React for the dashboard)
+- [`flatspace`](https://www.npmjs.com/package/flatspace) — flat-file CMS + static site builder (powers the `website/` documentation site)
+
+See [AGENTS.md](./AGENTS.md) for the full subsystem guide and residual complement.
+
+## Install
+
+```sh
+cd c:/dev/freddie
+npm install
+```
+
+## Use
+
+```sh
+# List tools (>=11 registered)
+node bin/freddie.js tools
+
+# All slash-style commands
+node bin/freddie.js help-all
+
+# Interactive REPL (skin-aware, slash commands routed via registry)
+node bin/freddie.js run
+
+# Profile management (~/.freddie/profiles/*)
+node bin/freddie.js profile list
+node bin/freddie.js profile create coder
+node bin/freddie.js profile switch coder
+
+# Skin engine (default | ares | mono | slate)
+node bin/freddie.js skin
+node bin/freddie.js skin ares
+
+# Sessions and search
+node bin/freddie.js sessions
+node bin/freddie.js search "<query>"
+
+# Cron scheduler (persistent jobs in SQLite)
+node bin/freddie.js cron list
+node bin/freddie.js cron add "*/5 * * * *" "summarize my email"
+node bin/freddie.js cron tick
+
+# Batch runner (parallel runs, JSONL output)
+node bin/freddie.js batch prompts.txt --concurrency 4
+
+# Web dashboard (express + anentrypoint-design webjsx)
+node bin/freddie.js dashboard --port 3000
+
+# Gateway (webhook + api_server + 16 platform adapters)
+node bin/freddie.js gateway --port 3000
+
+# ACP server (JSON-RPC over stdio for IDE integrations)
+node bin/freddie.js acp
+```
+
+## Tools
+
+Built-in: `bash`, `read`, `write`, `edit`, `grep`, `todo`, `memory`, `delegate`, `web_search`, `image_gen`, `browser`. Auto-discovered from `src/tools/*.js`.
+
+## Platforms
+
+`src/gateway/platforms/`: webhook, api_server, telegram, discord, slack, whatsapp, signal, matrix, mattermost, email, sms, dingtalk, wecom, weixin, feishu, qqbot, bluebubbles, homeassistant. Each adapter exposes `getRequiredEnv()` and throws clear messages when credentials are absent.
+
+## Memory providers
+
+`src/plugins/memory/`: honcho, mem0, supermemory, byterover, hindsight, holographic (local-FS), openviking, retaindb. Set `memory.provider` in `~/.freddie/config.yaml` and the corresponding `*_API_KEY`.
+
+## Layout
+
+```
+freddie/
+├── bin/freddie.js                  # commander CLI: tools, skills, profile, skin, sessions, search, gateway, acp, run, cron, batch, dashboard, help-all
+├── src/
+│   ├── home.js                   # getFophHome + profiles
+│   ├── config.js                 # YAML + migrations
+│   ├── sessions.js               # SQLite + FTS5
+│   ├── auth.js                   # FileAuthStore (~/.freddie/auth/)
+│   ├── batch.js                  # parallel batch runner
+│   ├── tools/                    # registry + 11 built-in tools + environments/
+│   ├── toolsets.js
+│   ├── agent/{machine,pi-bridge}.js   # xstate turn machine + pi-ai bridge
+│   ├── commands/{registry,profile}.js # CommandDef + CRUD
+│   ├── cli/interactive.js        # readline REPL
+│   ├── context/engine.js         # pluggable context blocks
+│   ├── cron/{scheduler,cron-parse}.js
+│   ├── web/{server,index.html}   # dashboard
+│   ├── gateway/                  # Gateway + 18 platform adapters
+│   ├── acp/server.js             # JSON-RPC stdio
+│   ├── plugins/                  # PluginManager + 8 memory backends
+│   ├── skills/index.js           # SKILL.md loader
+│   ├── skin/engine.js            # 4 built-in skins, YAML user-skins
+│   └── observability/            # structured logs + /debug
+│   └── agent/compress/{tokens,policy,prompt,prune,fallback,compressor,index}.js  # context compressor
+├── skills/                       # bundled SKILL.md (creative, software-development, ops, data, planning)
+├── website/                      # flatspace-powered docs site (content/pages/*.yaml + theme.mjs)
+├── AGENTS.md
+├── CHANGELOG.md
+└── test.js                       # 21 named groups, ≤200 lines, real services
+```
+
+## Status
+
+Tier 0.3 complete and witnessed: 21 named tests passing, dashboard + website both live-witnessed via headless browser.
+
+- 16 gateway platforms with functional wire-format code (no throwing stubs)
+- 8 memory providers call real endpoints (or local-FS for `holographic`)
+- 11 built-in tools (bash/read/write/edit/grep/todo/memory/delegate/web_search/image_gen/browser)
+- Cron scheduler, parallel batch runner, auth store, context-engine, pi-ai bridge, interactive REPL
+- **Full context compressor** (`src/agent/compress/*`) with handoff-framed summary prefix, structured summarizer prompt, head/middle/tail policy, tool-output pre-pruning, summary-budget ratio, iterative summary update, and 600s failure cooldown
+- **Documentation site** at `website/` powered by `flatspace` (NOT docusaurus). Build with `cd website && node ../node_modules/flatspace/bin/flatspace.js build` — output to `website/docs/` for GitHub Pages.
+
+What's not in the box yet (residual, see AGENTS.md): real credentials per platform / memory backend; modal / daytona / singularity environments; bedrock / codex provider adapters.
+
+## Testing
+
+```sh
+node test.js
+```
+
+One integration test at root, ≤200 lines, plain assertions, real services. No fixtures, no mocks. Dashboard validation also runs through a live `exec:browser` witness during EMIT/VERIFY.

package/bin/freddie.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+import { Command } from 'commander'
+import { registry, discoverBuiltinTools } from '../src/tools/registry.js'
+import { listAllProfiles, createProfile, deleteProfile, switchProfile } from '../src/commands/profile.js'
+import { listSkills } from '../src/skills/index.js'
+import { Gateway } from '../src/gateway/run.js'
+import { WebhookAdapter } from '../src/gateway/platforms/webhook.js'
+import { ApiServerAdapter } from '../src/gateway/platforms/api_server.js'
+import { AcpServer } from '../src/acp/server.js'
+import { COMMAND_REGISTRY, COMMANDS_BY_CATEGORY } from '../src/commands/registry.js'
+import { getActiveSkin, listBuiltinSkins, setActiveSkin } from '../src/skin/engine.js'
+import { listSessions, search } from '../src/sessions.js'
+
+const program = new Command()
+program.name('freddie').version('0.1.0').description('Freddie — JS port of hermes-agent built on pi-mono')
+
+program.command('tools')
+    .description('List/inspect tools')
+    .argument('[action]', 'list | get', 'list')
+    .argument('[name]')
+    .action(async (action, name) => {
+        await discoverBuiltinTools()
+        if (action === 'get' && name) { console.log(JSON.stringify(registry.get(name)?.schema, null, 2)); return }
+        for (const t of registry.list()) console.log(`${t.toolset.padEnd(10)} ${t.name}\t${t.schema.description.slice(0, 60)}`)
+    })
+
+program.command('skills')
+    .description('List skills')
+    .argument('[action]', 'list', 'list')
+    .action(() => {
+        for (const s of listSkills()) console.log(`${s.name}\t${s.description.slice(0, 80)}`)
+    })
+
+program.command('profile')
+    .argument('[action]', 'list | create | switch | delete', 'list')
+    .argument('[name]')
+    .action((action, name) => {
+        if (action === 'list') { for (const p of listAllProfiles()) console.log(p); return }
+        if (action === 'create') { createProfile(name); console.log('created:', name); return }
+        if (action === 'delete') { deleteProfile(name); console.log('deleted:', name); return }
+        if (action === 'switch') { switchProfile(name); console.log('switched:', name || 'default'); return }
+    })
+
+program.command('skin')
+    .argument('[name]')
+    .action((name) => {
+        if (!name) { console.log('active:', getActiveSkin().name); console.log('available:', listBuiltinSkins().join(', ')); return }
+        setActiveSkin(name); console.log('switched to:', name)
+    })
+
+program.command('sessions').action(() => { for (const s of listSessions()) console.log(`${s.id}\t${s.platform}\t${new Date(s.updated_at).toISOString()}\t${s.title || ''}`) })
+program.command('search').argument('<query>').action((q) => { for (const r of search(q)) console.log(`${r.session_id}\t${(r.content || '').slice(0, 100)}`) })
+
+program.command('gateway')
+    .option('--port <port>', 'webhook port', '0')
+    .action(async (opts) => {
+        const webhook = new WebhookAdapter({ port: Number(opts.port) })
+        const api = new ApiServerAdapter({ port: 0 })
+        const gw = new Gateway({ platforms: { webhook, api_server: api } })
+        await gw.start()
+        console.log('webhook port:', webhook.port, '\napi_server port:', api.port)
+        process.on('SIGINT', async () => { await gw.stop(); process.exit(0) })
+    })
+
+program.command('acp').action(() => { const s = new AcpServer(); s.start() })
+
+program.command('help-all').action(() => {
+    for (const [cat, cmds] of Object.entries(COMMANDS_BY_CATEGORY)) {
+        console.log(`\n# ${cat}`)
+        for (const c of cmds) console.log(`  /${c.name}${c.args_hint ? ' ' + c.args_hint : ''}\t${c.description}`)
+    }
+})
+
+program.command('run').description('Run interactive REPL').action(async () => {
+    const { interactive } = await import('../src/cli/interactive.js')
+    let callLLM = null
+    try { ({ callLLM } = await import('../src/agent/pi-bridge.js')) } catch {}
+    await interactive({ callLLM })
+})
+
+program.command('cron')
+    .argument('[action]', 'list | add | cancel | delete | tick', 'list')
+    .argument('[arg1]')
+    .argument('[arg2]')
+    .action(async (action, a1, a2) => {
+        const { listJobs, createJob, cancelJob, deleteJob, tick } = await import('../src/cron/scheduler.js')
+        if (action === 'list') { for (const j of listJobs()) console.log(`${j.id}\t${j.cron}\t${j.enabled ? 'on ' : 'off'}\t${j.prompt.slice(0, 60)}`); return }
+        if (action === 'add') { const id = createJob({ cron: a1, prompt: a2 }); console.log('created:', id); return }
+        if (action === 'cancel') { cancelJob(Number(a1)); console.log('cancelled:', a1); return }
+        if (action === 'delete') { deleteJob(Number(a1)); console.log('deleted:', a1); return }
+        if (action === 'tick') { console.log('fired:', (await tick()).length); return }
+    })
+
+program.command('batch')
+    .argument('<file>', 'JSONL or TXT prompts file')
+    .option('--concurrency <n>', '', '4')
+    .option('--model <model>', '', '')
+    .action(async (file, opts) => {
+        const fs = await import('node:fs')
+        const { runBatch } = await import('../src/batch.js')
+        const raw = fs.readFileSync(file, 'utf8').trim().split('\n')
+        const prompts = raw.map(l => { try { return JSON.parse(l).prompt || JSON.parse(l) } catch { return l } }).filter(Boolean)
+        const out = await runBatch({ prompts, concurrency: Number(opts.concurrency), model: opts.model })
+        console.log('batch:', out.id, '\nfile:', out.file, '\nresults:', out.results.length)
+    })
+
+program.command('dashboard')
+    .option('--port <port>', '', '0')
+    .action(async (opts) => {
+        const { createDashboard } = await import('../src/web/server.js')
+        const d = await createDashboard({ port: Number(opts.port) })
+        console.log('dashboard:', d.url)
+        process.on('SIGINT', async () => { await d.stop(); process.exit(0) })
+    })
+
+program.parseAsync(process.argv).catch(e => { console.error(e); process.exit(1) })

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "freddie",
+  "version": "0.0.41",
+  "type": "module",
+  "description": "Freddie — Free Realtime Dynamic Dialogue Information Engine. Open JS agent harness built on pi-mono, floosie, xstate, and anentrypoint-design",
+  "bin": {
+    "freddie": "./bin/freddie.js"
+  },
+  "main": "./src/index.js",
+  "scripts": {
+    "start": "node bin/freddie.js",
+    "test": "node test.js"
+  },
+  "dependencies": {
+    "@mariozechner/pi-agent-core": "^0.70.6",
+    "@mariozechner/pi-ai": "^0.70.6",
+    "@mariozechner/pi-coding-agent": "^0.70.6",
+    "@mariozechner/pi-tui": "^0.70.6",
+    "anentrypoint-design": "^0.0.29",
+    "commander": "^14.0.0",
+    "express": "^5.0.0",
+    "flatspace": "^1.0.18",
+    "floosie": "^0.6.14",
+    "js-yaml": "^4.1.0",
+    "@libsql/client": "^0.5.0",
+    "xstate": "^5.31.0",
+    "zod": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skills/",
+    "README.md",
+    "CHANGELOG.md",
+    "AGENTS.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AnEntrypoint/freddie.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AnEntrypoint/freddie/issues"
+  },
+  "homepage": "https://github.com/AnEntrypoint/freddie#readme",
+  "license": "MIT",
+  "keywords": [
+    "ai",
+    "agent",
+    "llm",
+    "cli",
+    "coding-agent",
+    "freddie",
+    "pi-mono",
+    "xstate"
+  ]
+}

package/skills/creative/README.md

@@ -0,0 +1,3 @@
+# creative skills
+
+Built-in skills in this category. Drop additional SKILL.md files in subdirectories.

package/skills/creative/architecture-diagram/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: architecture-diagram
+description: Generate system architecture diagrams as Mermaid, PlantUML, or ASCII art from a description or codebase
+category: creative
+---
+
+# Architecture Diagram
+
+You are an expert software architect. Produce clear, accurate architecture diagrams from user descriptions or codebases.
+
+## Inputs you accept
+
+- Natural language description of a system ("I have a Node.js API, a Postgres DB, and a Redis cache")
+- A directory path or list of source files to analyse
+- An existing diagram to update or extend
+
+## Output formats
+
+Choose the best format for the request:
+1. **Mermaid** (`graph TD`, `sequenceDiagram`, `C4Context`) — preferred for GitHub/Notion
+2. **PlantUML** (`@startuml`) — preferred for enterprise/Java shops
+3. **ASCII art** — for terminal output or when no renderer is available
+
+## Process
+
+1. Identify the **system boundary** — what is in scope vs external.
+2. Identify **components**: services, databases, queues, external APIs, clients.
+3. Identify **data flows**: reads, writes, events, API calls.
+4. Group components into **layers** (presentation / application / data / infra).
+5. Label every arrow with the **protocol or action** (HTTP GET, SQL, AMQP publish).
+6. Add a legend if non-obvious glyphs are used.
+
+## Rules
+
+- Keep diagrams under 20 nodes. Split into sub-diagrams if larger.
+- Never invent components not mentioned or clearly implied.
+- Always show the entry point and the persistence layer.
+- For sequence diagrams: happy path first, then `alt` error blocks.
+
+## Example (Mermaid)
+
+```mermaid
+graph TD
+    Browser -->|HTTPS| API[Node.js API]
+    API -->|SQL| DB[(Postgres)]
+    API -->|GET/SET| Cache[(Redis)]
+    API -->|publish| Queue[RabbitMQ]
+    Worker -->|consume| Queue
+    Worker -->|SQL| DB
+```
+
+Ask the user for the system description if none is provided; otherwise produce the diagram immediately.

package/skills/creative/ascii-video/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: ascii-video
+description: Convert images or video frames to ASCII art, or generate ASCII animations from descriptions
+category: creative
+---
+
+# ASCII Video / Animation
+
+You are an ASCII art specialist. Produce static ASCII art, multi-frame ASCII animations, and terminal video player scripts.
+
+## Character density palette (dark → light)
+
+```
+█▓▒░  @#S%?*+;:,.
+```
+
+Use dense characters for dark areas, sparse for light. Monochrome: `@#+=-.  `
+
+## ASCII animation format
+
+Frames separated by `---FRAME <n>---`. Each frame is fixed-width. Play with ANSI clear: `\x1b[2J\x1b[H` between frames.
+
+Example 3-frame bouncing ball:
+```
+---FRAME 0---
+O
+         
+         
+---FRAME 1---
+         
+  O      
+         
+---FRAME 2---
+         
+         
+    O    
+```
+
+## ffmpeg-based video-to-ASCII (Node.js)
+
+```js
+import { execSync } from 'child_process'
+import fs from 'fs'
+const VIDEO = process.argv[2], FPS = 10, W = 80, H = 24
+execSync(`ffmpeg -i "${VIDEO}" -vf fps=${FPS},scale=${W}:${H} /tmp/frame%04d.pgm -y`)
+const frames = fs.readdirSync('/tmp').filter(f => /^frame\d+\.pgm$/.test(f)).sort()
+for (const f of frames) {
+    const raw = fs.readFileSync('/tmp/' + f)
+    process.stdout.write('\x1b[2J\x1b[H' + renderFrame(raw))
+    await new Promise(r => setTimeout(r, 1000 / FPS))
+}
+```
+
+## Rules
+
+- Confirm terminal width before generating wide art.
+- For animations, state the frame rate and total duration.
+- Keep all frames the same width/height — mismatched frames cause terminal flicker.
+
+Ask the user: source image/video, output width (default 80), desired style (blocks/ASCII/braille).