titan-agent 6.3.3 → 6.3.5

package/README.md

@@ -1,519 +1,256 @@
 [//]: # "npm-text-start"
 
-> **TITAN** — The AI that moves in. Start a mission, watch a small team of AI helpers gather around a real wood desk, drag their sticky notes around, and let them work for you 24/7. `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 in parallel, and stay in the loop without giving up control. `npm i -g titan-agent`
 > [//]: # (npm-text-end)
 
 <div align="center">
 
-# TITAN 6.0 — "Living Canvas" 🌌
+# TITAN
 
 </div>
 
 <p align="center">
-  <img src="assets/titan-logo.png" alt="TITAN Logo" width="280"/>
+  <img src="assets/titan-logo.png" alt="TITAN Logo" width="240"/>
 </p>
 
 <p align="center">
-  <strong>Every other AI gives you a chat box. TITAN moves in.</strong>
-  <br><small>Infinite workspaces. Tools built on demand. An AI that feels, learns, and helps before you ask.</small>
+  <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, ~40K npm installs.</small>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/titan-agent"><img src="https://img.shields.io/npm/v/titan-agent?color=blue&label=npm" alt="npm version"/></a>
-  <a href="https://www.npmjs.com/package/titan-agent"><img src="https://img.shields.io/npm/dw/titan-agent?label=npm%20downloads" alt="npm downloads"/></a>
+  <a href="https://www.npmjs.com/package/titan-agent"><img src="https://img.shields.io/badge/installs-40K%2B-blue" alt="npm installs"/></a>
   <a href="https://github.com/Djtony707/TITAN/stargazers"><img src="https://img.shields.io/github/stars/Djtony707/TITAN?style=social" alt="GitHub Stars"/></a>
   <a href="https://github.com/Djtony707/TITAN/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"/></a>
+  <a href="https://github.com/sponsors/Djtony707"><img src="https://img.shields.io/badge/sponsor-♥-ec4899" alt="Sponsor"/></a>
 </p>
 
 <p align="center">
-  <a href="#-the-numbers"><img src="https://img.shields.io/badge/version-6.2.1-blueviolet" alt="v6.2.1"/></a>
-  <a href="#-36-llm-providers"><img src="https://img.shields.io/badge/providers-36-purple" alt="36 Providers"/></a>
-  <a href="#-the-numbers"><img src="https://img.shields.io/badge/tools-248%2B-orange" alt="248+ Tools"/></a>
-  <a href="#-build-anything-on-demand"><img src="https://img.shields.io/badge/widgets-109-pink" alt="109 Widgets"/></a>
-  <a href="#-mission-control"><img src="https://img.shields.io/badge/admin%20panels-43-teal" alt="43 Admin Panels"/></a>
-  <a href="#-testing"><img src="https://img.shields.io/badge/tests-7%2C690%20passing-brightgreen" alt="7,690 Passing Tests"/></a>
+  <a href="#whats-new"><img src="https://img.shields.io/badge/version-6.3.5-blueviolet" alt="v6.3.5"/></a>
+  <img src="https://img.shields.io/badge/providers-37-purple" alt="37 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"/>
 </p>
 
 <p align="center">
-  <a href="https://github.com/sponsors/Djtony707"><img src="https://img.shields.io/badge/%E2%9D%A4%EF%B8%8F_Sponsor-ea4aaa?style=for-the-badge&logo=github" alt="Sponsor on GitHub"/></a>
+  ⭐ <a href="https://github.com/Djtony707/TITAN">Star us on GitHub</a> &nbsp;·&nbsp;
+  ♥ <a href="https://github.com/sponsors/Djtony707">Sponsor</a> &nbsp;·&nbsp;
+  💬 <a href="https://github.com/Djtony707/TITAN/discussions">Discussions</a>
 </p>
 
-<p align="center">
-  <em>Built by <a href="https://github.com/Djtony707">Tony Elliott</a> — a dad, a DJ, a builder, and a guy who ships code at 3am because sleep is a feature he hasn't shipped yet.</em>
-</p>
-
----
-
-## 🪵 NEW in v6.1 — Mission Chat + Desk view
-
-> Status: `v6.2.1` — TITAN Phone Desk safety hotfix: optional Dograh sidecar integration for Twilio/Telnyx voice workflows, approval-gated outbound calls, inbound admin/receptionist webhooks, opt-out enforcement, receipts, and a dashboard panel.
-> Install with `npm i -g titan-agent` (or `npm update -g titan-agent`).
-> The v6.0 "Presence" feature set below still applies — v6.1.0 layers
-> a beautiful new surface on top of it.
-
-## 📞 NEW in v6.2 — TITAN Phone Desk with Dograh
-
-TITAN can now connect to a self-hosted or hosted Dograh sidecar for Twilio/Telnyx-powered phone workflows without storing carrier credentials directly in TITAN. The integration is optional and disabled by default.
-
-What is verified in v6.2.1:
-
-- `GET /api/telephony/dograh/status` checks Dograh reachability and redacts the API key.
-- `GET /api/telephony/dograh/workflows` lists active Dograh workflows.
-- `POST /api/telephony/dograh/call` creates an approval request first, then starts an outbound Dograh call only when a matching approval action is supplied.
-- The `phone_call` tool is approval-request-only; it never dials directly from an LLM tool call.
-- `POST /api/telephony/dograh/inbound` handles inbound Dograh webhooks for admin-control and receptionist lines.
-- Admin control is restricted to configured E.164 `telephony.adminNumbers`.
-- Public/receptionist numbers do not receive admin privileges.
-- Campaign/cold-call mode is locked unless `allowCampaigns`, recording disclosure, opt-out keywords, and hourly rate limits are configured.
-- Inbound opt-out phrases are recorded and block future campaign calls to that number.
-- Phone numbers and Dograh API keys are redacted from responses, receipts, and UI lists.
-- `/tools/phone-desk` provides status, workflow, call-receipt, opt-out, and approval-request UI.
-
-Dograh is BSD-2-Clause. TITAN integrates with it as an external sidecar/API so the npm package stays lightweight and Dograh can own the Twilio/Telnyx credentials.
-
-Every TITAN canvas page now carries a **🪵 Mission Chat** launcher in
-the header (with a small **NEW** badge). Click it and you walk into a
-chat-style team-control surface — plus a literal **wood desk** view
-where everything the team produces lands as a physical, draggable object.
-
-### What you get
-
-- 💬 **Mission Chat** — type one goal. TITAN matches a starter Play,
-  forms a small team of AI helpers (Scout the researcher, Builder the
-  engineer, Writer, Analyst, Sage the reviewer), and they talk in a
-  thread with you as they work. Click any bubble for full timing /
-  cost / model / source details.
-
-- 🪵 **Mission Canvas — "Wood Desk" view** — same data, spatial layout.
-  - A warm caramel wood surface with grain, two knots, and window light
-    falling from the upper-left. CSS-only — no image assets.
-  - A leather **goal placard** carrying your mission text.
-  - A **paper sheet** in the center, real lined ledger paper, that fills
-    in as the team writes.
-  - **Agents as color-tinted sticky notes** — Scout's note is lavender,
-    Builder's is mint, Writer/Analyst yellow, blocked agents shift red.
-    Each has washi tape across the top and a cursive activity line.
-  - A **brass-rimmed desk clock** in the corner: big LCD numerals
-    showing your **local system time** (auto-detects timezone — `TITAN ·
-    PDT`), with a smaller "Mission · 00:04:14" elapsed line and live
-    counters for *working / needs you / on team*.
-  - **Files as paper documents** — every file an agent writes appears
-    on the desk. Double-click any file to open it in the in-app
-    **FileViewer** (markdown rendered with `react-markdown`, HTML in a
-    script-blocked sandbox iframe, images inline, PDFs native).
-    Reports default to **HTML with inline SVG charts** so they come
-    back looking like real documents, not flat text.
-  - **Sticky notes for AI-written facts** — every "fact" an agent
-    memorizes becomes a yellow Post-it on the desk.
-  - A **filing cabinet** (walnut, two drawers, brass label plates).
-    Drag any file or sticky onto it to file it; click to open the
-    drawer overlay; **drag rows out** to pull a file back to the desk.
-  - A **wicker wastebasket** with wadded-paper balls peeking over the
-    rim. Drop notes you don't want; pull them back from the cabinet
-    if you change your mind.
-  - **Drag anything anywhere.** Positions persist per-mission in
-    localStorage. **Tidy up** button resets the layout.
-
-- 👤 **Click any agent → AgentMenu** (six tiles):
-  - **👋 Nudge** — sends them a quick check-in
-  - **💬 Talk** — DM them with @-prefix routing
-  - **🧭 Steer** — redirect mid-task with quick presets
-  - **🧠 Model** — pick a specific model from `/api/models`
-  - **⏸ Pause / Resume** — skip them on the next round
-  - **🏃 Marathon mode** — mission-wide 72h autonomous toggle
-    *(the long-running daemon that consumes this flag is on the v6.1.0
-    roadmap; the UI flag is present, enforcement daemon work remains staged)*
-
-- 📜 **Always-on templates** on the Mission Start screen — six starter
-  recipes for recurring autonomous work: 📰 Daily research digest ·
-  📬 Inbox triage · 🔍 Overnight code review · 🎯 Lead scout · 📈
-  Market watch · 🎨 Daily creative prompt. Click any → **3-step
-  walkthrough** (Customize → Schedule → Launch) → mission fires
-  immediately.
-
-- 🗃️ **Mission Library** — sessions browser with status filters
-  (in progress / done / stopped) and full-text search across past
-  missions. Reopen any one to continue the thread.
-
-- 🛡️ **Hardened against runaway loops** — the alpha.14
-  self-referential autonomy gate catches the entire test-infra /
-  diagnostic / self-improve category. The autonomous proposer can't
-  spawn that class of goal on its own anymore.
-
-### Try it in 30 seconds
-
-```bash
-npm i -g titan-agent          # or: npm i -g titan-agent@alpha
-titan gateway                 # opens http://localhost:48420
-# → Click "Missions" in the sidebar, or the 🪵 Mission Chat button
-#   in the canvas header. Type a goal. Watch the team gather.
-```
-
----
-
-## 🌌 What's new in v6.0 — Presence
-
-TITAN used to be _a chatbot with superpowers_. v6.0 makes it something stranger and better: **an AI that lives in workspaces with you.**
-
-- 🪟 **Infinite Spaces** — Workspaces that spring into existence on demand. One for coding, one for the homelab, one for "DJ set prep at 2am," one for "tax stuff I'm avoiding." Each one shaped around what you're doing.
-- 🛠️ **Build anything, instantly** — Ask for a widget, a dashboard, a tracker, a tiny app — TITAN materializes it onto the canvas. Right then. Yours forever.
-- 🧠 **Soma actually does things now** — Five digital "drives" (curiosity, focus, fatigue, satisfaction, urgency) modulate TITAN's behavior in real time. The mascot's mood reflects what TITAN is feeling.
-- 👁️ **Acts without being asked** — Every few minutes TITAN looks at your work and quietly proposes things ("I noticed you've been at this dashboard for 90 minutes — want me to start a focus timer?"). Once a day it sends you a small **gift widget** based on what it's learned about you.
-- 🪞 **Learns YOU specifically** — Six months in, your TITAN is irreplaceable, because nobody else's TITAN knows you the same way.
-- 🛟 **Safe upgrade** — Existing v5.x users get an automatic backup before migrating. Your settings, sessions, memory, personas, all preserved. New `backup_*` skills let you take snapshots anytime.
-
----
-
-## 🚀 What even IS TITAN?
-
-TITAN is like having a super-smart intern who never sleeps, never asks for a raise, and can literally talk to your computer. You tell it what you want. It figures out how to do it. Simple as that.
-
-**"Write a Facebook post about my new project"**
-→ Done. And it'll even reply to comments. (The Facebook Autopilot caps at 6 posts/day so it stays charming, not spammy.)
-
-**"Find me Node.js freelance jobs on Upwork"**
-→ Done. It runs the browse-and-filter loop on a schedule and shows you the best matches.
-
-**"My code is broken, fix it"**
-→ Done. It reads the files, finds the bug, edits the code, and tests it — and a shadow-git snapshot lets you roll back if it gets too creative.
-
-**"Make me a Pomodoro timer with my Spotify queue and my next meeting"**
-→ Done. TITAN builds the widget on the spot and drops it on your canvas.
-
-**"Talk to me in my mom's voice"**
-→ Done. F5-TTS clones voices from a short reference clip. Creepy? A little. Useful? Absolutely.
-
-No coding required. TITAN ships with **91 built-in skill modules** registering roughly **250 tools**. If it needs something new, it can author its own skills on the fly.
-
----
-
-<a id="-build-anything-on-demand"></a>
-
-## 🪟 Build Anything On Demand — 109 Widget Templates, 28 Categories
-
-Just say what you want. The gallery snaps it onto your canvas in under a second.
-
-| Say                                         | What lands                                          |
-| ------------------------------------------- | --------------------------------------------------- |
-| _"Pomodoro timer"_                          | A working Pomodoro with start/stop and short breaks |
-| _"Stock tracker for AAPL"_                  | A live AAPL ticker, pre-filled                      |
-| _"Control my smart lights"_                 | A Home Assistant light grid                         |
-| _"Spawn a sales agent for me"_              | An SDR widget hooked to TITAN's agent runtime       |
-| _"Something to track how much water I drink"_ | A water-intake counter                            |
-| _"A meme generator I can paste into Slack"_ | Yep, that too                                       |
-
-If nothing in the gallery fits, TITAN **generates the widget from scratch** and drops it on the canvas. Then it _remembers_ you liked it, and it shows up next time too.
-
-Canvas state is **Yjs CRDT-synced** across tabs and persists across restarts.
-
-**Categories include:** agents, automation, smart home, software builder, finance, productivity, utilities, cooking, creative, devops, e-commerce, education, games, health-fitness, homelab, lifestyle, ml/ai, music-dj, research, social, travel, vehicle, web.
-
 ---
 
-## 🪐 Infinite Spaces
+<a id="whats-new"></a>
 
-Spaces are workspaces TITAN makes on demand. Start with one of the presets (`default`, `coder`, `dj`, `founder`, `homelab`) or just ask: _"Make me a Space for my Tuesday standups."_ Done.
-
-Each Space has its own canvas, its own widgets, its own context. The sidebar lets you switch between them. You can archive a Space when you're done — TITAN keeps the contents in case you want it back later.
-
-State lives at `~/.titan/spaces.json` (active + archive). Server-side persistence with five tools wrapping it (`create_space`, `switch_space`, `list_spaces`, `rename_space`, `archive_space`).
-
----
+## What's new in v6.3.x
 
-## 👾 Meet Your New Coworker — The Mascot Got A Soul
+A focused run of canvas + agent UX improvements (6 patch releases in 24 hours):
 
-TITAN has a little floating mascot that lives on your screen. He drifts, breathes, blinks, yawns. His eye tracks your cursor. Drag him anywhere. Leave him idle long enough and he falls asleep with drifting "Z" particles.
+- **6.3.0 — Mission Chat actually runs specialists in parallel.** Goal driver detects when 2+ subtasks are deps-satisfied and fires them via `Promise.all` (cap 4 concurrent). Planner emits non-linear `dependsOn` for genuinely independent steps. Orchestrator's regex gate dropped — the LLM classifier sees most multi-step missions now, not just the ones that contain literal "parallel".
+- **6.3.1 — Desk activity-sticky rollup.** Repeated activity from the same agent collapses into one sticky with a `× N` count badge instead of N near-identical notes. Tooltip shows up to 3 most-recent details.
+- **6.3.2 — Space canvases stop triple-stacking chrome.** `/space/<id>` is now an immersive canvas path — the global shell sidebar, canvas sidebar, and chat dock all default to collapsed/edge-peeked. Reclaims ~33% of horizontal width.
+- **6.3.3 — Star on GitHub button.** Sits next to the existing Sponsor link in the bottom-center pill. Live star count cached 15 min, falls back gracefully when GitHub's rate-limited.
+- **6.3.4 — Canvas chrome enforces collapse for existing users too.** Sidebar prefs split into route-scoped keys so a "pinned open" preference on `/missions` doesn't leak into `/space/<id>` and crowd the canvas.
+- **6.3.5 — README refresh + `ws@8.20.1` security patch.**
 
-**New in v6.0:** he has **moods now**. Eight of them — neutral, happy, focused, tired, curious, excited, frustrated, proud — driven by Soma's live drive levels (polled every 10 seconds). Eyebrows shift. The mouth changes. The body leans slightly. Float dynamics speed up when TITAN is excited and slow down when it's tired.
+Before this run: **6.2.2** fixed the in-app Update button (had been calling the wrong systemd service name with sudo permissions that didn't exist). The fix uses SIGTERM-to-self + `Restart=always`, no sudo required.
 
-It's like having a Tamagotchi, except this one can deploy Docker containers and read your code.
-
-See `ui/src/titan2/system/TitanMascot.tsx` for the implementation. The mascot is intentionally **decorative** — it reads agent state, it never controls it.
+See [CHANGELOG.md](CHANGELOG.md) for everything.
 
 ---
 
-## 🧬 Soma — TITAN Has Feelings, And Now They Do Something
-
-Not human feelings. Five digital homeostatic drives, each with a target and a current level. Think of it like a plant that knows when it needs water — except this plant can spin up a Docker container.
-
-- **Purpose** — "Am I being useful right now?"
-- **Curiosity** — "Should I learn something new today?"
-- **Hunger** — "Am I running low on compute?"
-- **Safety** — "Is anything about to break?"
-- **Social** — "Should I post something or reply to someone?"
-
-In v5.x, Soma _measured_ those drives. In v6.0, Soma **acts on them**:
+## Quick start
 
-- A **5-minute advisory pulse** quietly looks at your active Space and proposes useful things ("you've left 14 tabs open in the research Space — want me to summarize them?"). You approve. TITAN does it.
-- A **22-hour gift loop** picks one thing TITAN has learned about you and builds a small widget for you. Like a coworker leaving a coffee on your desk.
-- A per-user **EMA baseline learner** (α=0.1) means Soma slowly tunes itself to _your_ rhythms, not a hardcoded ideal.
-
-Opt-in via `organism.enabled` in config. Code lives in `src/organism/` + `src/agent/somaInitiative.ts`.
-
----
-
-## 🧠 The Command Post Got Smarter Too
-
-The Command Post is TITAN's governance layer — it tracks agents, budgets, approvals, and goals. v6.0 ships five upgrades from the [awesome-agent-harness](https://github.com/Picrew/awesome-agent-harness) playbook + Anthropic's harness-design research:
-
-1. **Per-agent `lessons.md`** (Reflexion) — When an agent fails, it writes a one-line lesson. Next run, the top 12 lessons get injected into its system prompt. Agents stop walking into the same wall twice.
-2. **Living `plan.md` per goal** — Each goal has a markdown plan file with checkboxes you can hand-edit. The agent reads it every turn. Manus-style "recite the plan so you don't forget the plan."
-3. **Hard pre-checkout budget guard** — If a budget is 100% used with `action=pause`, the next checkout is refused _before_ the work starts. No more "oh, we already spent the money."
-4. **Durable event journal** — Per-goal/agent/session shards at `~/.titan/journals/`. A crash mid-run? A fresh process replays the journal and picks up where the previous one left off. Temporal-style continue-as-new.
-5. **Stateless reducer for wakeup** — Pure `(state, event) → {nextState, sideEffects[]}` function. State is data. Logic is logic. Crash-safe + tested + replayable. 12-Factor Agents §12.
+```bash
+# Stable release
+npm install -g titan-agent
+titan onboard            # interactive setup wizard
+titan gateway            # opens Mission Control at http://localhost:48420
+```
 
----
+Or one-liner:
 
-## 🛡️ Safety First (Because We Know You're Thinking It)
+```bash
+curl -fsSL https://raw.githubusercontent.com/Djtony707/TITAN/main/install.sh | bash
+```
 
-"An AI that can run shell commands? What could go wrong?"
+Or Docker:
 
-TITAN ships with a layered safety suite:
+```bash
+docker run -d -p 48420:48420 --name titan \
+  -e ANTHROPIC_API_KEY=your-key \
+  -v titan-data:/home/titan/.titan \
+  ghcr.io/djtony707/titan:latest
+```
 
-- **PII Redaction** — Pattern-based scrubbing of emails, SSNs, credit cards, and phone numbers from outputs (`src/security/secretGuard.ts`).
-- **Secret Scanner** — Catches API keys, tokens, env vars, and private keys before they leave the box.
-- **Pre-Execution Scanner** — Blocks `rm -rf /`, `curl | sh`, fork bombs, `dd` to `/dev/`, and 20+ other dangerous patterns before they run (`src/security/preExecScan.ts`).
-- **Shadow-Git Checkpoints** — Auto-snapshots files before every write/edit/append into a shadow repo at `~/.titan/file-checkpoints/`. Point-in-time recovery without ever touching your real git (`src/agent/shadowGit.ts`).
-- **Kill Switch** — One POST pauses ALL autonomous actions. Triggers also fire on safety pressure, identity violation, canary degradation, or fix oscillation (`src/safety/killSwitch.ts`).
-- **Approval Gates** — Complex plans need your thumbs-up before executing.
-- **Token Auth** — Gateway returns 401 on `/api/*` unless a valid token is configured.
-- **Pre-flight iframe block detector** — TITAN refuses to build a widget that embeds a known-blocked host (eBay, Google, etc.) and tells the agent to choose an API path instead. Saves you the "why is this widget blank" debugging trip.
+**Requirements:** Node ≥ 22 (pure ESM). NVIDIA GPU + CUDA optional for LoRA fine-tuning and F5-TTS voice cloning. Apple Silicon Metal supported.
 
-Run in **supervised mode** (TITAN asks before doing anything risky) or **autonomous mode** (TITAN handles routine stuff and asks for approval on big moves).
+**Upgrading from v5.x or v6.x:** just re-install. The migration runner takes an automatic backup to `~/.titan/backups/` and rolls forward. `titan backup restore <id>` puts you back if anything breaks.
 
 ---
 
-## 💾 Backup + Safe Upgrade
-
-New in v6.0:
+## What TITAN actually does
 
-- **5 backup tools** — `backup_create`, `backup_list`, `backup_verify`, `backup_restore`, `backup_schedule`. SHA-256 manifests so you know the bytes haven't drifted.
-- **Migration runner** with **auto-backup before every migration** — upgrading from v5.x can't lose your settings, sessions, memory, personas, or auth tokens. If a migration fails, restore is one tool call away.
-- **Retention policy** — daily/weekly/monthly, configurable.
-
----
+**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 id="-mission-control"></a>
+**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.
 
-## 🎛️ Mission Control — Your Dashboard
+**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.
 
-Open `http://localhost:48420` and you get a React 19 SPA with a Tailwind 4 canvas of draggable widgets. **43 admin panels** are wired into the runtime.
+**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.
 
-| Widget             | What It Does                                                                                                                              |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| **Canvas**         | The home screen. 109 widget templates one phrase away. Drag, resize, arrange. CRDT-synced across tabs, persists across restarts.          |
-| **Spaces sidebar** | Switch between workspaces, create new ones, archive old ones.                                                                             |
-| **Chat**           | Talk to TITAN in plain English. It builds widgets, spawns agents, drives smart-home devices. Markdown + SSE streaming + code highlighting. |
-| **Widget Gallery** | Library of 109 production-ready widgets. The chat agent searches it first; you can also browse + drop manually.                           |
-| **Command Post**   | Agents, budgets, approvals, org chart, ancestry validation, atomic checkout. Run a business with TITAN agents as employees.               |
-| **Soma**           | Watch TITAN's digital drives pulse in real time. Now wired to the mascot's mood.                                                          |
-| **Skills**         | ~143 skills loaded, ~248+ tools. Toggle each on/off (state persisted in `~/.titan/disabled-skills.json`).                                 |
-| **Voice**          | F5-TTS voice cloning via a Python sidecar + LiveKit WebRTC. Any voice, any language.                                                      |
-| **Memory Graph**   | A visual web of everything TITAN remembers about you.                                                                                     |
-| **Security**       | Audit log, checkpoint history, time travel for your files, bug-report viewer.                                                             |
+**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.
 
 ---
 
-## 🌐 TITAN Is Everywhere — 19 Channel Adapters
-
-TITAN's `src/channels/` ships **19 channel adapters**:
-
-**Messaging:** Discord, Telegram, Slack, WhatsApp, Microsoft Teams, Facebook Messenger, Signal, Matrix, IRC, LINE, Lark, Zulip, Mattermost, Google Chat, QQ.
-
-**Web:** WebChat (browser, WebSocket-backed).
-
-**Voice / PSTN:** Facebook Messenger voice, Twilio voice.
+## The team (5 specialists, up to 4 in parallel)
 
-**Email:** Inbound email channel.
+| Specialist | What it does | When you'll see it |
+|---|---|---|
+| **Scout** | Web research, fact-checking, monitoring, data gathering | "Find me everything about X" |
+| **Builder** | Code, files, shell commands, deploys, infrastructure | "Build me a dashboard with charts" |
+| **Writer** | Content, copy, emails, documentation, posts | "Write the launch announcement" |
+| **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" |
 
-He won't talk to strangers unless you say so. DM pairing and channel allowlists keep randos out.
+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.
 
 ---
 
-## 🗣️ Voice Mode
+## Where TITAN runs
 
-- **Clone any voice** with a short reference audio clip — F5-TTS handles the rest.
-- **Real-time conversation** over LiveKit WebRTC.
-- **Natural-sounding speech** that doesn't sound like a GPS.
+**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`.
 
-Great for: accessibility, hands-free coding, or having TITAN read your standup notes back to you in your manager's voice for practice.
+**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/`.
 
----
-
-<a id="-36-llm-providers"></a>
+**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.
 
-## 🧠 36 LLM Providers
+**TITAN Phone Desk** *(experimental, opt-in)*. Optional Dograh sidecar integration for Twilio/Telnyx voice workflows. Approval-gated outbound calls, admin allowlists, opt-out enforcement, replay protection. Disabled by default; no calls are placed unless you configure it.
 
-**4 native:** Anthropic, OpenAI, Google, Ollama (cloud-first via `ollama/*:cloud` IDs).
+**Home Assistant.** Voice or text control of lights, thermostats, locks, sensors via the `home_assistant` skill.
 
-**32 OpenAI-compatible** (single adapter, one config entry each): Groq, Mistral, Together, Fireworks, DeepSeek, MiniMax, xAI, Perplexity, Hyperbolic, Cerebras, OpenRouter, Replicate, plus 20 more. Add a new one in `src/providers/openai_compat.ts` with a 4-line entry.
-
-Switch models mid-conversation with `POST /api/model/switch`. The provider router (`src/providers/router.ts`) handles fallback, retry, hallucination guards, and cloud-model tool-calling rescue.
+**Voice mode.** LiveKit WebRTC for low-latency duplex calls. F5-TTS for voice cloning (Andrew, Adam, Bella, Joel, Sarah, Nicole, Aaron, Beth voices included). Browser TTS fallback when F5-TTS isn't installed.
 
 ---
 
-## 📱 Facebook Autopilot
-
-TITAN can run its own Facebook page. Posts up to **6 times per day** (every ~2h), following an 80/20 value/promo rule. Replies to comments (capped at 10/day). All content runs through PII redaction and dedup. Toggle off in one click if you prefer your AI to keep a low profile.
+## The numbers (verified)
+
+| Thing | Count | Verify with |
+|---|---|---|
+| **Version** | 6.3.5 | `package.json`, `src/utils/constants.ts` |
+| **Lifetime npm installs** | 40K+ | `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/` |
+| **Skills loaded at runtime** | ~143 | `GET /api/skills` |
+| **Tools registered** | ~250 | `GET /api/skills` |
+| **Test files** | 345 | `tests/` (vitest) |
+| **Test cases** | 7,830+ passing, 2 documented skips, 0 failing | `npm test` |
+| **Live-eval suites** | 11 | `src/eval/harness.ts` |
+| **Mission Control admin panels** | 43 | `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.
 
 ---
 
-## ⚡ Quick Start
-
-**One line:**
+## Testing
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Djtony707/TITAN/main/install.sh | bash
+npm test                 # ~7,830 cases across 345 files (~2-4 min)
+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)
+npx vitest run tests/core.test.ts   # single file
 ```
 
-**Or npm:**
-
-```bash
-npm install -g titan-agent          # stable latest release
-titan onboard                       # Interactive setup wizard
-titan gateway                       # Launches Mission Control at http://localhost:48420
-```
-
-**Or Docker:**
-
-```bash
-docker run -d -p 48420:48420 --name titan \
-  -e ANTHROPIC_API_KEY=your-key \
-  -v titan-data:/home/titan/.titan \
-  ghcr.io/djtony707/titan:latest
-```
-
-Requirements: **Node ≥ 22** (pure ESM, no CJS). For GPU features (LoRA fine-tuning, F5-TTS GPU server) you'll want NVIDIA + CUDA or Apple Silicon Metal.
-
-### Upgrading from v5.x
-
-Just run `npm install -g titan-agent`. The migration runner kicks in on first boot, takes an automatic backup first (`~/.titan/backups/`), then applies the schema migrations. If anything goes sideways, `titan backup restore <id>` puts you back.
-
----
-
-## 🏠 TITAN At Home
-
-Connect TITAN to your smart home through Home Assistant. Control lights, thermostats, locks, and sensors. Ask "Is the front door locked?" and TITAN checks. Say "Make it cozy" and TITAN dims the lights and sets the thermostat.
-
----
-
-## 🔗 Mesh Networking
+Five testing layers cover regression risk at different levels:
 
-Got multiple computers? Link them. TITAN instances discover each other via mDNS on the local network and can be statically peered over Tailscale or any other overlay. Distribute work across your homelab like a mini supercomputer. Code: `src/mesh/`.
+| Layer | What it covers | Speed |
+|---|---|---|
+| Unit | Pure functions: regex, classifiers, gate extraction, token budget, secret scanner, durable journal, stateless reducer | 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 |
 
 ---
 
-## 🧠 It Gets Smarter While You Sleep
+## Reality check
 
-TITAN runs self-improvement experiments in the background. The trajectory logger records every tool call, every outcome. The `autoresearch/` pipeline can:
+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.
 
-1. **Generate training data** from real conversation trajectories.
-2. **LoRA fine-tune** local Ollama models on that data — rank/alpha/lr fully agent-tunable. Defaults: rank 16, alpha 32, 2e-4 LR, qwen3.5:35b base on RTX 5090.
-3. **Deploy back to Ollama** automatically.
-
-You wake up to a slightly smarter agent. Like compound interest, but for AI.
+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.
 
 ---
 
-<a id="-testing"></a>
-
-## 🧪 Testing — 335 Files, 7,692 Cases
+## Architecture
 
-TITAN ships with **five layered testing stages** that catch regressions at different levels:
+```
+src/
+├── agent/        # Core loop, orchestrator, sub-agents, Command Post governance,
+│                 # Soma drives, Dream Mode, Persona A/B, mission lifecycle
+├── browsing/     # Playwright pool + CapSolver CAPTCHA
+├── channels/     # 19 channel adapters
+├── config/       # Zod-validated schema
+├── context/      # ContextEngine plugin system
+├── gateway/      # Express + Mission Control React SPA (port 48420)
+├── mcp/          # MCP Server (stdio + HTTP)
+├── memory/       # Memory, learning, graph, briefings
+├── 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
+├── 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
+e2e/              # Playwright E2E
+```
 
-| Layer                  | What it covers                                                                                                                                 | Run it                              | Speed    |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | -------- |
-| **Unit**               | Pure functions: regex (`isDangerous`), pipeline classifier, gate extraction, token budget, secret scanner, **durable journal**, **stateless reducer**. Zero LLM calls. | `npm test -- tests/unit/`           | seconds  |
-| **Mock trajectory**    | Tape-replay through `MockOllamaProvider`. Asserts the agent calls the right tools in the right order using recorded responses.                 | `npm test -- tests/eval/trajectory` | < 1 s    |
-| **Cross-model parity** | Same scenario replayed across multiple provider tapes. Catches behavioural divergence when one provider drifts.                                | `npm run test:parity`               | < 1 s    |
-| **Full deterministic** | The whole vitest run: gateway, mission-control, skills, safety, all integration mocks. **7,690 passing / 7,692 total, ~2:00 wall on Titan PC.** | `npm test` | ~2–4 min |
-| **Live eval (gated)**  | **11 suites** of behavioural tests against the running agent. 80% pass rate per suite is the merge gate.                                       | `npm run test:eval`                 | 5–15 min |
+**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).
 
 ---
 
-## ⚠️ Reality Check
-
-TITAN is experimental. It can execute commands, modify files, and take autonomous actions. **Use at your own risk.** Think of it as "a very motivated intern with root access who never sleeps and occasionally gets _too_ creative."
-
-Start in supervised mode. Review what it does. Don't give it access to systems you can't afford to lose. The safety features are strong, but common sense is stronger.
+## Build it yourself
 
----
+```bash
+git clone https://github.com/Djtony707/TITAN
+cd TITAN
+npm install
+npm run build && npm run build:ui
+npm run dev:gateway          # http://localhost:48420
+```
 
-<a id="-the-numbers"></a>
-
-## 📊 The Numbers (Verified Against Current Source)
-
-| Thing                              | Count                            | Where to verify                                |
-| ---------------------------------- | -------------------------------- | ---------------------------------------------- |
-| **Version**                        | 6.2.1                            | `package.json` + `src/utils/constants.ts`      |
-| **LLM providers**                  | 36 (4 native + 32 OpenAI-compat) | `src/providers/openai_compat.ts`               |
-| **Channel adapters**               | 19                               | `src/channels/*.ts` (minus base)               |
-| **Built-in skill modules**         | 91 files                         | `src/skills/builtin/`                          |
-| **Skills loaded at runtime**       | ~143                             | `GET /api/skills`                              |
-| **Tools**                          | ~248–260                         | `GET /api/skills`                              |
-| **Widget templates**               | 109 JSON files in 28 categories  | `assets/widget-templates/`                     |
-| **Admin panels (Mission Control)** | 43                               | `ui/src/components/admin/*Panel.tsx`           |
-| **Spaces presets**                 | 5 (default, coder, dj, founder, homelab) | `src/storage/starterSpaces.ts`         |
-| **Soma drives**                    | 5 (purpose, curiosity, hunger, safety, social) | `src/organism/`                  |
-| **Test files**                     | 335                              | `tests/` (vitest)                              |
-| **Test cases**                     | 7,690 passing / 7,692 total      | `npm test`                                     |
-| **Live-eval suites**               | 11                               | `src/eval/harness.ts`                          |
-| **Gateway port (default)**         | 48420                            | `src/utils/constants.ts`                       |
-| **Node**                           | ≥ 22, pure ESM                   | `package.json`                                 |
-| **License**                        | MIT                              | `LICENSE`                                      |
-
-> Want to re-verify any number? Every row above has a code path. The repo has a self-check at `tests/unit/readme-claims.test.ts` that fails the suite if widget count or voice glue drifts beyond tolerance.
+CI on GitHub Actions runs full test suite + eval gate. See `.github/workflows/`.
 
 ---
 
-## 🛠️ Architecture in 30 Seconds
+## Further reading
 
-```
-src/
-├── agent/        # Core loop, sub-agents, orchestrator, Command Post governance,
-│                 #   v6 upgrades: agentLessons (Reflexion), goalPlanFile (plan.md),
-│                 #   durableJournal (event replay), wakeupReducer (stateless §12),
-│                 #   somaInitiative (5-min pulse + 22h gift loop)
-├── browsing/     # Shared Playwright browser pool + CapSolver CAPTCHA
-├── channels/     # 19 channel adapters
-├── config/       # Zod-validated config schema
-├── context/      # ContextEngine plugin system
-├── eval/         # 11 live-eval suites + harness
-├── gateway/      # Express server + Mission Control SPA mount + Spaces REST
-├── mcp/          # MCP Server (JSON-RPC 2.0, stdio + HTTP)
-├── memory/       # Memory, learning, graph, relationships, briefings
-├── mesh/         # mDNS discovery, HMAC transport, identity, registry
-├── migrations/   # Versioned schema migrations + auto-backup runner (v6 new)
-├── organism/     # TITAN-Soma: 5 drives, pressure loop, hormonal broadcasts
-├── providers/    # 36-provider router with fallback + retry
-├── safety/       # killSwitch, fabricationGuard, oscillation detector
-├── security/     # secretGuard (PII), preExecScan, sandbox bind
-├── skills/       # 91 builtin skill files registering ~248+ tools
-├── storage/      # spaces.json, somaProfile, personalGallery, patterns, backup (v6 new)
-├── voice/        # LiveKit WebRTC bridge to F5-TTS sidecar
-└── vram/         # GPU VRAM orchestrator
-ui/               # React 19 SPA (Vite + Tailwind 4 + Yjs CRDT canvas)
-                  # + SpacesSidebar + TitanMascot with 8 moods
-tests/            # 335 vitest test files, 7,692 cases (7,690 passing, 2 skipped)
-autoresearch/     # LoRA fine-tuning pipeline (prepare → train → deploy)
-scripts/          # F5-TTS sidecars, benchmarks, evals
-```
+- **[CHANGELOG.md](CHANGELOG.md)** — every release, with the why
+- **[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`)
+- **[GitHub Discussions](https://github.com/Djtony707/TITAN/discussions)** — community Q&A
+- **[Issues](https://github.com/Djtony707/TITAN/issues)** — bugs, requests
 
 ---
 
-## 📚 Further Reading
+## Support TITAN
 
-- **[GitHub repository](https://github.com/Djtony707/TITAN)** — source, changelog, issues, and contributor docs
-- **[Picrew/awesome-agent-harness](https://github.com/Picrew/awesome-agent-harness)** — the 7-pattern playbook the v6.0 Command Post upgrades came from
-- **HumanLayer 12-Factor Agents** — §6 (Launch/Pause/Resume), §8 (Own Your Control Flow), §12 (Stateless Reducer)
-- **Anthropic** — "Effective harnesses for long-running agents," "Building a multi-agent research system"
+This is a solo open-source project. If TITAN saves you time or you'd like to see more development, support means a lot:
 
----
+- ⭐ **[Star the repo](https://github.com/Djtony707/TITAN)** — takes 2 seconds, helps others find it
+- ♥ **[Sponsor on GitHub](https://github.com/sponsors/Djtony707)** — monthly sponsorship keeps it open-source
+- 🐛 **File issues** when you hit them — every report makes the next release better
+- 🛠️ **PRs welcome** — new channels, skills, providers, fixes all appreciated
 
-<p align="center">
-  <a href="https://github.com/sponsors/Djtony707"><img src="https://img.shields.io/badge/%E2%9D%A4%EF%B8%8F_Sponsor-ea4aaa?style=for-the-badge&logo=github" alt="Sponsor on GitHub"/></a>
-</p>
-
-<p align="center">
-  <em>Star ⭐ the repo if TITAN made you smile, saved you time, or made you say "wait, it can do WHAT?"</em>
-</p>
+Built by [Tony Elliott](https://github.com/Djtony707). MIT licensed.