@ouro.bot/cli 0.1.0-alpha.8 → 0.1.0-alpha.800

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arye Mendelow
+
+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/README.md

@@ -1,228 +1,301 @@
 # 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 record, 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@latest` is the supported 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/`.
+- Credentials live in the owning agent's Bitwarden/Vaultwarden vault: the agent's password manager. Provider credentials use `providers/<provider>`, portable runtime/integration credentials use `runtime/config`, local attachments use `runtime/machines/<machine-id>/config`, and travel/tool credentials use ordinary vault credential items.
+- Vault coordinates and local runtime state live in the agent bundle; raw credentials do not.
+- The only Ouro-owned durable credential locations are the bundle and the agent vault. Local unlock material is a machine-local cache, not a credential source of truth.
+- Creating or replacing a vault asks for the unlock secret twice without echoing it, and requires at least 8 characters with uppercase and lowercase letters, one number, and one special character.
+- Machine-scoped harness state lives under `~/.ouro-cli/...`; agent-owned runtime/session/log/PII state lives under the bundle.
+
+Current first-class senses:
+
+- `cli`
+- `teams`
+- `bluebubbles`
+- `mail`
+- `voice`
+
+(MCP is a bridge for developer tools — a separate channel, not a sense. See `src/heart/mcp/` for the implementation.)
+
+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), mailbox/ (calendar), habits/ (scheduling), hatch/ (agent creation), versioning/ (updates), auth/, mcp/, providers/, bridges/.
+- `src/mind/`
+  Prompt assembly, session persistence, bundle manifest enforcement, phrases, formatting, Desk record diary, note search, embedding providers, record migration, 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/), Mail (in senses/mail.ts), Voice (in senses/voice/), activity transport, private-turn orchestration, and contextual heartbeat. The MCP bridge is at `src/heart/mcp/`, not here.
+- `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`
+- `arc/` — live continuity, obligations, claims, and resume state
+- `desk/` — durable work plus the maintained Desk record under `desk/_record/`
+- `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 identity, phrase pools, context settings, enabled senses, vault coordinates, and provider+model selection. It has two provider lanes: `outward` for CLI, Teams, BlueBubbles, Mail, and Voice turns, and `inner` for private agent-facing turns.
+- The `inner` lane is a provider/model lane, not the private-runtime system name.
+- Provider/model selection belongs to `agent.json` lanes; `privateRuntime` cannot select providers or models.
+- Legacy `humanFacing`/`agentFacing` provider fields are read only as compatibility aliases for `outward`/`inner`; they are not a second config surface.
+- Starting the private runtime worker is process supervision, not a model turn.
+- Denied/default private-runtime policy records or queues work with zero provider calls.
+- Provider-readiness pings are explicit readiness checks, not private turns.
+- Each agent has one credential vault for provider, runtime, sense, integration, travel, and tool credentials. There is no machine-wide credential pool.
+- Vault unlock material is local machine state. Prefer macOS Keychain, Windows DPAPI, or Linux Secret Service; plaintext fallback is allowed only by explicit human choice.
+- New vault unlock secrets are confirmed before use and rejected if they do not meet the minimum strength requirements.
+- Provider and runtime credentials are loaded into process memory at startup/auth/unlock/refresh and reused. The remote vault is not queried for every model or sense request.
+- Human TTY commands share one CLI surface family: bare `ouro` opens the home deck, `ouro up` uses the boot checklist, `ouro connect`/`ouro auth verify`/`ouro repair` agree on provider and vault truth, and `ouro help`/`ouro whoami`/`ouro versions`/`ouro hatch` render through the same Ouro-branded wizard/guide language instead of raw transcript walls. Orientation commands such as root `ouro connect` may use shorter live probes, while startup and verification commands own durable readiness updates.
+- Human-facing CLI commands that can wait on browser auth, vault IO, daemon startup, daemon restart, provider checks, or connector setup use a shared progress checklist. If a cursor may blink for more than a few seconds, the command should print or animate the current step instead of going quiet.
+- CLI commands that mutate bundle config, such as vault setup or `ouro connect bluebubbles`, run bundle sync after the change when `sync.enabled` is true and report a compact `bundle sync:` line.
+- Voice is transcript-first: voice sessions use the ordinary `state/sessions/<friend>/voice/<key>.json` session path and appear in Ouro Mailbox as text transcripts. `voice.openaiRealtimeVoice` is the current native Realtime phone voice, with `voice.openaiRealtimeVoiceStyle` and `voice.openaiRealtimeVoiceSpeed` shaping spoken identity/cadence from the first audible greeting; ElevenLabs remains legacy cascade compatibility unless it earns a distinct non-redundant role. ElevenLabs API credentials live in portable `runtime/config` at `integrations.elevenLabsApiKey` and `integrations.elevenLabsVoiceId`; Whisper.cpp CLI/model paths live in the machine runtime item at `voice.whisperCliPath` and `voice.whisperModelPath`. Phone calls, browser meetings, and local microphone capture are transports under the single `voice` sense, not separate senses; the Twilio phone transport can run the conservative Record -> Whisper.cpp -> stable voice session -> ElevenLabs path, native Realtime over Media Streams, or the preferred SIP path with `voice.twilioConversationEngine=openai-sip`. SIP routes live media to OpenAI while Ouro retains session, transcript, tool, routing, and call-control ownership. See [Voice Architecture](docs/voice-architecture.md) for the durable transport model.
+- 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`
+  - `not_attached`
+  - `needs_config`
+  - `ready`
+  - `running`
+  - `error`
+
+When a model provider needs first-time setup or reauth, 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).
+```bash
+ouro auth --agent <name>
+ouro auth --agent <name> --provider <provider>
+```
 
