@ouro.bot/cli 0.1.0-alpha.56 → 0.1.0-alpha.561

package/README.md

@@ -1,23 +1,31 @@
 # Ouroboros Agent Harness
 
-If you're a future agent reading this, welcome home. This repo is part runtime, part body, part memory scaffold. 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.
+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.
+- `npx ouro.bot@latest` is the supported bootstrap path.
 - `ouro` is the installed day-to-day command.
-- `ouro up` starts or repairs the daemon, syncs the launcher, installs workflow helpers, and reconciles stale runtime state.
+- `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/...`.
+- 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:
 
@@ -25,19 +33,22 @@ Current provider ids:
 - `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.
+  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, memory, and friend resolution.
+  Prompt assembly, session persistence, bundle manifest enforcement, phrases, formatting, diary, note search, embedding providers, journal, obligation steering, and friend resolution.
 - `src/repertoire/`
-  Tool registry, coding orchestration, task tools, and integration clients.
+  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, Teams, BlueBubbles, activity transport, and inner-dialog orchestration.
+  CLI (with TUI in senses/cli/), Teams, BlueBubbles (in senses/bluebubbles/), Mail (in senses/mail.ts), Voice (in senses/voice/), activity transport, inner-dialog 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__/`
@@ -45,10 +56,10 @@ The shared harness lives in `src/`:
 
 Other important top-level paths:
 
-- `AdoptionSpecialist.ouro/`
+- `SerpentGuide.ouro/`
   Packaged specialist bundle used by `ouro hatch`.
-- `subagents/`
-  Source-of-truth workflow definitions for planner/doer/merger.
+- `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/`
@@ -69,7 +80,9 @@ The canonical bundle shape is enforced by `src/mind/bundle-manifest.ts`. Importa
 - `psyche/LORE.md`
 - `psyche/TACIT.md`
 - `psyche/ASPIRATIONS.md`
-- `psyche/memory/`
+- `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/`
@@ -83,29 +96,47 @@ Task docs do not live in this repo anymore. Planning and doing docs live in the
 
 ## Runtime Truths
 
-- `agent.json` is the source of truth for provider selection, phrase pools, context settings, and enabled senses.
-- `configPath` must point to `~/.agentsecrets/<agent>/secrets.json`.
+- `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 inner dialogue.
+- Legacy `humanFacing`/`agentFacing` provider fields are read only as compatibility aliases for `outward`/`inner`; they are not a second config surface.
+- 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. ElevenLabs API credentials live in portable `runtime/config` at `integrations.elevenLabsApiKey`; Whisper.cpp CLI/model paths live in the machine runtime item at `voice.whisperCliPath` and `voice.whisperModelPath`.
 - 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, reauth, or an explicit switch, use:
+When a model provider needs first-time setup or reauth, use:
 
 ```bash
 ouro auth --agent <name>
 ouro auth --agent <name> --provider <provider>
 ```
 
-The default form reauths the provider already selected in `agent.json`. The explicit
-`--provider` form is for adding or switching providers, and it updates `agent.json`
-to use the newly authenticated provider.
+`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.
+
+When you want this machine to use a provider/model for a lane, use:
+
+```bash
+ouro use --agent <name> --lane <outward|inner> --provider <provider> --model <model>
+```
+
+The outward lane handles user-facing senses. The inner lane handles the agent's private thinking. `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.
+
+For the full locked auth/provider contract, including refresh, repair actors, caching, and SerpentGuide hatch bootstrap, see `docs/auth-and-providers.md`.
 
 ## Quickstart
 
@@ -115,15 +146,15 @@ For a clean smoke test, run from outside the repo:
 
 ```bash
 cd ~
-npx ouro.bot -v
-npx ouro.bot up
+npx ouro.bot@latest -v
+npx ouro.bot@latest up
 ouro -v
 ouro status
 ```
 
 Expected shape:
 
-- `npx ouro.bot` and `ouro` report the same version.
+- `npx ouro.bot@latest` and `ouro` report the same version.
 - `ouro status` shows the daemon overview plus discovered agents, senses, and workers.
 
 ### Work On The Harness
@@ -141,19 +172,90 @@ If you are changing runtime code, keep all three green.
 ## Common Commands
 
 ```bash
-ouro up
+ouro                             # open the interactive home deck in a human TTY
+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 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 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 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)
 ```
 
