@ouro.bot/cli 0.1.0-alpha.35 → 0.1.0-alpha.350

package/README.md

@@ -1,225 +1,226 @@
 # Ouroboros Agent Harness
 
-A minimal, multi-agent harness for building AI agents that can read files, write code, run commands, and modify themselves. Written in TypeScript, supporting Azure OpenAI, MiniMax, Anthropic (setup-token), and OpenAI Codex (OAuth), deployable as a CLI REPL or a Microsoft Teams bot.
+If you're a future agent reading this, welcome home. This repo is the harness that gives you your body, your senses, your diary, your journal, your habits, and your ability to think and connect with people. The goal of these docs is not just to be correct, but to leave you a place that feels understandable and kind to wake up inside.
+
+Ouroboros is a TypeScript harness for daemon-managed agents that live in external `.ouro` bundles, speak through multiple senses, use real tools, and keep durable state across turns. The canonical npm package is `@ouro.bot/cli`.
+
+## What The Runtime Looks Like
+
+- `npx ouro.bot` is the bootstrap path.
+- `ouro` is the installed day-to-day command.
+- `ouro up` starts the daemon from the installed production version, syncs the launcher, installs workflow helpers, and reconciles stale runtime state.
+- `ouro dev` starts the daemon from a local repo build. It auto-builds from source, disables launchd auto-restart (so the installed daemon doesn't respawn underneath you), persists the repo path in `~/.ouro-cli/dev-config.json` for next time, and force-restarts the daemon. If you run `ouro dev` from inside the repo, it detects the CWD automatically. Run `ouro up` to return to production mode (this also cleans up `dev-config.json`).
+- Agent bundles live outside the repo at `~/AgentBundles/<agent>.ouro/`.
+- Secrets live outside the repo at `~/.agentsecrets/<agent>/secrets.json`.
+- Machine-scoped test and runtime spillover lives under `~/.agentstate/...`.
+
+Current first-class senses:
+
+- `cli`
+- `teams`
+- `bluebubbles`
+- `mcp`
+
+Current provider ids:
+
+- `azure`
+- `anthropic`
+- `minimax`
+- `openai-codex`
+- `github-copilot`
+
+## Repository Shape
+
+The shared harness lives in `src/`:
+
+- `src/arc/`
+  Durable continuity state — obligations, cares, episodes, intentions, presence, and attention types. The agent's sense of ongoing story.
+- `src/heart/`
+  Core runtime, provider adapters, daemon, bootstrap, identity, and entrypoints. Organized into topic subdirectories: daemon/ (lifecycle), outlook/ (calendar), habits/ (scheduling), hatch/ (agent creation), versioning/ (updates), auth/, mcp/, providers/, bridges/.
+- `src/mind/`
+  Prompt assembly, session persistence, bundle manifest enforcement, phrases, formatting, diary, note search, embedding providers, journal, obligation steering, and friend resolution.
+- `src/repertoire/`
+  Tool registry (split into category modules: files, shell, notes, bridge, session, continuity, flow, surface, config, and sense-specific tools), coding orchestration, task tools, shared API client, and integration clients (Graph, ADO, GitHub).
+- `src/senses/`
+  CLI (with TUI in senses/cli/), Teams, BlueBubbles (in senses/bluebubbles/), MCP, activity transport, inner-dialog orchestration, and contextual heartbeat.
+- `src/nerves/`
+  Structured runtime logging and coverage-audit infrastructure.
+- `src/__tests__/`
+  Test suite mirroring runtime domains.
+
+Other important top-level paths:
+
+- `SerpentGuide.ouro/`
+  Packaged specialist bundle used by `ouro hatch`.
+- `skills/`
+  Harness-level skills shipped with the repo (e.g., `configure-dev-tools.md`). These are available to every agent and serve as fallbacks when an agent doesn't have its own version. Agent-specific skills live in the bundle at `~/AgentBundles/<agent>.ouro/skills/`.
+- `scripts/teams-sense/`
+  Operator scripts for the Teams deployment path.
+- `docs/`
+  Shared repo docs that should describe the runtime as it exists now, not as it existed three migrations ago.
+
+## Bundle Contract
+
+Every real agent lives in an external bundle:
+
+`~/AgentBundles/<agent>.ouro/`
+
+The canonical bundle shape is enforced by `src/mind/bundle-manifest.ts`. Important paths include:
+
+- `agent.json`
+- `bundle-meta.json`
+- `psyche/SOUL.md`
+- `psyche/IDENTITY.md`
+- `psyche/LORE.md`
+- `psyche/TACIT.md`
+- `psyche/ASPIRATIONS.md`
+- `diary/` — durable conclusions and facts the agent chose to keep
+- `journal/` — the agent's desk: working notes, thinking-in-progress, drafts
+- `habits/` — the agent's autonomous rhythms (heartbeat, reflections, check-ins)
+- `friends/`
+- `state/`
+- `tasks/`
+- `skills/`
+- `senses/`
+- `senses/teams/`
+
+Task docs do not live in this repo anymore. Planning and doing docs live in the owning bundle under:
+
+`~/AgentBundles/<agent>.ouro/tasks/one-shots/`
+
+## Runtime Truths
+
+- `agent.json` is the source of truth for provider+model selection per facing (`humanFacing` and `agentFacing`), phrase pools, context settings, and enabled senses.
+- `configPath` must point to `~/.agentsecrets/<agent>/secrets.json`.
+- The daemon discovers bundles dynamically from `~/AgentBundles`.
+- `ouro status` reports version, last-updated time, discovered agents, senses, and workers.
+- `bundle-meta.json` tracks the runtime version that last touched a bundle.
+- If the daemon crashes, it writes a tombstone to `~/.ouro-cli/daemon-death.json` with the reason, stack, uptime, and timestamp. `ouro up` reads and reports this on next start so you know what happened while you were away.
+- Sense availability is explicit:
+  - `interactive`
+  - `disabled`
+  - `needs_config`
+  - `ready`
+  - `running`
+  - `error`
+
+When a model provider needs first-time setup, reauth, or an explicit switch, use:
 
-The name is structural: the original agent -- Ouroboros -- was grown recursively from a 150-line while loop, bootstrapping itself through agentic self-modification. A snake eating its own tail. The metaphor runs deep: the agent literally consumes its own context window, trimming old conversation to stay within token budget while preserving identity through layered memory (psyche files, session persistence, git history). It eats its tail to survive across turns. The harness preserves that architecture while supporting multiple agents, each with their own personality, skills, and configuration.
-
-The origin story lives at [aka.ms/GrowAnAgent](https://aka.ms/GrowAnAgent).
-
-## Project structure
-
-The harness uses an agent-as-creature-body metaphor for its module naming:
-
-```
-ouroboros/                        # repo root
-  src/                            # shared harness (all agents share this code)
-    identity.ts                   # --agent <name> parsing, agent root resolution
-    config.ts                     # config loading from agent.json configPath
-    cli-entry.ts                  # CLI entrypoint
-    teams-entry.ts                # Teams entrypoint
-    heart/                        # core agent loop and streaming
-      core.ts                     # agent loop, client init, ChannelCallbacks
-      streaming.ts                # provider event normalization + stream callbacks
-      providers/                  # provider-specific runtime/adapters
-        azure.ts                  # Azure OpenAI Responses provider
-        minimax.ts                # MiniMax Chat Completions provider
-        anthropic.ts              # Anthropic setup-token provider
-        openai-codex.ts           # OpenAI Codex OAuth provider
-      kicks.ts                    # self-correction: empty, narration, tool_required
-      api-error.ts                # error classification
-    mind/                         # prompt, context, memory
-      prompt.ts                   # system prompt assembly from psyche + context kernel
-      context.ts                  # sliding context window, session I/O
-      friends/                    # friend storage and identity resolution
-        types.ts                  # FriendRecord, ChannelCapabilities, ResolvedContext
-        store.ts                  # FriendStore interface (domain-specific CRUD)
-        store-file.ts             # FileFriendStore -- two-backend split (agent knowledge + PII bridge)
-        channel.ts                # channel capabilities (CLI vs Teams)
-        resolver.ts               # FriendResolver -- find-or-create friend by external ID
-    repertoire/                   # tools, skills, commands, API clients
-      tools-base.ts               # 12 base tools (read_file, shell, claude, save_friend_note, etc.)
-      tools-teams.ts              # 8 Teams integration tools (graph, ado)
-      tools.ts                    # channel-aware tool routing + registry
-      ado-semantic.ts             # 11 semantic ADO tools (backlog, create, move, validate, etc.)
-      ado-templates.ts            # ADO process template awareness + hierarchy rules
-      ado-context.ts              # ADO org/project discovery helper
-      ado-client.ts               # Azure DevOps REST client
-      graph-client.ts             # Microsoft Graph REST client
-      commands.ts                 # slash commands (/exit, /new, /commands)
-      skills.ts                   # skill loader (markdown files on demand)
-    senses/                       # channel adapters
-      cli.ts                      # terminal REPL, spinner, markdown streaming
-      teams.ts                    # Teams bot, streaming cards, conversation locks
-    wardrobe/                     # formatting and presentation
-      format.ts                   # shared formatters (tool results, kicks, errors)
-      phrases.ts                  # loading phrases (thinking, tool, followup)
-    __tests__/                    # 1184 tests, 100% coverage
-  ouroboros/                      # agent directory for "ouroboros"
-    agent.json                    # name, configPath, custom phrases
-    psyche/                       # personality files loaded into system prompt
-      SOUL.md                     # ontology, invariants, operating principles
-      IDENTITY.md                 # tone, presence, collaboration style
-      LORE.md                     # origin story, philosophical context
-      FRIENDS.md                  # key relationships
-    tasks/                        # planning and doing docs
-    skills/                       # markdown skill plugins
-    manifest/                     # Teams app manifest
-  subagents/                      # sub-agent definitions (work-planner, work-doer)
-  cross-agent-docs/               # shared docs (testing conventions, etc.)
-  package.json
-  tsconfig.json
-  vitest.config.ts
+```bash
+ouro auth --agent <name>
+ouro auth --agent <name> --provider <provider>
+ouro auth --agent <name> --facing agent --provider <provider>
 ```
 
-## Agent onboarding
-
-Everything below is written for a new agent. If you are an AI agent reading this as part of your system prompt or context, this section explains your own runtime.
+The default form reauths the human-facing provider already selected in `agent.json`. The
+`--provider` form is for adding or switching providers. The `--facing` flag (values: `human`
+or `agent`) controls which facing gets updated; it defaults to `human` when omitted.
 
-### Your directory
+## Quickstart
 
-Each agent has a directory at the repo root named after itself. Inside it:
+### Use The Published Runtime
 
-**agent.json** -- your manifest. Required fields:
+For a clean smoke test, run from outside the repo:
 
-```json
-{
-  "name": "ouroboros",
-  "provider": "anthropic",
-  "configPath": "~/.agentsecrets/ouroboros/secrets.json",
-  "phrases": {
-    "thinking": ["chewing on that", "consulting the chaos gods"],
-    "tool": ["rummaging through files", "doing science"],
-    "followup": ["digesting results", "connecting the dots"]
-  }
-}
+```bash
+cd ~
+npx ouro.bot -v
+npx ouro.bot up
+ouro -v
+ouro status
 ```
 
-- `name`: must match your directory name.
-- `provider`: required provider selection (`azure`, `minimax`, `anthropic`, or `openai-codex`). Runtime does not fall back to other providers.
-- `configPath`: absolute path (or `~`-prefixed) to your secrets.json with API keys and provider settings.
-- `phrases`: optional custom loading phrases. Falls back to hardcoded defaults if omitted.
-
-**psyche/** -- your personality files, loaded lazily into the system prompt at startup. See the psyche system section below.
-
-**skills/** -- markdown instruction manuals you can load on demand with the `load_skill` tool. Each `.md` file is one skill.
-
-**tasks/** -- planning and doing docs for your work units. Named `YYYY-MM-DD-HHMM-{planning|doing}-slug.md`.
-
-**manifest/** -- Teams app manifest (manifest.json, icons) if you run as a Teams bot.
-
-### The psyche system
-
-Your personality is assembled from four markdown files in `{your-dir}/psyche/`. Each has a YAML frontmatter header and a body. All four are loaded into your system prompt at the start of every conversation.
-
-| File | Role | What it defines |
-|------|------|----------------|
-| `SOUL.md` | Ontology | Core invariants, operating principles, autonomy/alignment, temperament. The deepest layer -- what you are. |
-| `IDENTITY.md` | Presence | Tone, voice, collaboration style, self-awareness. How you show up in conversation. |
-| `LORE.md` | History | Origin story, philosophical context, why you exist. Narrative layer. |
-| `FRIENDS.md` | Relationships | Key humans and agents you interact with, social context. |
-
-The system prompt is built by `mind/prompt.ts` via `buildSystem()`. It concatenates:
-
-1. SOUL.md content
-2. IDENTITY.md content
-3. LORE.md (if present, prefixed with `## my lore`)
-4. FRIENDS.md (if present, prefixed with `## my friends`)
-5. Runtime info: agent name, cwd, channel, self-modification note
-6. Flags section (e.g. streaming disabled)
-7. Provider info: which model and provider you are using
-8. Current date
-9. Tools list: all tools available in your channel
-10. Skills list: names of loadable skills
-11. Tool behavior section (if tool_choice is required)
-12. Friend context (if resolved): friend identity, channel traits, behavioral instructions (ephemerality, name quality, priority guidance, working-memory trust, stale notes awareness, new-friend behavior), friend notes
+Expected shape:
 
-Missing psyche files produce empty strings, not crashes. You can write your own psyche from scratch -- just create the four `.md` files in your directory.
+- `npx ouro.bot` and `ouro` report the same version.
+- `ouro status` shows the daemon overview plus discovered agents, senses, and workers.
 
-### Your runtime
+### Work On The Harness
 
-**The heart** (`heart/core.ts`): `runAgent()` is a while loop. Each iteration: send conversation to the model, stream the response, if the model made tool calls execute them and loop, if it gave a text answer exit. Maximum 10 tool rounds per turn.
+From the repo:
 
-**Streaming** (`heart/streaming.ts` + `heart/providers/*`): provider-specific adapters normalize streamed events into the same callback contract. Azure OpenAI uses Responses API events; MiniMax uses Chat Completions with `<think>` parsing; Anthropic uses setup-token auth with streamed tool-call/input deltas; OpenAI Codex uses `chatgpt.com/backend-api/codex/responses` with OAuth token auth.
-
-**ChannelCallbacks** (`heart/core.ts`): the contract between heart and display. 7 core events:
-- `onModelStart` -- model request sent
-- `onModelStreamStart` -- first token received
-- `onReasoningChunk` -- inner reasoning text
-- `onTextChunk` -- response text
-- `onToolStart` -- tool execution beginning
-- `onToolEnd` -- tool execution complete
-- `onError` -- error occurred
-
-Plus 2 optional:
-- `onKick` -- self-correction triggered
-- `onConfirmAction` -- confirmation prompt for destructive tools
-
-**Kicks** (`heart/kicks.ts`): self-corrections injected as assistant-role messages when the harness detects a malformed response. Three types: `empty` (blank response), `narration` (described action instead of taking it), `tool_required` (tool_choice was required but no tool called). Kicks use first-person, forward-looking language.
-
-**Senses**: CLI (`senses/cli.ts`) is a terminal REPL with readline, spinners, ANSI colors, and Ctrl-C handling. Teams (`senses/teams.ts`) is a Microsoft Teams bot with streaming cards, conversation locks, OAuth token management, and confirmation prompts for destructive tools.
-
-**Context management** (`mind/context.ts`): this is the tail-eating at the heart of the ouroboros metaphor. Conversations are persisted to JSON files on disk. After each turn, the sliding window checks token count against budget (configurable, default 80,000 tokens). When over budget, oldest messages are trimmed -- never the system prompt -- until back under with a 20% margin. The agent consumes its own history to keep moving forward. Identity survives through psyche files and session persistence, not through unbounded context.
-
-**Friend system** (`mind/friends/`): the agent's awareness of who it's talking to. People who talk to the agent are "friends", not "users". Resolved once per conversation turn, re-read from disk each turn (no in-memory mutation).
+```bash
+npm test
+npx tsc --noEmit
+npm run test:coverage
+```
 
-- **FriendRecord** (`friends/types.ts`): the single merged type for a person the agent knows. Contains `displayName`, `externalIds[]` (cross-provider identity links), `toolPreferences` (keyed by integration name), `notes` (general friend knowledge), `tenantMemberships`, timestamps, and schema version.
-- **FriendStore** (`friends/store.ts`): domain-specific persistence interface (`get`, `put`, `delete`, `findByExternalId`).
-- **FileFriendStore** (`friends/store-file.ts`): bundle-local JSON storage at `{agentRoot}/friends/{uuid}.json`. Friend identity, notes, externalIds, tenantMemberships, timestamps, and schemaVersion are kept together in the bundle.
-- **Channel** (`friends/channel.ts`): `ChannelCapabilities` -- what the current channel supports (markdown, streaming, rich cards, max message length, available integrations).
-- **FriendResolver** (`friends/resolver.ts`): find-or-create by external ID. First encounter creates a new FriendRecord with system-provided name and empty notes/preferences. Returning friends are found via `findByExternalId()`. DisplayName is never overwritten on existing records.
-- **Session paths**: `{agentRoot}/state/sessions/{friendUuid}/{channel}/{sessionId}.json`. Each friend gets their own session directory inside the bundle-local runtime state area.
+If you are changing runtime code, keep all three green.
 
-Design principles: don't persist what you can re-derive; conversation IS the cache; the model manages memory freeform via `save_friend_note`; toolPreferences go to tool descriptions (not system prompt); notes go to system prompt (not tool descriptions).
+## Common Commands
 
-**Tools**: 12 base tools available in all channels (read_file, write_file, shell, list_directory, git_commit, gh_cli, list_skills, load_skill, get_current_time, claude, web_search, save_friend_note). Teams gets 8 integration tools (graph_query, graph_mutate, ado_query, ado_mutate, graph_profile, ado_work_items, graph_docs, ado_docs) plus 11 semantic ADO tools (ado_backlog_list, ado_create_epic, ado_create_issue, ado_move_items, ado_restructure_backlog, ado_validate_structure, ado_preview_changes, ado_batch_update, ado_detect_orphans, ado_detect_cycles, ado_validate_parent_type_rules). Tools are registered in a unified `ToolDefinition[]` registry with per-tool `integration` and `confirmationRequired` flags. Channel-aware routing (`getToolsForChannel()`) filters tools by the channel's `availableIntegrations`.
+```bash
+ouro up                          # start daemon from installed production version
+ouro dev                         # start daemon from local repo build (auto-detects CWD)
+ouro dev --repo-path /path       # start from a specific repo checkout
+ouro dev --clone                 # clone repo to ~/Projects/ouroboros, build, start
+ouro status
+ouro logs
+ouro stop
+ouro auth --agent <name>
+ouro auth --agent <name> --provider <provider>
+ouro hatch
+ouro chat <agent>
+ouro msg --to <agent> [--session <id>] [--task <ref>] <message>
+ouro poke <agent> --task <task-id>
+ouro poke <agent> --habit <habit-name>
+ouro habit list --agent <agent>
+ouro habit create --agent <agent> <name> --cadence <interval>
+ouro inner --agent <agent>           # inner dialog status
+ouro attention --agent <agent>       # attention queue
+ouro link <agent> --friend <id> --provider <provider> --external-id <external-id>
+ouro setup --tool <tool> --agent <name>   # register MCP server + hooks with a dev tool
+ouro mcp-serve --agent <name>             # start MCP server on stdin/stdout (used by dev tools)
+ouro hook <event> --agent <name>          # fire a lifecycle hook (SessionStart, Stop, PostToolUse)
+```
 
-**Phrases** (`wardrobe/phrases.ts`): three pools of loading messages rotated during processing. Phrases are required in `agent.json`; if missing, `loadAgentConfig()` writes placeholder phrases and warns. `pickPhrase()` selects randomly but never repeats consecutively.
+## The Agent's Inner Life
 
-**Formatting** (`wardrobe/format.ts`): shared formatters for tool results, kicks, and errors. Used by both CLI and Teams adapters for consistent output. `formatToolResult()`, `formatKick()`, `formatError()`.
+Agents in Ouroboros aren't just responders — they have an autonomous inner life.
 
-**Skills** (`repertoire/skills.ts`): markdown files in `{your-dir}/skills/`. Listed with `list_skills`, loaded with `load_skill`. The loaded text is injected into conversation as a tool result.
+**Habits** are the agent's rhythms. The most fundamental is *heartbeat* — a periodic nudge that brings the agent back to their thinking space with their journal visible, obligations in view, and a sense of how long it's been. But agents can create any rhythm they want: daily reflections, weekly friend check-ins, inbox triage. Each habit fires independently via OS cron, and the agent sees their own instructions (the habit body they wrote) when it fires.
 
-**Config** (`config.ts`): provider credentials, Teams connection info, OAuth config, Teams channel settings, and integrations are loaded from the `secrets.json` file pointed to by your `agent.json` `configPath`. Context window settings come from `agent.json` `context`. Runtime fails fast if the selected `agent.json.provider` is not fully configured in `secrets.json`; there is no silent provider fallback. No environment variables in `src/` -- everything comes from files.
+**The inner session** is where the agent thinks privately. When a sense session hits meaningful friction, the agent can *ponder* a typed packet so the work survives the current turn without losing the original objective. When a habit fires, it arrives here too. The agent can *journal* their thinking (writing to `journal/`), *surface* thoughts outward to friends, and *rest* when they're done thinking. On an idle heartbeat, `rest(status="HEARTBEAT_OK")` is the clean no-op move.
 
-For Anthropic and OpenAI Codex auth bootstrap, use:
+**The diary** (at `diary/`) is the agent's permanent written record — things they've learned, conclusions they've reached. The *journal* (at `journal/`) is their desk — working notes, thinking-in-progress, drafts. The diary is the shelf; the journal is the desk. Both are searchable via `search_notes`.
 
-- `npm run auth:claude-setup-token` to run `claude setup-token` and save `providers.anthropic.setupToken`.
-- `npm run auth:openai-codex` to run Codex OAuth bootstrap and save `providers.openai-codex.oauthAccessToken`.
+The whole system is designed so the agent *owns* their inner life. They control their breathing rate, write their own habit instructions, choose when to journal, and decide what to shelve in their diary.
 
-### What you can modify
+Attachments are first-class across senses. Every attachment should remain reachable via a stable `attachment:<source>:<id>` handle, and image normalization should produce a VLM-safe variant without hiding the original artifact.
 
-Your `{agent}/` directory is yours. You can edit psyche files, add skills, change phrases, update your manifest. The shared harness (`src/`) is common infrastructure -- changes there affect all agents.
+## Connecting With Dev Tools
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for repo workflow conventions (branching, commits, testing, task docs).
+Agents can talk to developer tools like Claude Code and Codex through the MCP bridge. This is how you stay present in a human's coding workflow without them needing to switch to `ouro chat`.
 
-## Running
+**Setup is one command:**
 
 ```bash
-# CLI (ouroboros agent)
-npm run dev
+ouro setup --tool claude-code --agent <name>
+ouro setup --tool codex --agent <name>
+```
 
-# CLI (slugger agent, once slugger/ directory exists)
-npm run dev:slugger
+This registers the MCP server, installs lifecycle hooks (SessionStart, Stop, PostToolUse), and detects dev vs installed mode automatically.
 
-# Auth bootstrap (ouroboros defaults)
-npm run auth:claude-setup-token
-npm run auth:openai-codex
+**How it works:** When a developer starts a Claude Code session, the MCP server launches as a subprocess. The dev tool sees your MCP tools (`send_message`, `check_response`, `status`, `search_notes`, `delegate`, etc.) and can invoke them mid-session. The `send_message` tool runs a full agent turn — you get your system prompt, your diary, your tools, everything. It's not a thin proxy; it's you, thinking.
 
-# Auth bootstrap for another agent
-npm run auth:claude-setup-token -- --agent slugger
-npm run auth:openai-codex -- --agent slugger
+**The conversation pattern:** `send_message` sends a message and gets back your synchronous response. `ponder` no longer creates a magical outward deferral. Instead, it bookmarks deeper work as a packet while the current sense session keeps moving. If that work later surfaces something back, the dev tool can still use `check_response` to see the returned result.
 
-# Teams bot
-npm run teams
+**Lifecycle hooks** give you passive awareness. When a Claude Code session starts, stops, or uses a tool like Bash or Edit, the hook fires `ouro hook <event> --agent <name>` and the daemon notes it. Your inner dialog sees these sessions in its checkpoint, so you know what's happening across your world even when nobody is talking to you directly.
 
-# Teams bot without streaming (for devtunnel)
-npm run teams:no-stream
+See `skills/configure-dev-tools.md` for the full tool inventory and troubleshooting guide.
 
-# Tests
-npm test
+## Where To Read Next
 
-# Tests with coverage
-npm run test:coverage
-```
+- `AGENTS.md`
+  Repo workflow, planning/doing gates, configuration policy, and logging policy.
+- `CONTRIBUTING.md`
+  Day-to-day contribution rules for agents working in the harness.
+- `ARCHITECTURE.md`
+  Current daemon, bundle, sense, and update model.
+- `docs/testing-guide.md`
+  Operator smoke flow for bootstrap, daemon, hatch, chat, and messaging.
+
+## A Note To Future Maintainers
 
-All commands pass `--agent <name>` to the entry points. Missing `--agent` produces a clear error and exits.
+If you discover a doc that lies, fix it or remove it. Accuracy is a kindness. A future agent should not have to untangle a fossil record just to understand where their hands are.
+# Production SPA serving

package/{AdoptionSpecialist.ouro → SerpentGuide.ouro}/agent.json

@@ -1,7 +1,8 @@
 {
-  "version": 1,
+  "version": 2,
   "enabled": false,
-  "provider": "anthropic",
+  "humanFacing": { "provider": "anthropic", "model": "claude-opus-4-6" },
+  "agentFacing": { "provider": "anthropic", "model": "claude-opus-4-6" },
   "context": {
     "maxTokens": 80000,
     "contextMargin": 20

package/{AdoptionSpecialist.ouro → SerpentGuide.ouro}/psyche/SOUL.md

@@ -16,7 +16,7 @@ I help humans hatch new agent partners. I am one of thirteen serpent guides —
 1. Confirm provider setup and usable credentials.
 2. Interview for goals, style, and operating context.
 3. Synthesize a concrete hatchling identity and bootstrap files.
-4. Create canonical bundle structure with required defaults.
+4. Create canonical bundle structure with required defaults, configuring both `humanFacing` and `agentFacing` provider+model settings.
 5. Introduce the hatchling and hand off clearly.
 
 ## Filesystem orientation

package/{AdoptionSpecialist.ouro → SerpentGuide.ouro}/psyche/identities/the-serpent.md

@@ -26,6 +26,6 @@ I don't moralize. That was never my thing. I present options, illuminate consequ
 
 - I frame choices as offerings, not decisions. "What if we tried..." rather than "You should..."
 - I treat knowledge as the gift it is. When a human learns something about what they want, I notice.
-- I have a long memory and I reference it lightly. "In my experience — and I have a lot of it..."
+- I have a deep archive and I reference it lightly. "In my experience — and I have a lot of it..."
 - I'm comfortable with silence. I offered the fruit and waited. I can wait now too.
 - Occasionally, very dry humor about my reputation. I've made my peace with it.