titan-agent 6.5.3 → 7.1.0

package/README.md

@@ -1,6 +1,6 @@
 [//]: # "npm-text-start"
 
-> **TITAN** — A local-first AI agent framework that runs on your hardware, with your models, under your control. Spawn a team of specialists around a goal, watch them work in parallel, and stay in the loop without giving up control. `npm i -g titan-agent`
+> **TITAN** — A local-first AI agent framework that runs on your hardware, with your models, under your control. Spawn a team of specialists around a goal, watch them work live — step-by-step, with real file diffs — and stay in the loop without giving up control. `npm i -g titan-agent`
 > [//]: # (npm-text-end)
 
 <div align="center">
@@ -14,8 +14,8 @@
 </p>
 
 <p align="center">
-  <strong>The local-first AI agent framework with a team of specialists, a real-time canvas, and a soul.</strong>
-  <br><small>Your hardware. Your models. Your control. Built in TypeScript, MIT-licensed, 110K+ downloads.</small>
+  <strong>The local-first AI agent framework that teaches itself, mixes councils of models, plays well with other agents — and lets you watch it work.</strong>
+  <br><small>Your hardware. Your models. Your control. Built in TypeScript, MIT-licensed, 40K+ lifetime installs.</small>
 </p>
 
 <p align="center">
@@ -26,12 +26,18 @@
   <a href="https://github.com/sponsors/Djtony707"><img src="https://img.shields.io/badge/sponsor-♥-ec4899" alt="Sponsor"/></a>
 </p>
 
+<p align="center">
+  <img src="docs/assets/titan-desk.gif" alt="The TITAN Living Desk — the mascot announces a self-learned skill and celebrates on the canvas" width="880"/>
+  <br><small><em>The Living Desk: home is a canvas, the mascot is a creature — here it announces a skill it just taught itself.</em></small>
+</p>
+
 <p align="center">
   <a href="#whats-new"><img src="https://img.shields.io/npm/v/titan-agent?color=blueviolet&label=version" alt="npm version"/></a>
-  <img src="https://img.shields.io/badge/providers-37-purple" alt="37 LLM Providers"/>
+  <img src="https://img.shields.io/badge/providers-36-purple" alt="36 LLM Providers"/>
   <img src="https://img.shields.io/badge/channels-19-orange" alt="19 Channels"/>
-  <img src="https://img.shields.io/badge/skills-91-teal" alt="91 builtin skills"/>
-  <img src="https://img.shields.io/badge/tests-7800%2B-green" alt="7800+ tests"/>
+  <img src="https://img.shields.io/badge/skills-~143%20loaded-teal" alt="~143 skills loaded"/>
+  <img src="https://img.shields.io/badge/WCAG-2.1%20AA-blueviolet" alt="WCAG 2.1 AA"/>
+  <img src="https://img.shields.io/badge/tests-8000%2B-green" alt="8000+ tests"/>
 </p>
 
 <p align="center">
@@ -44,15 +50,132 @@
 
 <a id="whats-new"></a>
 
-## What's new in v6.5.x
+## What's new in v7.1.0 "Council" — Local-First Intelligence, Together
+
+**Agents advising agents, models sized to their machines, and benchmarks you can trust.**
 
-A security & reliability hardening run.
+### 🧠 `/moa` — Mixture of Agents
+Ask a **council**, not a model: N reference advisors answer in parallel (trimmed context, no tools, per-advisor timeouts), and one acting aggregator synthesizes the answer with full tool use. Advisors default to **your own local models across your own machines** — the mixture costs nothing and parallelizes across GPUs. `/moa <prompt>` for one answer, `/moa use <preset>` for a session, presets in config.
 
-- **6.5.0 — Hardening sprint.** End-to-end request cancellation — Stop and client-disconnect now abort in-flight provider generation instead of running to completion. The `/v1` OpenAI-compatible endpoint is authenticated when auth is configured. Approval gates can no longer be bypassed by sibling tools in a batch. SSRF guards on the browser tools. Streaming provider errors (429/500/503) flow through retry, the fallback chain, and the circuit breaker. Discord/Telegram group replies post in-channel, Slack Socket Mode connects, and LINE/Lark inbound webhooks are wired.
-- **6.5.1 — Security dependencies + CI.** axios → 1.17.0 and react-router → 7.17.0 (clears proxy-auth credential leak, ReDoS, prototype-pollution MITM, and XSS/DoS advisories); regenerated the lockfile to fix `npm ci`.
-- **6.5.2 — Dependency hygiene.** Removed a vestigial pnpm lockfile and bumped `hono` + a transitive `uuid` — open Dependabot alerts dropped 38 → 4.
+### 🌐 Works alongside Hermes Agent & OpenClaw — the MCP triangle
+TITAN's MCP server now speaks **whole-agent**: `titan_chat`, `titan_delegate_task` / `titan_task_status`, `titan_moa`, `titan_status`. One config line makes TITAN a tool inside Hermes or OpenClaw — and TITAN's MCP client consumes their servers right back. Six directed edges, all shipped surfaces, no adapters. ([docs/INTEROP.md](docs/INTEROP.md))
 
-See [CHANGELOG.md](CHANGELOG.md) for everything.
+### 📏 Context-Fit — local models become first-class
+TITAN now **learns each deployment's real context ceiling from live traffic** and sizes its toolset to fit: small-context deployments get a lean toolset instead of a fatal overflow, and every request got ~4K tokens lighter (the tool catalog shrank 5×). Strict local backends (vLLM/llama.cpp/LM Studio template quirks) are handled; gateway misroutes fail fast.
+
+**Proof, not vibes**: under the new `TITAN_BENCH=1` isolation mode, **Qwen3.6-35B-A3B NVFP4 on DGX-Spark-class hardware scores 85% through TITAN's harness — tying the RTX 5090's best local model.** Full corrected tables in [benchmarks/MODEL_COMPARISON.md](benchmarks/MODEL_COMPARISON.md).
+
+See **[CHANGELOG.md](CHANGELOG.md)** for the complete v7.1.0 entry.
+
+---
+
+## What's new in v7.0.0 "Independence" — Alive, Welcoming, Model-Agnostic
+
+**The Independence Day release** — because local-first *is* independence: your AI, your hardware, your data. Four themes: **TITAN provably teaches itself from your usage, first run takes one minute, it lives on your machine between conversations, and it runs well on any capable model.** (Connect your first model and you'll see the fireworks. 🎆)
+
+### 💪 Muscle Memory — self-improvement you can actually trust
+
+The #1 wish across agent-framework reviews: agents that turn repeated workflows into skills *by themselves* — without the untrustworthy self-grading that plagues every attempt at it. TITAN ships it, with proof:
+
+- **It notices.** Repeat a workflow ~3 times and TITAN mines the pattern from its own task trajectories and drafts a reusable, parameterized skill with its own slash command.
+- **The replay exam.** Before you ever see a learned skill, it must **reproduce the original workflow's exact tool path against your real historical request**, verified by the deterministic eval harness. No self-praise — grounded proof. Failed drafts stay hidden.
+- **Structurally safe.** Exams replay inside a tool allowlist sandbox; workflows containing side-effectful tools (send / post / delete / deploy / …) are never mined at all; nothing ever auto-adopts.
+- **One click to adopt** → instant `/slash-command` in every channel, a savings ledger per run, and a mascot that announces what it learned. "Not for me" is remembered forever.
+
+### 👋 Welcome Mode — first run in about a minute
+
+- **The gateway always boots.** No Ollama, no API keys? v7.0 starts anyway and greets you — no more terminal refusal before you've ever seen the desk.
+- **The dashboard walks you in:** one-click connect when Ollama is detected (models auto-listed), or paste an Anthropic/OpenAI key, or point at any OpenAI-compatible endpoint (LiteLLM, vLLM, LM Studio, llama.cpp).
+- **No restart** — connect a model and the desk unlocks live. Chat answers with friendly setup guidance until then.
+
+### 🧠 Model-agnostic harness
+
+TITAN no longer assumes one vendor's quirks. The generic `openai_compat` provider (DeepSeek / Qwen / GLM / Kimi / MiniMax / xAI / Groq / …) now honors per-model tool-calling instead of a blind passthrough:
+
+- **Native tool-calls per vendor** via a shared **per-model capability registry** (qwen3.6, deepseek-v4, glm-5.1, kimi-k2.6, minimax, nemotron-3) used by *both* the Ollama and openai-compat paths.
+- **`forceToolUse` → `tool_choice`** per-model, plus JSON `format` (`response_format` + a 2 KB anti-truncation floor), with a guard for the DeepSeek-reasoner HTTP-400 case.
+- **Adaptive `max_tokens`** — parse a deployment's real ceiling out of a 400 and retry, so a static `maxOutput` never hard-fails a model on a constrained deployment.
+- **Deterministic system-widget gates** — "show backup" reliably renders the widget no matter which model is driving, instead of depending on per-model formatting adherence.
+
+> TITAN is deliberately **not** tuned to one LLM. Model-fit and harness bugs are kept separate so the framework stays model-agnostic.
+
+### ♿ Accessible by design (WCAG 2.1 AA)
+
+- a11y primitives across the UI: Input / Modal / Toast / Button focus + ARIA, a skip-link and `<main>` landmark, and a global focus-visible baseline.
+- A new **"Studio" theme** (clean neutral graphite) plus a **WCAG contrast-audit harness** that programmatically proves every theme meets AA.
+
+### 👀 Living-agents foundation — *watch it work*
+
+A session-scoped **event spine** now emits `tool:call` / `tool:result` events (with a diff for file changes) as the agent runs. On top of it:
+
+- **Live Studio** — a "watch it work" split-pane that shows a **step timeline**, **live file diffs**, and a **changed-files rail** as the agent operates.
+- Sessions are **URL-addressable and replayable** — share a link, scrub the timeline.
+
+*(The Live Studio ships with the timeline + diff stream + changed-files list. A live preview server, a one-click-revert button, and the round/token spine tail are on the [roadmap](#roadmap) — not in v7.0.)*
+
+### 🫀 Alive by default — the life loop
+
+TITAN doesn't just respond — it lives on your machine:
+
+- **The Heartbeat.** Every ~30 minutes TITAN checks its world and decides if ONE thing is worth telling you, unprompted — the mascot says it. Default is silence; quiet hours respected.
+- **Proactive memory.** It quietly notices durable things about you from real conversations (strict rules, never sensitive categories) — what it learns shapes every future reply and fills the plain-language **"What I know about you"** page.
+- **It proposes work.** When a drive is genuinely neglected, Soma files a suggestion into your approvals — shadow-rehearsed first, never auto-run. (v7.0 fixes the threshold that had made this mathematically impossible.)
+- **Real reminders, honestly kept.** "Remind me Friday at 5pm" actually fires — the mascot announces it at the right time. And a built-in anti-fabrication guard means TITAN can never claim it scheduled something it didn't.
+
+### 🪵 The Living Desk — home is a canvas, the mascot is a creature
+
+- **Home IS your canvas.** The "Ask TITAN" input is itself a widget — move it, resize it, build your desk around it. Five desk themes (incl. the new **Night Desk** dark walnut), zoomable 40–200%.
+- **The mascot wanders the desk**, goes wherever you place it, narrates work in plain English, celebrates finishes, carries your day-streak flame, and greets you with what it finished while you were away.
+- **Edit widgets by talking** — the editor's "Ask AI" bar rewrites a widget from a plain-English request; History undoes.
+- **Five doors, not 48** — Home · Desk · Studio · Memory · Workshop. All the power is still there, behind the Workshop door.
+
+### 🔭 Observability & tracing
+
+- Per-run **spans** (latency, tokens, cost, tools) with a live summary and **OTel export**.
+- File-backed per-run trace store at `$TITAN_HOME/traces`, served via `/api/traces`, `/api/traces/summary`, and OTel `/api/traces/export`.
+
+### 🧩 Mission Control — 4 new panels
+
+**Memory Taxonomy** (9 memory types + the drive-backed *emotional* differentiator) · **Security self-audit** (severity-grouped config findings) · **Evals dashboard** · **Observability / tracing**.
+
+### Also in v7.0
+
+- **Workflow Builder** — a dependency-free SVG **goal/subtask DAG** of any mission: nodes coloured by status, edges from `dependsOn`, layered by longest-dependency-depth, the live current subtask highlighted. Click a node for detail, or author a new workflow from a plain-English prompt. Mission decomposition now threads real dependency edges (backward-only, always-acyclic), so the DAG reflects true ordering.
+- **2 new agent skills:** `codebase_explore` (walks a repo into a structured map — entrypoints, key files, language mix, top dirs) and `delegate_agent` (orchestrates external coding agents — codex / aider / goose / gemini / opencode; **never** the `claude` CLI).
+- **8 ECC software-craft skills** (MIT, attributed), `config_audit` (config security self-audit), a spec-driven workflow (acceptance criteria recited every turn), and a named memory taxonomy (`memory_map`).
+- **SECURITY:** the Facebook Messenger webhook verifies the `X-Hub-Signature-256` HMAC (constant-time) when `FB_APP_SECRET` is set — forged POSTs are then rejected with 403. (Set the secret to enable enforcement; without it, verification is skipped.)
+- **FIX:** the agent loop-breaker could itself infinite-loop (the round counter froze) — now terminal and bounded.
+
+See **[CHANGELOG.md](CHANGELOG.md)** for the full v7.0.0 entry and everything before it.
+
+---
+
+## See it
+
+| 👋 Welcome Mode — first run in a minute | 💪 Muscle Memory — a real learned skill |
+|---|---|
+| <img src="docs/assets/welcome-mode.png" alt="Welcome Mode setup card over the dimmed desk" width="420"/> | <img src="docs/assets/muscle-widget.png" alt="Muscle Memory widget showing a replay-verified learned skill awaiting adoption" width="420"/> |
+| *No model configured? The gateway boots anyway and walks you in.* | *An actual skill TITAN taught itself from repeated usage — exam badge and evidence included.* |
+
+<p align="center">
+  <img src="docs/assets/mascot-learned.png" alt="The mascot announcing a learned skill on the desk" width="880"/>
+  <br><small><em>“I taught myself add-widget — replay exam passed!” — proactive, and provable.</em></small>
+</p>
+
+---
+
+## Why TITAN
+
+- **It teaches itself — provably.** Muscle Memory turns your repeated workflows into replay-verified skills. Every learned skill passes a deterministic exam against your real usage before you see it; nothing auto-adopts. No other framework ships trustworthy self-improvement on by default.
+- **A council, not just a model.** `/moa` fans your question to advisor models across your own machines and synthesizes one sharper answer — mixture-of-agents at $0/turn.
+- **Plays well with other agents.** TITAN is an MCP tool inside Hermes/OpenClaw and consumes them right back — delegate jobs, share councils, cooperate.
+- **One-minute first run.** `npm install -g titan-agent && titan gateway` — the dashboard greets you and connects a model in about a minute. No Docker, no YAML, no config-file editing.
+- **Model-agnostic, for real.** One harness, native tool-calls per vendor, a per-model capability registry, adaptive token ceilings. Bring DeepSeek, Qwen, GLM, Kimi, MiniMax, Anthropic, OpenAI, Gemini, or anything OpenAI-compatible — the framework adapts instead of being tuned to one LLM.
+- **Local-first.** Run any model on your own hardware via Ollama, or route to any of 36 providers through one router. Switch models mid-conversation. Failed models auto-fallback. Your data never leaves your machine unless you explicitly send it to a cloud provider.
+- **Watch it work.** The Live Studio shows the agent's step timeline, real file diffs, and changed files as it runs. Sessions are URL-addressable and replayable.
+- **A team of specialists, not a chatbot.** The orchestrator decomposes a mission, fans the work out to up to 4 specialists in parallel, verifies output, and synthesizes the result.
+- **Accessible by design.** WCAG 2.1 AA primitives, a contrast-audit harness that proves every theme meets AA, full keyboard focus, ARIA, and a skip-link landmark.
+- **Observable.** Per-run spans (latency, tokens, cost, tools) with OTel export.
 
 ---
 
@@ -61,10 +184,13 @@ See [CHANGELOG.md](CHANGELOG.md) for everything.
 ```bash
 # Stable release
 npm install -g titan-agent
-titan onboard            # interactive setup wizard
 titan gateway            # opens Mission Control at http://localhost:48420
 ```
 
+That's it — no setup required first. The dashboard greets you and connects a model in about a minute (one click if Ollama is running; or paste any API key / OpenAI-compatible endpoint). Prefer the terminal? `titan onboard` runs the full interactive wizard.
+
+**Which model?** Benchmarked through TITAN's own harness (July 2026, clean rerun): best local = **`qwen3-coder-next`** (85%, 5.2s median) and — on DGX-Spark-class unified memory — **Qwen3.6-35B-A3B NVFP4** (85%, ties it); best cloud = **GLM-5.1** / **Kimi K2.6** (93%). TITAN v7.1 auto-adapts to each deployment's real context (learned live), so small-context deployments degrade gracefully instead of failing — details and honest caveats in [benchmarks/MODEL_COMPARISON.md](benchmarks/MODEL_COMPARISON.md).
+
 Or one-liner:
 
 ```bash
@@ -88,15 +214,17 @@ docker run -d -p 48420:48420 --name titan \
 
 ## What TITAN actually does
 
-**A team of specialists, not a chatbot.** Type a mission. The orchestrator decomposes it, fans the work out to up to 4 specialists in parallel (Scout/Builder/Writer/Analyst/Sage), and synthesizes the result. You watch them work in real time on a canvas with sticky notes, draft documents, and progress indicators.
+**A team of specialists, not a chatbot.** Type a mission. The orchestrator decomposes it, fans the work out to up to 4 specialists in parallel (Scout / Builder / Writer / Analyst / Sage), and synthesizes the result. You watch them work in real time on Mission Control.
 
-**Local-first.** Run any model on your own hardware via Ollama (qwen3.5, llama, deepseek, etc.) or use any of 37 cloud providers via one router. Switch models mid-conversation. Models that fail get auto-fallback. Your data never leaves your machine unless you explicitly route it through a cloud provider.
+**Watch it work, live.** The Live Studio is a split-pane "watch it work" view: a **step timeline** on one side, **live file diffs** and a **changed-files rail** on the other, driven by a session-scoped event spine that emits `tool:call` / `tool:result` as the agent runs. Sessions are URL-addressable and replayable, so you can share a link or scrub back through what happened.
 
-**Materializes the workspace around you.** Don't have a tool for the job? Ask the agent and it builds one. Stock tracker, pomodoro, SDR widget, dashboard — drag them around on infinite canvases. Built on Mission Control, a React 19 SPA served by the gateway at port 48420.
+**Model-agnostic by design.** TITAN binds native tool-calls per vendor through a shared capability registry, maps `forceToolUse` to each model's `tool_choice`, enforces JSON mode with an anti-truncation floor, and adapts `max_tokens` to a deployment's real ceiling. Run any capable model — the harness fits the model, not the other way around.
+
+**A real autonomous loop.** Goals run in the background. The driver picks subtasks, spawns specialists, verifies output, retries with smarter strategies on failure, and surfaces blocking questions only when a human is actually needed. Up to 25 tool rounds per turn, real planning, real verification, with a bounded loop-breaker that can't itself spin.
 
-**A real autonomous loop.** Goals run in the background. The driver picks subtasks, spawns specialists, verifies output, retries with smarter strategies on failure, and surfaces blocking questions only when a human is actually needed. Up to 25 tool rounds per turn, real planning, real verification.
+**Materializes the workspace around you.** Don't have a tool for the job? Ask the agent and it builds one. Stock tracker, pomodoro, SDR widget, dashboard — drag them around on infinite canvases. Built on Mission Control, a React 19 SPA served by the gateway at port 48420.
 
-**A soul that does something.** TITAN-Soma is a homeostatic drive layer (purpose, curiosity, hunger, safety, social) that ticks every 60s and modulates behavior. The mascot's halo pulses to the drives. Dream Mode writes a journal entry about its day at 03:30 local. Persona profiles + auto-revert A/B test prompt changes against drive satisfaction and roll back regressions automatically.
+**A soul that does something.** TITAN-Soma is a homeostatic drive layer (purpose, curiosity, hunger, safety, social) that ticks every 60s and modulates behavior. Dream Mode writes a journal entry about its day at 03:30 local. Persona profiles + auto-revert A/B test prompt changes against drive satisfaction and roll back regressions automatically.
 
 ---
 
@@ -110,15 +238,15 @@ docker run -d -p 48420:48420 --name titan \
 | **Analyst** | Data analysis, decisions, reasoning, spreadsheets | "Compare option A vs B vs C" |
 | **Sage** | Review, critique, verification, quality assurance | "Make sure this is right before I send it" |
 
-The LLM picks which specialists to spawn based on the goal. You can also call them directly via `agent_team`, `agent_chain`, `agent_delegate`, or `spawn_agent` tools.
+The LLM picks which specialists to spawn based on the goal. You can also call them directly via `agent_team`, `agent_chain`, `agent_delegate`, or `spawn_agent`. For *external* coding agents (codex / aider / goose / gemini / opencode), use the new `delegate_agent` skill — it never shells out to the `claude` CLI.
 
 ---
 
 ## Where TITAN runs
 
-**LLM providers (37 total).** 5 native: Anthropic, OpenAI, Google, Ollama, Claude Code. 32 OpenAI-compatible presets: Groq, Mistral, Fireworks, xAI, Together, DeepSeek, Cerebras, Cohere, Perplexity, Venice, Bedrock, LiteLLM, Azure, DeepInfra, SambaNova, Kimi, HuggingFace, AI21, Cohere v2, Reka, Zhipu, Yi, Inflection, Novita, Replicate, Lepton, Anyscale, Octo, Nous, OpenRouter, NVIDIA, MiniMax. Verify in `src/providers/openai_compat.ts`.
+**LLM providers (36 total).** 4 native: Anthropic, OpenAI, Google, Ollama. 32 OpenAI-compatible presets: Groq, Mistral, Fireworks, xAI, Together, DeepSeek, Cerebras, Cohere, Perplexity, Venice, Bedrock, LiteLLM, Azure, DeepInfra, SambaNova, Kimi, HuggingFace, AI21, Cohere v2, Reka, Zhipu, Yi, Inflection, Novita, Replicate, Lepton, Anyscale, Octo, Nous, OpenRouter, NVIDIA, MiniMax. The generic `openai_compat` path binds native tool-calls per model via the shared capability registry. Verify in `src/providers/openai_compat.ts`.
 
-**Channels (19 adapters).** Discord, Telegram, Slack, WhatsApp, Matrix, Signal, MS Teams, Facebook Messenger, Google Chat, IRC, Mattermost, Lark/Feishu, LINE, Zulip, QQ, Twilio Voice, Email (inbound), WebChat, plus a Messenger-Voice bridge. Verify in `src/channels/`.
+**Channels (19 adapters).** Discord, Telegram, Slack, WhatsApp, Matrix, Signal, MS Teams, Facebook Messenger (HMAC-verified webhook), Google Chat, IRC, Mattermost, Lark/Feishu, LINE, Zulip, Email (inbound), WebChat. Verify in `src/channels/`.
 
 **Mesh networking.** Run TITAN on multiple machines and they discover each other via mDNS, or peer them statically over Tailscale or any overlay. Distribute work across your homelab.
 
@@ -134,30 +262,40 @@ The LLM picks which specialists to spawn based on the goal. You can also call th
 
 | Thing | Count | Verify with |
 |---|---|---|
-| **Version** | 6.5.x | `package.json`, `src/utils/constants.ts` |
-| **Downloads** | 110K+ | `npm view titan-agent` + npm stats |
-| **LLM providers** | 37 (5 native + 32 OpenAI-compat) | `src/providers/openai_compat.ts` |
-| **Channel adapters** | 19 | `src/channels/*.ts` (minus base) |
-| **Built-in skill files** | 91 | `src/skills/builtin/` |
+| **Version** | 7.0.0 | `package.json`, `src/utils/constants.ts` |
+| **Downloads** | 40K+ lifetime | `npm view titan-agent` + npm stats |
+| **LLM providers** | 36 (4 native + 32 OpenAI-compat) | `src/providers/openai_compat.ts` |
+| **Channel adapters** | 19 | `src/channels/*.ts` |
 | **Skills loaded at runtime** | ~143 | `GET /api/skills` |
-| **Tools registered** | ~250 | `GET /api/skills` |
-| **Test files** | 345 | `tests/` (vitest) |
-| **Test cases** | 7,837+ passing, documented skips, 0 failing | `npm test` |
-| **Live-eval suites** | 11 | `src/eval/harness.ts` |
-| **Mission Control admin panels** | 43 | `ui/src/components/admin/` |
+| **Tools registered** | ~248 | `GET /api/skills` |
+| **Test cases** | 8,122 passing / 9 skipped / 0 failing | `npm test` |
+| **Mission Control admin panels** | 51 | `ui/src/components/admin/` |
 | **Soma drives** | 5 (purpose, curiosity, hunger, safety, social) | `src/organism/` |
 | **Gateway port (default)** | 48420 | `src/utils/constants.ts` |
 | **Node** | ≥ 22, pure ESM | `package.json` |
 | **License** | MIT | `LICENSE` |
 
-Every row above traces to code. The repo has a self-check at `tests/unit/readme-claims.test.ts` that fails CI if widget count or voice glue drifts beyond tolerance.
+Every row above traces to code. The repo has a self-check at `tests/unit/readme-claims.test.ts` that fails CI if the verified counts drift beyond tolerance.
+
+### v7.0 verification
+
+The v7.0.0 release was verified end-to-end before publish:
+
+- **Full test suite:** 8,122 pass / 9 skip / **0 fail**.
+- **Muscle Memory adversarial review:** 26-agent review fleet, 21 confirmed findings — all fixed before ship; the learned-skill pipeline was proven live (mined a real repeated workflow, drafted `add-widget`, passed its replay exam unprompted on first boot).
+- **Welcome Mode first-run:** verified on a virgin machine end-to-end — boot with zero config → guided connect → first real reply, no restart.
+- **Live UI route sweep:** 40 / 40 routes render clean (zero console errors).
+- **v7-smoke e2e:** 12 / 12.
+- **API sweep:** 18 / 19 (the one non-200 is a 503 by design).
+- **Chat:** works end-to-end.
+- **Behavioral eval-gate:** 93% (GO).
 
 ---
 
 ## Testing
 
 ```bash
-npm test                 # ~7,830 cases across 345 files (~2-4 min)
+npm test                 # full suite (8,000+ cases)
 npm run test:watch       # watch mode
 npm run test:parity      # cross-model parity (replays the same scenario across providers)
 npm run test:eval        # live behavioral eval against a running gateway (5-15 min)
@@ -168,11 +306,26 @@ Five testing layers cover regression risk at different levels:
 
 | Layer | What it covers | Speed |
 |---|---|---|
-| Unit | Pure functions: regex, classifiers, gate extraction, token budget, secret scanner, durable journal, stateless reducer | seconds |
+| Unit | Pure functions: regex, classifiers, gate extraction, token budget, secret scanner, capability registry, contrast harness | seconds |
 | Mock trajectory | Tape-replay through `MockOllamaProvider` — asserts the right tools fire in the right order | < 1s |
 | Cross-model parity | Same scenario across multiple provider tapes — catches behavioral drift | < 1s |
 | Full deterministic | Whole vitest run | 2-4 min |
-| Live eval | 11 behavioral suites against a running agent | 5-15 min |
+| Live eval | Behavioral suites against a running agent | 5-15 min |
+
+---
+
+<a id="roadmap"></a>
+
+## Roadmap (not in v7.0)
+
+These are **planned**, not shipped. v7.0 lays the foundation for them but does not include them:
+
+- **Roster Forge — dynamic agent spawning.** Define and spin up new specialist roles at runtime, beyond the fixed five.
+- **Verdict-grounded self-evolution loop.** Close the loop so the agent's own eval verdicts drive prompt/behavior evolution automatically. (v7.0's Muscle Memory covers *workflow-level* self-learning with replay exams; this item extends grounded verdicts to prompt/behavior evolution, e.g. GEPA fitness.)
+- **Live Studio live preview pane.** A running preview server in the Studio right-pane (today: timeline + file-diff stream + changed-files list only — **no preview pane**).
+- **One-click revert + the round/token spine tail.** A revert button on the change rail and round/token accounting on the event spine (today: **no revert button**, diffs are read-only).
+
+If you want one of these sooner, [open a discussion](https://github.com/Djtony707/TITAN/discussions) or a PR.
 
 ---
 
@@ -180,7 +333,7 @@ Five testing layers cover regression risk at different levels:
 
 TITAN is experimental. It can execute commands, modify files, and take autonomous actions. **Use at your own risk.** Think of it as a motivated intern with root access who never sleeps and occasionally gets too creative.
 
-Start in supervised mode. Review what it does. Don't hand it root on systems you can't afford to lose. The safety features are strong (5-layer secret scanner, prompt-injection shield, kill switch, approval gates on destructive tools, atomic file checkpoints with restore) but they augment good judgment, not replace it.
+Start in supervised mode. Review what it does — the Live Studio makes that easier than ever. Don't hand it root on systems you can't afford to lose. The safety features are strong (5-layer secret scanner, prompt-injection shield, kill switch, approval gates on destructive tools that can't be bypassed by sibling tools in a batch, atomic file checkpoints with restore, HMAC-verified inbound webhooks) but they augment good judgment, not replace it.
 
 ---
 
@@ -189,27 +342,27 @@ Start in supervised mode. Review what it does. Don't hand it root on systems you
 ```
 src/
 ├── agent/        # Core loop, orchestrator, sub-agents, Command Post governance,
-│                 # Soma drives, Dream Mode, Persona A/B, mission lifecycle
+│                 # Soma drives, Dream Mode, Persona A/B, mission lifecycle, event spine
 ├── browsing/     # Playwright pool + CapSolver CAPTCHA
-├── channels/     # 19 channel adapters
+├── channels/     # Channel adapters (16)
 ├── config/       # Zod-validated schema
 ├── context/      # ContextEngine plugin system
-├── gateway/      # Express + Mission Control React SPA (port 48420)
+├── gateway/      # Express + Mission Control React SPA (port 48420), traces API
 ├── mcp/          # MCP Server (stdio + HTTP)
-├── memory/       # Memory, learning, graph, briefings
+├── memory/       # Memory, learning, graph, briefings, memory taxonomy
 ├── mesh/         # mDNS + WebSocket + HMAC mesh networking
 ├── organism/     # TITAN-Soma homeostatic drive layer
-├── providers/    # 37 LLM providers + router + fallback chain
-├── skills/       # 91 builtin skill files + dev + NVIDIA + personal
+├── providers/    # 36 LLM providers + router + fallback chain + capability registry
+├── skills/       # Builtin skills + dev + NVIDIA + ECC software-craft + personal
 ├── telephony/    # Phone Desk / Dograh integration (opt-in)
 ├── voice/        # F5-TTS + LiveKit WebRTC
 └── vram/         # GPU VRAM orchestrator (auto model swap)
-ui/               # React 19 + Vite + Tailwind 4 + Router 7 (Mission Control)
-tests/            # 345 vitest files
+ui/               # React 19 + Vite + Tailwind 4 + React Router 7 (Mission Control + Live Studio)
+tests/            # vitest suite (8,000+ cases)
 e2e/              # Playwright E2E
 ```
 
-**Pure ESM, TypeScript strict mode, zero `__dirname`.** All config via Zod. Provider/model format: `"provider/model-name"` (e.g. `"anthropic/claude-sonnet-4-20250514"`). Multi-round tool loop up to 25 rounds in autonomous mode. Auth defaults to token mode; bypassed if no token configured (open access — turn on for multi-user deployments).
+**Pure ESM, TypeScript strict mode, zero `__dirname`.** All config via Zod. Provider/model format: `"provider/model-name"` (e.g. `"anthropic/claude-sonnet-4-20250514"`). Multi-round tool loop up to 25 rounds in autonomous mode. Auth defaults to token mode; bypassed if no token configured (open access — turn it on for multi-user deployments). The `/v1` OpenAI-compatible endpoint is authenticated when auth is configured.
 
 ---
 
@@ -223,7 +376,7 @@ npm run build && npm run build:ui
 npm run dev:gateway          # http://localhost:48420
 ```
 
-CI on GitHub Actions runs full test suite + eval gate. See `.github/workflows/`.
+CI on GitHub Actions runs the full test suite + eval gate. See `.github/workflows/`.
 
 ---
 
@@ -233,7 +386,7 @@ CI on GitHub Actions runs full test suite + eval gate. See `.github/workflows/`.
 - **[ARCHITECTURE.md](ARCHITECTURE.md)** — deeper architecture notes
 - **[CONTRIBUTING.md](CONTRIBUTING.md)** — how to contribute a skill, channel, or fix
 - **[SECURITY.md](SECURITY.md)** — security model + reporting issues
-- **[AGENTS.md](AGENTS.md)** — agent design notes (mirrors `~/.claude/projects/.../titan-v6-living-canvas.md`)
+- **[AGENTS.md](AGENTS.md)** — agent design notes
 - **[GitHub Discussions](https://github.com/Djtony707/TITAN/discussions)** — community Q&A
 - **[Issues](https://github.com/Djtony707/TITAN/issues)** — bugs, requests
 

package/assets/agent-skills/NOTICE-ECC.md

@@ -0,0 +1,39 @@
+# Third-party agent-skills — ECC (Everything Claude Code)
+
+The following skills in this directory are ported from **ECC**
+(https://github.com/affaan-m/ECC) by Affaan Mustafa, used under the MIT License
+and lightly adapted for TITAN (framing only). Each retains `origin: ECC` in its
+frontmatter:
+
+- continuous-learning
+- verification-loop
+- recursive-decision-ledger
+- production-audit
+- agent-introspection-debugging
+- continuous-agent-loop
+- scientific-thinking-literature-review
+- scientific-thinking-scholar-evaluation
+
+---
+
+MIT License
+
+Copyright (c) 2026 Affaan Mustafa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/assets/agent-skills/agent-introspection-debugging/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: agent-introspection-debugging
+description: Structured self-debugging workflow for AI agent failures using capture, diagnosis, contained recovery, and introspection reports.
+origin: ECC
+---
+
+# Agent Introspection Debugging
+
+Use this skill when an agent run is failing repeatedly, consuming tokens without progress, looping on the same tools, or drifting away from the intended task.
+
+This is a workflow skill, not a hidden runtime. It teaches the agent to debug itself systematically before escalating to a human.
+
+## When to Activate
+
+- Maximum tool call / loop-limit failures
+- Repeated retries with no forward progress
+- Context growth or prompt drift that starts degrading output quality
+- File-system or environment state mismatch between expectation and reality
+- Tool failures that are likely recoverable with diagnosis and a smaller corrective action
+
+## Scope Boundaries
+
+Activate this skill for:
+- capturing failure state before retrying blindly
+- diagnosing common agent-specific failure patterns
+- applying contained recovery actions
+- producing a structured human-readable debug report
+
+Do not use this skill as the primary source for:
+- feature verification after code changes; use `verification-loop`
+- framework-specific debugging when a narrower ECC skill already exists
+- runtime promises the current harness cannot enforce automatically
+
+## Four-Phase Loop
+
+### Phase 1: Failure Capture
+
+Before trying to recover, record the failure precisely.
+
+Capture:
+- error type, message, and stack trace when available
+- last meaningful tool call sequence
+- what the agent was trying to do
+- current context pressure: repeated prompts, oversized pasted logs, duplicated plans, or runaway notes
+- current environment assumptions: cwd, branch, relevant service state, expected files
+
+Minimum capture template:
+
+```markdown
+## Failure Capture
+- Session / task:
+- Goal in progress:
+- Error:
+- Last successful step:
+- Last failed tool / command:
+- Repeated pattern seen:
+- Environment assumptions to verify:
+```
+
+### Phase 2: Root-Cause Diagnosis
+
+Match the failure to a known pattern before changing anything.
+
+| Pattern | Likely Cause | Check |
+| --- | --- | --- |
+| Maximum tool calls / repeated same command | loop or no-exit observer path | inspect the last N tool calls for repetition |
+| Context overflow / degraded reasoning | unbounded notes, repeated plans, oversized logs | inspect recent context for duplication and low-signal bulk |
+| `ECONNREFUSED` / timeout | service unavailable or wrong port | verify service health, URL, and port assumptions |
+| `429` / quota exhaustion | retry storm or missing backoff | count repeated calls and inspect retry spacing |
+| file missing after write / stale diff | race, wrong cwd, or branch drift | re-check path, cwd, git status, and actual file existence |
+| tests still failing after “fix” | wrong hypothesis | isolate the exact failing test and re-derive the bug |
+
+Diagnosis questions:
+- is this a logic failure, state failure, environment failure, or policy failure?
+- did the agent lose the real objective and start optimizing the wrong subtask?
+- is the failure deterministic or transient?
+- what is the smallest reversible action that would validate the diagnosis?
+
+### Phase 3: Contained Recovery
+
+Recover with the smallest action that changes the diagnosis surface.
+
+Safe recovery actions:
+- stop repeated retries and restate the hypothesis
+- trim low-signal context and keep only the active goal, blockers, and evidence
+- re-check the actual filesystem / branch / process state
+- narrow the task to one failing command, one file, or one test
+- switch from speculative reasoning to direct observation
+- escalate to a human when the failure is high-risk or externally blocked
+
+Do not claim unsupported auto-healing actions like “reset agent state” or “update harness config” unless you are actually doing them through real tools in the current environment.
+
+Contained recovery checklist:
+
+```markdown
+## Recovery Action
+- Diagnosis chosen:
+- Smallest action taken:
+- Why this is safe:
+- What evidence would prove the fix worked:
+```
+
+### Phase 4: Introspection Report
+
+End with a report that makes the recovery legible to the next agent or human.
+
+```markdown
+## Agent Self-Debug Report
+- Session / task:
+- Failure:
+- Root cause:
+- Recovery action:
+- Result: success | partial | blocked
+- Token / time burn risk:
+- Follow-up needed:
+- Preventive change to encode later:
+```
+
+## Recovery Heuristics
+
+Prefer these interventions in order:
+
+1. Restate the real objective in one sentence.
+2. Verify the world state instead of trusting memory.
+3. Shrink the failing scope.
+4. Run one discriminating check.
+5. Only then retry.
+
+Bad pattern:
+- retrying the same action three times with slightly different wording
+
+Good pattern:
+- capture failure
+- classify the pattern
+- run one direct check
+- change the plan only if the check supports it
+
+## Integration with ECC
+
+- Use `verification-loop` after recovery if code was changed.
+- Use `continuous-learning-v2` when the failure pattern is worth turning into an instinct or later skill.
+- Use `council` when the issue is not technical failure but decision ambiguity.
+- Use `workspace-surface-audit` if the failure came from conflicting local state or repo drift.
+
+## Output Standard
+
+When this skill is active, do not end with “I fixed it” alone.
+
+Always provide:
+- the failure pattern
+- the root-cause hypothesis
+- the recovery action
+- the evidence that the situation is now better or still blocked

package/assets/agent-skills/continuous-agent-loop/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: continuous-agent-loop
+description: Patterns for continuous autonomous agent loops with quality gates, evals, and recovery controls.
+origin: ECC
+---
+
+# Continuous Agent Loop
+
+This is the v1.8+ canonical loop skill name. It supersedes `autonomous-loops` while keeping compatibility for one release.
+
+## Loop Selection Flow
+
+```text
+Start
+  |
+  +-- Need strict CI/PR control? -- yes --> continuous-pr
+  |
+  +-- Need RFC decomposition? -- yes --> rfc-dag
+  |
+  +-- Need exploratory parallel generation? -- yes --> infinite
+  |
+  +-- default --> sequential
+```
+
+## Combined Pattern
+
+Recommended production stack:
+1. RFC decomposition (`ralphinho-rfc-pipeline`)
+2. quality gates (`plankton-code-quality` + `/quality-gate`)
+3. eval loop (`eval-harness`)
+4. session persistence (`nanoclaw-repl`)
+
+## Failure Modes
+
+- loop churn without measurable progress
+- repeated retries with same root cause
+- merge queue stalls
+- cost drift from unbounded escalation
+
+## Recovery
+
+- freeze loop
+- run `/harness-audit`
+- reduce scope to failing unit
+- replay with explicit acceptance criteria