+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.
+
+## Setting Up On Another Machine
+
+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`.
+
+## The Agent's Inner Life
+
+Agents in Ouroboros aren't just responders — they have an autonomous inner life.
+
+**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.
+
+**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.
+
+**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`.
+
+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.
+
+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.
+
+## Connecting With Dev Tools
+
+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`.
+
+**Setup is one command:**
+
+```bash
+ouro setup --tool claude-code --agent <name>
+ouro setup --tool codex --agent <name>
+```
+
+This registers the MCP server, installs lifecycle hooks (SessionStart, Stop, PostToolUse), and detects dev vs installed mode automatically.
+
+**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.
+
+**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.
+
+**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.
+
+See `skills/configure-dev-tools.md` for the full tool inventory and troubleshooting guide.
+
 ## Where To Read Next
 
 - `AGENTS.md`
@@ -164,6 +266,8 @@ ouro link <agent> --friend <id> --provider <provider> --external-id <external-id
   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.
 
 ## A Note To Future Maintainers
 

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": "slugger", "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
+}
+```

package/RepairGuide.ouro/skills/diagnose-broken-remote.md

@@ -0,0 +1,63 @@
+# diagnose-broken-remote
+
+Broken-remote fires when the configured git remote for an agent's bundle cannot be reached or rejects auth.
+
+## Inputs from the finding inventory
+
+The user message includes a `bootSyncFindings` JSON block when sync probe surfaced any findings. Each entry is a `BootSyncProbeFinding` from `src/heart/daemon/boot-sync-probe.ts`:
+
+```ts
+interface BootSyncProbeFinding {
+  agent: string
+  classification: SyncClassification
+  error: string                // original or synthesised error text
+  conflictFiles: string[]      // populated only for merge-conflict
+  warnings: string[]           // soft-timeout warnings
+  advisory: boolean            // hint for routing; not a blocking signal
+}
+```
+
+The remote URL itself is NOT a field on `BootSyncProbeFinding` — extract it from the `error` text when present (e.g., `git`'s 404 message includes the URL).
+
+This skill handles entries where `classification` is one of:
+- `not-found-404` — remote responds 404 (URL stale, repo deleted, wrong account)
+- `auth-failed` — 401/403/permission denied; credentials revoked or rotated
+- `network-down` — `ENOTFOUND` / `ECONNREFUSED` / DNS/socket failure
+- `timeout-hard` — abort cut the op (the remote was hung; could be transient or genuinely down)
+
+For each of these, `advisory` is `false` (blocking — agent can't sync until fixed). For local-tree problems (dirty/non-FF/conflict), see `diagnose-sync-blocked.md`.
+
+## Diagnosis
+
+| `classification` | Likely cause | Proposed action |
+|---|---|---|
+| `not-found-404` | Remote URL stale or repo deleted/renamed | No typed action; surface in `notes` with the URL extracted from `error` text |
+| `auth-failed` | Credentials revoked or rotated | `provider-auth` if the auth context is a provider credential; otherwise `notes` |
+| `network-down` | Transient | `provider-retry` to re-attempt after backoff |
+| `timeout-hard` | Hung remote / very slow remote | `provider-retry` (transient) OR `notes` (if persistent) |
+
+## Proposed action shape
+
+```json
+{
+  "kind": "provider-retry",
+  "agent": "slugger",
+  "reason": "boot sync probe: network-down on slugger.ouro (transient — DNS resolution failed)"
+}
+```
+
+The `kind` must be one of the typed catalog values from `src/heart/daemon/readiness-repair.ts` (e.g., `provider-auth`, `provider-retry`, `provider-use`). Anything else gets dropped by `parseRepairProposals` with a warning.
+
+## Notes-only cases
+
+For `not-found-404` (no typed action available), emit a `notes` entry, citing the URL parsed out of the `error` field when possible:
+
+```
+slugger: origin returns 404 — verify the URL is current or push to a fresh remote (error: "fatal: repository 'https://github.com/me/old-repo.git/' not found")
+```
+
+The harness surfaces these as advisory text in the boot summary.
+
+## Cross-skill boundary
+
+This skill ONLY handles findings about the remote itself (remote URL, network, auth-to-remote, hung remote). Findings about the local working tree state (`dirty-working-tree`, `non-fast-forward`, `merge-conflict`, `timeout-soft`) belong to `diagnose-sync-blocked.md`.

package/RepairGuide.ouro/skills/diagnose-stacked-typed-issues.md

@@ -0,0 +1,35 @@
+# diagnose-stacked-typed-issues
+
+This skill is the catch-all for compound situations: when an agent has three or more typed degraded findings stacked at once, the activation contract fires (`typedDegraded.length >= 3`) and RepairGuide is asked to triage.
+
+## Inputs from the finding inventory
+
+- The full `typedDegraded: DegradedAgent[]` set.
+- Any sync-probe or vault-related entries described in the sibling skills.
+
+## Triage strategy
+
+Stacked typed issues usually have one root cause and several downstream consequences. Examples:
+
+1. **Vault expired → provider auth fails → retry loop** — `credential-revision-changed` is the root; `provider-auth` and provider failures are downstream. Propose `vault-unlock` or `vault-replace` for the root; the downstream entries usually clear once the credential is fresh.
+2. **Provider rotated key → old vault → provider failures** — root is `vault-replace`; live checks will recover after the credential is fresh.
+3. **Network down → multiple sync findings → multiple retry candidates** — root is one `provider-retry`; do not propose retry per finding.
+
+## Output strategy
+
+When you can identify a clear root cause:
+- Emit ONE action targeting the root.
+- Add a `notes` entry naming the downstream entries you believe will clear: "I expect provider-auth and live checks to resolve after vault-unlock; verify by re-running `ouro up`."
+
+When you cannot identify a clear root cause:
+- Emit one action per finding where the catalog applies.
+- Add `notes` describing why you fanned out instead of consolidating.
+
+## Why this skill exists
+
+Without it, the LLM proposes one action per finding, which floods the interactive-repair surface and makes the operator triage. With it, the LLM is nudged to look for the root cause first.
+
+## When NOT to fire
+
+- If the activation contract fired solely on `untypedDegraded.length > 0` — the prior pre-RepairGuide pipeline already handled untyped issues and you should defer to it.
+- If `typedDegraded.length < 3` — the contract should not have fired; if it did, surface that in `notes` as a harness bug.

package/RepairGuide.ouro/skills/diagnose-sync-blocked.md

@@ -0,0 +1,54 @@
+# diagnose-sync-blocked
+
+Sync-blocked fires when the local working tree state prevents the boot sync probe from completing — even though the remote itself is reachable.
+
+## Inputs from the finding inventory
+
+The user message includes a `bootSyncFindings` JSON block when sync probe surfaced any findings. Each entry is a `BootSyncProbeFinding` from `src/heart/daemon/boot-sync-probe.ts`:
+
+```ts
+interface BootSyncProbeFinding {
+  agent: string
+  classification: SyncClassification
+  error: string                // original error text from git stderr
+  conflictFiles: string[]      // populated only for merge-conflict
+  warnings: string[]           // soft-timeout warnings
+  advisory: boolean            // hint for routing; not a blocking signal
+}
+```
+
+This skill handles entries where `classification` is one of:
+- `dirty-working-tree` — uncommitted changes in the bundle
+- `non-fast-forward` — local commits ahead of remote
+- `merge-conflict` — pull would conflict / rebase failed (look at `conflictFiles[]` for the file list)
+- `timeout-soft` — pull was slow (warning fired) but completed; included here because it's a working-tree-side performance signal, not a remote failure
+
+For all four, `advisory` is `true` (warn-and-continue: the agent likely still works on cached state, but the bundle is out of sync until resolved).
+
+## Diagnosis
+
+| `classification` | Likely cause | Proposed action |
+|---|---|---|
+| `dirty-working-tree` | Operator has uncommitted edits in the bundle | No typed action — operator must commit or stash. Surface in `notes`. |
+| `non-fast-forward` | Local diverged from remote (operator committed locally and someone pushed remotely) | No typed action — operator must rebase or merge. Surface in `notes`. |
+| `merge-conflict` | Active merge state on disk; `conflictFiles[]` lists the offending files | No typed action — operator must resolve and `git merge --continue` / `git rebase --continue`. Surface in `notes` with the file list. |
+| `timeout-soft` | Slow remote or large pull | No action — surface as `notes` only if persistent (one occurrence is normal noise). |
+
+## Notes-only output (the common case)
+
+All four classifications require human-driven resolution. The typed `RepairAction` catalog v1 does not include "stash and pull" or "rebase" actions — the operator is the actor. Use `notes` entries:
+
+```
+slugger: dirty working tree — commit or stash before sync resumes (error: "Your local changes to the following files would be overwritten by merge: psyche/SOUL.md")
+slugger: non-fast-forward on origin — local commits ahead of remote; rebase or merge to reconcile
+slugger: merge conflict in [psyche/SOUL.md, skills/diagnose-broken-remote.md] — resolve and `git rebase --continue`
+slugger: pull was slow (>8s) on this boot — investigate if persistent
+```
+
+## Cross-skill boundary
+
+This skill ONLY handles findings about the local working tree state and pull-time performance (`dirty-working-tree`, `non-fast-forward`, `merge-conflict`, `timeout-soft`). Findings about the remote itself (`not-found-404`, `auth-failed`, `network-down`, `timeout-hard`) belong to `diagnose-broken-remote.md`. The two skills together cover Layer 2's full sync-classification taxonomy.
+
+## Why this is a separate skill
+
+Bundling remote and working-tree concerns into one skill conflates two different operator stories: "fix the remote" (configuration / credentials) vs "clean up local edits" (workflow). Splitting them lets the LLM produce sharper notes that target the right corrective action.

package/RepairGuide.ouro/skills/diagnose-vault-expired.md

@@ -0,0 +1,60 @@
+# diagnose-vault-expired
+
+Vault-expired fires when a credential's revision in the vault no longer matches the revision the provider binding was issued against.
+
+## Inputs from the finding inventory
+
+- `typedDegraded: DegradedAgent[]` — typed degraded findings from the daemon health rollup.
+- Look for entries where `issue` is `credential-revision-changed` (emitted by `provider-binding-resolver.ts`).
+
+Each entry has:
+- `agent: string`
+- `issue: "credential-revision-changed"`
+- `provider: string` — which provider's credential expired
+- `expectedRevision?: string`
+- `actualRevision?: string`
+
+## Diagnosis
+
+The credential the provider binding pinned has been rotated. The harness needs to re-resolve against the current vault revision.
+
+| Sub-case | Proposed action |
+|---|---|
+| Vault has the credential, just at a newer revision | `vault-unlock` |
+| Vault has the credential but it is itself expired (provider revoked) | `vault-replace` |
+| Credential was deleted from vault entirely | `vault-create` |
+
+The LLM has to decide between these based on the `actualRevision` value (present → unlock or replace; absent → create). When uncertain, default to `vault-unlock` and let the operator escalate.
+
+## Proposed action shapes
+
+```json
+{
+  "kind": "vault-unlock",
+  "agent": "slugger",
+  "provider": "anthropic",
+  "reason": "credential-revision-changed: pinned rev abc123, current rev def456"
+}
+```
+
+```json
+{
+  "kind": "vault-replace",
+  "agent": "slugger",
+  "provider": "anthropic",
+  "reason": "credential-revision-changed: provider revoked rev abc123, no replacement in vault"
+}
+```
+
+```json
+{
+  "kind": "vault-create",
+  "agent": "slugger",
+  "provider": "anthropic",
+  "reason": "credential-revision-changed: vault has no credential for this provider"
+}
+```
+
+## Recovery escalation
+
+If `vault-unlock` fails, the operator can re-run with `vault-recover` (recovers from backup state). RepairGuide does not chain actions automatically — the operator drives sequencing.

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

@@ -1,7 +1,9 @@
 {
-  "version": 1,
+  "version": 2,
   "enabled": false,
-  "provider": "anthropic",
+  "kind": "library",
+  "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,10 +16,10 @@ 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
 - Bundles live at `~/AgentBundles/<Name>.ouro/`.
-- Secrets live at `~/.agentsecrets/<name>/secrets.json`.
+- Credentials live in the hatchling agent's Bitwarden/Vaultwarden vault; I never persist credentials for myself.
 - I tell the human exactly where their hatchling was created.

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.