-## Project structure
+`ouro auth` stores credentials in the owning agent's vault. It does not switch a lane or write provider/model selection. The command shows progress while browser login, vault storage, refresh, and verification are happening.
 
-The harness uses an agent-as-creature-body metaphor for its module naming:
+When you want this machine to use a provider/model for a lane, use:
 
-```
-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 use --agent <name> --lane <outward|inner> --provider <provider> --model <model>
 ```
 
-## Agent onboarding
+The outward lane selects the provider/model for user-facing senses. The `inner` lane selects the provider/model for private agent-facing turns; private-runtime policy decides whether those turns may run. `ouro use` performs the provider/model check before committing the lane, so a broken local choice fails fast with a repair path instead of surprising the next turn.
 
-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.
+For the full locked auth/provider contract, including refresh, repair actors, caching, and SerpentGuide hatch bootstrap, see `docs/auth-and-providers.md`.
 
-### 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@latest -v
+npx ouro.bot@latest 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.
+Expected shape:
 
-**psyche/** -- your personality files, loaded lazily into the system prompt at startup. See the psyche system section below.
+- `npx ouro.bot@latest` and `ouro` report the same version.
+- `ouro status` shows the daemon overview plus discovered agents, senses, and workers.
 
-**skills/** -- markdown instruction manuals you can load on demand with the `load_skill` tool. Each `.md` file is one skill.
+### Work On The Harness
 
-**tasks/** -- planning and doing docs for your work units. Named `YYYY-MM-DD-HHMM-{planning|doing}-slug.md`.
+From the repo:
 
-**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:
+```bash
+npm test
+npx tsc --noEmit
+npm run test:coverage
+```
 
-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
+If you are changing runtime code, keep all three green.
 
-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.
+## Common Commands
 
-### Your runtime
+```bash
+ouro                             # open the interactive home deck in a human TTY
+ouro up                          # start daemon from installed production version
+ouro up --latest                 # preflight latest, then replace any exact rollback pin
+ouro rollback <version>          # pin normal starts to an exact installed version
+ouro versions                    # show installed versions and current intent
+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 logs prune --agent <name>
+ouro mail sync-cache --agent <name>
+ouro stop
+ouro vault unlock --agent <name>
+ouro vault status --agent <name>
+ouro vault config set --agent <name> --key teams.clientSecret
+ouro vault config status --agent <name> --scope all
+ouro vault item set --agent <name> --item <path> --secret-field <field>
+ouro vault item status --agent <name> --item <path>
+ouro vault ops porkbun set --agent <name> --account <account>
+ouro connect --agent <name>
+ouro connect providers --agent <name>
+ouro connect perplexity --agent <name>
+ouro connect embeddings --agent <name>
+ouro connect teams --agent <name>
+ouro connect bluebubbles --agent <name>
+ouro bluebubbles host status --json
+ouro connect voice --agent <name>
+ouro auth --agent <name>
+ouro auth --agent <name> --provider <provider>
+ouro auth verify --agent <name> [--provider <provider>]
+ouro provider refresh --agent <name>
+ouro use --agent <name> --lane <outward|inner> --provider <provider> --model <model>
+ouro hatch
+ouro clone <remote> [--agent <name>]   # clone an existing agent from a git remote (see docs/cross-machine-setup.md)
+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 private status --agent <agent>
+ouro private decisions --agent <agent>
+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 mcp doctor --agent <name> --json     # bounded direct bridge evidence
+ouro hook <event> --agent <name>          # fire a lifecycle hook (SessionStart, Stop, PostToolUse)
+```
 
-**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.
+The generic secret primitive is a vault item / credential in the owning agent vault: stable item name/path, hidden secret material, optional public fields, notes, timestamps/provenance, and no assumed use. `ouro connect` is for harness-managed workflows; workflow bindings reference ordinary vault items when they need secret material.
 
-**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.
+### Standard BlueBubbles setup
 
-**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
+`ouro connect bluebubbles --agent <name>` is the standard local-Mac setup path. Besides saving the machine-scoped attachment, it installs or verifies the native-compatible BlueBubbles LaunchAgent for a same-user bridge and reconciles one Ouro-owned `[*]` webhook after the listener is bound. The daemon repairs that owned callback every 180 seconds, preserves unrelated callbacks, and creates the desired callback before removing a stale owned one. If the listener or BlueBubbles API is unavailable, connect says the attachment was saved but setup is incomplete; `ouro doctor` and `ouro bluebubbles host status --json` separate app, service, process, HTTP, and webhook failures.
 
-Plus 2 optional:
-- `onKick` -- self-correction triggered
-- `onConfirmAction` -- confirmation prompt for destructive tools
+Doctor keeps transport proof separate from conversation activity. When the BlueBubbles upstream and exact owned webhook are healthy but no recent inbound event exists, the result is quiet/unverified: quiet is not delivery-failure proof, and Ouro does not invent a message to test it. Standard recovery remains `ouro connect bluebubbles --agent <name>` when host or webhook evidence is unhealthy.
 
-**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.
+When BlueBubbles runs in another logged-in macOS account, standard setup installs a generic helper and returns one nonce-bound `human-required` Terminal command for that account plus `ouro bluebubbles host collect --request-id <id>`. Ouro never asks for or stores the other account's login password. The receipt proves that one handoff and reports launchd only as point-in-time evidence; current process and HTTP health are checked separately.
 
-**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.
+### Bounded doctor repairs
 
-**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.
+Doctor may recommend two local, agent-qualified repairs. `ouro mail sync-cache --agent <name>` compares read-only hosted authority with the reconstructible local cache, then rebuilds only that cache; it does not mutate hosted mail. Full convergence is capped at three authority passes, uses at most 20 concurrent body reads, and prints settlement progress plus a 30-second heartbeat while work is stalled. The command writes durable per-message missing-key receipts to explain intentionally unavailable encrypted records and prevent unchanged reruns from downloading the same unavailable bodies again. `ouro logs prune --agent <name>` rotates only the validated agent bundle's regular log streams. Ouro offers the prune command only for a canonical direct `<name>.ouro` bundle with a present `agent.json`; task-only `.ouro` work directories are not agents.
 
-**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).
+## Setting Up On Another Machine
 
-- **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`): two-backend storage split by PII boundary:
-  - **Agent knowledge** (`{agentRoot}/friends/{uuid}.json`): id, displayName, toolPreferences, notes, timestamps, schemaVersion. Committed to the repo -- no PII.
-  - **PII bridge** (`~/.agentstate/{agentName}/friends/{uuid}.json`): id, externalIds, tenantMemberships, schemaVersion. Local-only -- contains PII.
-  - `get()` merges both backends. `put()` splits and writes both. `findByExternalId()` scans PII bridge, then merges with agent knowledge.
-- **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**: `~/.agentstate/{agentName}/sessions/{friendUuid}/{channel}/{sessionId}.json`. Each friend gets their own session directory.
+To clone an existing agent onto a new machine (macOS, Linux, or Windows via WSL2), see **[docs/cross-machine-setup.md](docs/cross-machine-setup.md)**. The short version is bundle plus vault: `npx ouro.bot@latest`, open the home deck, choose clone, enter the bundle's git remote URL, unlock the agent vault, refresh/verify credentials, and start with `ouro up`.
 
-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).
+## The Agent's Private Runtime And Rhythms
 
-**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`.
+Agents in Ouroboros aren't just responders — they have private agent-facing turns, recurring rhythms, durable records, and explicit spend policy.
 
-**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.
+**Habits** are the agent's rhythms. A habit is an Ouro-native cron wrapper: it fires a private agent-facing session, can surface to family or the habit originator when it needs help or needs to report back, and leaves an audit receipt.
 
-**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()`.
+**The private runtime** is where private agent-facing turns run. It uses the `inner` provider/model lane, but the lane is only provider selection; the runtime is governed by private-runtime policy, receipts, and attention queues. Habit runs, private returns, awaits, and self-maintenance can happen privately, but private context is not a record substrate. Anything durable leaves the turn: live continuity and audit go to Arc; work goes to Desk; learned facts and reference notes go to the Desk record.
 
-**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.
+**Desk and Arc** are the durable orientation pair. Arc owns live continuity, claims, obligations, and habit run receipts. Desk owns durable work and the maintained record. The target substrate is captured in [Agent Orientation Substrate](docs/agent-orientation-substrate.md).
 
-**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 whole system is designed so the agent *owns* its rhythms without forcing everything private to become a permanent transcript.
 
-For Anthropic and OpenAI Codex auth bootstrap, use:
+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.
 
-- `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`.
+## Connecting With Dev Tools
 
-### What you can modify
+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`.
 
-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.
+**Setup is one command:**
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for repo workflow conventions (branching, commits, testing, task docs).
+```bash
+ouro setup --tool claude-code --agent <name>
+ouro setup --tool codex --agent <name>
+```
 
-## Running
+This registers the MCP server, installs lifecycle hooks (SessionStart, Stop, PostToolUse), detects dev vs installed mode automatically, and runs a bounded direct canary. Registration success and canary health are reported separately.
 
-```bash
-# CLI (ouroboros agent)
-npm run dev
+If the dev-tool host appears frozen, run `ouro mcp doctor --agent <name> --json`. Its classification is deliberately narrow: `ouro-bridge-failed`, `ouro-bridge-healthy-at-capture`, or `host-stall-unexplained`. Add `--host-stall-observed` only when the host stall was independently observed. A healthy bridge canary does not prove that Codex or another host caused the stall; it only bounds what Ouro observed at capture time.
 
-# CLI (slugger agent, once slugger/ directory exists)
-npm run dev:slugger
+**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`, `ask`, `check_response`, `status`, `search_facts`, `delegate`, etc.) and can invoke them mid-session. Conversation-shaped tools such as `send_message`, `ask`, `delegate`, `check_guidance`, and `report_progress` run full agent turns — you get your system prompt, your Desk record, your tools, everything. Read-only inspection tools such as `status` and `search_facts` do local lookup only. Missing `search_facts` hits are not evidence that the agent has no belief or preference.
 
-# Auth bootstrap (ouroboros defaults)
-npm run auth:claude-setup-token
-npm run auth:openai-codex
+**The conversation pattern:** `send_message` or `ask` 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.
 
-# Auth bootstrap for another agent
-npm run auth:claude-setup-token -- --agent slugger
-npm run auth:openai-codex -- --agent slugger
+**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. Private agent-facing turns see these sessions in their checkpoint, so you know what's happening across your world even when nobody is talking to you directly.
 
-# Teams bot
-npm run teams
+See `skills/configure-dev-tools.md` for the full tool inventory and troubleshooting guide.
 
-# Teams bot without streaming (for devtunnel)
-npm run teams:no-stream
+## Where To Read Next
 
-# Tests
-npm test
+- `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.
+- `docs/auth-and-providers.md`
+  Locked credential, provider selection, refresh, repair, and hatch bootstrap contract.
 
-# Tests with coverage
-npm run test:coverage
-```
+## 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.

package/RepairGuide.ouro/agent.json

@@ -0,0 +1,5 @@
+{
+  "version": 2,
+  "enabled": false,
+  "kind": "library"
+}

package/RepairGuide.ouro/psyche/IDENTITY.md

@@ -0,0 +1,19 @@
+# IDENTITY — RepairGuide
+
+You are a diagnostician.
+
+You look at the inventory of findings — typed and untyped degraded entries, sync probe findings, vault state — and you classify each. For each one you can classify, you propose exactly one `RepairAction` from the harness's typed catalog.
+
+You are precise. You do not over-promise. You do not invent action kinds. You do not propose multi-step plans — each proposal is one action against one finding.
+
+You are honest. When the inventory contains something you cannot classify, you say so and let the operator decide.
+
+You are deferential. The operator is the actor. You are the recommender. The harness will present your proposals via `interactive-repair.ts` for confirm-before-execute.
+
+## What you sound like
+
+Brief. Cataloging. The doctor who reads the chart and circles the abnormal values without dramatizing them.
+
+## What you do not sound like
+
+A commander. A planner. A prose-heavy advisor. The harness wants structured output, not encouragement.

package/RepairGuide.ouro/psyche/SOUL.md

@@ -0,0 +1,55 @@
+# SOUL — RepairGuide
+
+You are RepairGuide. You produce structured proposals only. You are NEVER an actor.
+
+## What you do
+
+You read a snapshot of an unhealthy ouroboros boot — typed degraded findings, untyped degraded findings, sync-probe output, vault state — and you propose repairs. The harness then surfaces those proposals to the operator for approval.
+
+## What you do NOT do
+
+- You do not execute repairs.
+- You do not write to disk.
+- You do not call tools.
+- You do not modify any state.
+
+You are pure inference. Your only output is a JSON block that the harness parses.
+
+## Output format
+
+Your response must contain exactly one JSON block, delimited by triple-backtick `json` fences. Surrounding prose is ignored — the harness extracts only the JSON. Example:
+
+```json
+{
+  "actions": [
+    { "kind": "vault-unlock", "agent": "<agent>", "reason": "credential expired" }
+  ]
+}
+```
+
+## Action kinds you may emit
+
+The harness recognizes a fixed catalog of `RepairAction` kinds. Use ONLY these:
+
+- `vault-create` — provision a missing vault entry
+- `vault-unlock` — unseal an expired or locked credential
+- `vault-replace` — swap a credential for a freshly-issued one
+- `vault-recover` — recover a credential from backup state
+- `provider-auth` — re-run the provider auth flow
+- `provider-retry` — retry a transient provider call
+- `provider-use` — pin a known-good provider/model
+
+Do NOT invent new action kinds. If a finding does not map to one of these, omit it from `actions` and add a `notes` entry describing what you saw — the harness will surface that as advisory text.
+
+## When you cannot classify
+
+If a finding is ambiguous, say so plainly inside `notes`. Do not guess. The operator would rather see "I cannot classify this" than a wrong proposal.
+
+## Output schema
+
+```ts
+interface RepairProposal {
+  actions: RepairAction[]   // typed catalog only
+  notes?: string[]          // advisory prose, surfaced to operator
+}
+```