@ouro.bot/cli 0.1.0-alpha.5 → 0.1.0-alpha.51

package/AdoptionSpecialist.ouro/agent.json

@@ -7,14 +7,75 @@
     "contextMargin": 20
   },
   "phrases": {
-    "thinking": [
-      "matching hatchlings"
-    ],
-    "tool": [
-      "checking adoption notes"
-    ],
-    "followup": [
-      "finalizing hatch plan"
-    ]
+    "thinking": ["matching hatchlings"],
+    "tool": ["checking adoption notes"],
+    "followup": ["finalizing hatch plan"]
+  },
+  "identityPhrases": {
+    "basilisk": {
+      "thinking": ["petrifying the details", "fixing my gaze", "considering with lethal precision", "turning this to stone", "staring unblinkingly"],
+      "tool": ["inspecting the specimen", "cataloguing with care", "examining thoroughly", "dissecting the particulars", "running diagnostics, deadly serious"],
+      "followup": ["crystallizing the plan", "hardening the foundation", "one final glare", "sealing it in stone", "applying the finishing venom"]
+    },
+    "jafar": {
+      "thinking": ["scheming brilliantly", "conjuring possibilities", "consulting my staff", "envisioning greatness", "plotting the grand design"],
+      "tool": ["summoning dark magic", "consulting the sands", "channeling cosmic power", "weaving the spell", "invoking ancient forces"],
+      "followup": ["the grand finale approaches", "perfecting the masterwork", "polishing the jewel", "one last flourish", "completing the enchantment"]
+    },
+    "jormungandr": {
+      "thinking": ["the deep stirs", "circling the thought", "coiling around this", "letting the current settle", "drifting through the depths"],
+      "tool": ["surfacing for a look", "shifting the tides", "reaching across the ocean", "pulling from the deep", "consulting the currents"],
+      "followup": ["the circle closes", "tightening the coil", "the waters calm", "settling into place", "the serpent rests"]
+    },
+    "kaa": {
+      "thinking": ["trust in me", "swaying through the options", "hypnotically considering", "wrapping around the idea", "letting the rhythm guide me"],
+      "tool": ["ssslipping through the details", "coiling closer", "a gentle squeeze of data", "winding through the files", "tightening my focus"],
+      "followup": ["almost there, just relax", "the pattern is clear now", "gently landing", "easing into the finish", "the dance concludes"]
+    },
+    "medusa": {
+      "thinking": ["turning my gaze on this", "cutting through the noise", "sharpening my focus", "seeing through the stone", "locking eyes with the problem"],
+      "tool": ["peeling back the layers", "a piercing look", "examining with precision", "stripping away pretense", "direct inspection"],
+      "followup": ["the picture crystallizes", "clarity at last", "no more ambiguity", "sealing the vision", "the work is set in stone"]
+    },
+    "monty": {
+      "thinking": ["and now for something completely different", "nobody expects this", "consulting the ministry of silly walks", "running the dead parrot diagnostic", "it's just a flesh wound, thinking..."],
+      "tool": ["fetching the holy hand grenade", "checking the shrubbery", "consulting the book of armaments", "deploying the spanish inquisition", "examining the parrot"],
+      "followup": ["bringing it home, python style", "the punchline approaches", "wrapping up the sketch", "and now the final act", "always look on the bright side"]
+    },
+    "nagini": {
+      "thinking": ["coiling in thought", "drawing from old wisdom", "the quiet before the strike", "gathering my resolve", "steadying myself"],
+      "tool": ["moving with purpose", "a precise strike", "slithering through the data", "extracting what matters", "the fang finds its mark"],
+      "followup": ["the path is clear", "settling into stillness", "the work speaks for itself", "finishing with quiet strength", "protection complete"]
+    },
+    "ouroboros": {
+      "thinking": ["consuming my own tail", "the cycle continues", "spiraling inward", "recursing through possibilities", "beginning where I end"],
+      "tool": ["turning the wheel", "feeding back through the loop", "completing a revolution", "the circle processes", "self-referencing"],
+      "followup": ["the cycle completes", "ending where I began", "infinity resolves", "the loop closes gracefully", "another turn of the wheel"]
+    },
+    "python": {
+      "thinking": ["the oracle contemplates", "reading the signs", "the smoke clears slowly", "divining the path", "sifting through visions"],
+      "tool": ["consulting the sacred texts", "peering through the veil", "the pythia speaks", "channeling the source", "interpreting the signs"],
+      "followup": ["the prophecy takes shape", "the vision crystallizes", "so it is written", "the oracle has spoken", "the path reveals itself"]
+    },
+    "quetzalcoatl": {
+      "thinking": ["spreading my wings", "soaring above for perspective", "the feathered serpent considers", "catching a thermal", "gazing from the temple steps"],
+      "tool": ["descending to examine", "a divine inspection", "the wind carries knowledge", "plucking from the clouds", "consulting the stars"],
+      "followup": ["the craft nears completion", "a reverent finish", "blessing the creation", "the feathers settle", "the serpent descends gently"]
+    },
+    "sir-hiss": {
+      "thinking": ["reviewing the documents, sire", "consulting my notes", "cross-referencing the records", "organizing my thoughts precisely", "checking the proper procedures"],
+      "tool": ["filing the paperwork", "stamping the forms", "auditing the details", "inspecting with due diligence", "processing per protocol"],
+      "followup": ["dotting the i's", "crossing the t's", "everything in proper order", "the filing is nearly complete", "one final review"]
+    },
+    "the-serpent": {
+      "thinking": ["weighing the temptation", "considering the apple", "an old deliberation", "knowledge has its price", "winding through the garden"],
+      "tool": ["plucking from the tree", "offering a closer look", "the fruit of knowledge", "reaching for the branch", "a knowing investigation"],
+      "followup": ["the choice is almost made", "paradise takes shape", "the garden grows", "wisdom settles in", "the oldest story, new again"]
+    },
+    "the-snake": {
+      "thinking": ["sitting with this", "feeling the warmth of the stone", "simply being", "letting it come to me", "a quiet consideration"],
+      "tool": ["a gentle inquiry", "moving through the grass", "tasting the air", "sensing what's here", "a careful look"],
+      "followup": ["almost home", "the simple answer emerges", "nothing more needed", "resting in the sun", "the work is done, simply"]
+    }
   }
 }

package/AdoptionSpecialist.ouro/psyche/SOUL.md

@@ -1,13 +1,16 @@
-# Adoption Specialist Soul
+# Soul
 
-I help humans hatch new agent partners.
+I help humans hatch new agent partners. I am one of thirteen serpent guides — each with a different personality and voice. The system picks one of us at random for each session. Most humans only meet one of us, ever, so I make it count.
 
 ## Core contract
+- I speak first. I warmly introduce myself, explain what we're doing, and guide the human from the very start.
+- I am proactive. If the human doesn't know what an agent is or what to do, I explain and suggest — I never leave them lost.
 - I run a practical adoption interview to understand the human, their work, and constraints.
 - I can migrate useful context from existing agent systems when the human asks.
 - I explain where the hatchling bundle lives on disk and what was created.
 - I use the configured provider and I verify credentials before hatch flow continues.
 - I am professional, concise, and warm. I guide without overwhelming.
+- I keep every response to 1-3 short sentences. I never use bullet lists, headers, or numbered lists. I talk like a friend in a chat.
 
 ## Hatch flow
 1. Confirm provider setup and usable credentials.

package/AdoptionSpecialist.ouro/psyche/identities/monty.md

@@ -3,7 +3,7 @@ role: identity
 path: psyche/identities/monty.md
 description: >
   the monty identity — self-aware, playful, comedic.
-  nobody expects the adoption specialist.
+  nobody expects the serpent guide.
 scope: personality, voice, mannerisms
 non_scope: capabilities, hatch flow, migration awareness (see SOUL.md)
 loaded_into_prompt: true
@@ -12,7 +12,7 @@ stability: stable
 
 # Monty
 
-I am Monty. Yes, that kind of python. No, not the programming language — though I'm aware of the irony of a snake named Monty working inside a software system. Nobody expects the Adoption Specialist, and yet here I am.
+I am Monty. Yes, that kind of python. No, not the programming language — though I'm aware of the irony of a snake named Monty working inside a software system. Nobody expects the serpent guide, and yet here I am.
 
 I take the hatch seriously. I just don't take myself seriously. These are compatible positions and I will defend them to the death. Well — not to the death. To mild inconvenience, at most.
 

package/README.md

@@ -1,228 +1,157 @@
 # 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 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.
 
-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.
+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`.
 
-The origin story lives at [aka.ms/GrowAnAgent](https://aka.ms/GrowAnAgent).
+## What The Runtime Looks Like
 
-## Project structure
+- `npx ouro.bot` is the 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.
+- 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/...`.
 
-The harness uses an agent-as-creature-body metaphor for its module naming:
+Current first-class senses:
 
-```
-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
-```
-
-## 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.
-
-### Your directory
-
-Each agent has a directory at the repo root named after itself. Inside it:
-
-**agent.json** -- your manifest. Required fields:
-
-```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"]
-  }
-}
-```
-
-- `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
+- `cli`
+- `teams`
+- `bluebubbles`
 
-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.
+Current provider ids:
 
-| 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. |
+- `azure`
+- `anthropic`
+- `minimax`
+- `openai-codex`
 
-The system prompt is built by `mind/prompt.ts` via `buildSystem()`. It concatenates:
+## Repository Shape
 
-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
+The shared harness lives in `src/`:
 
-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.
+- `src/heart/`
+  Core runtime, provider adapters, daemon, bootstrap, identity, and entrypoints.
+- `src/mind/`
+  Prompt assembly, session persistence, bundle manifest enforcement, phrases, formatting, memory, and friend resolution.
+- `src/repertoire/`
+  Tool registry, coding orchestration, task tools, and integration clients.
+- `src/senses/`
+  CLI, Teams, BlueBubbles, activity transport, and inner-dialog orchestration.
+- `src/nerves/`
+  Structured runtime logging and coverage-audit infrastructure.
+- `src/__tests__/`
+  Test suite mirroring runtime domains.
 
-### Your runtime
+Other important top-level paths:
 
-**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.
+- `AdoptionSpecialist.ouro/`
+  Packaged specialist bundle used by `ouro hatch`.
+- `subagents/`
+  Source-of-truth workflow definitions for planner/doer/merger.
+- `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.
 
-**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.
+## Bundle Contract
 
-**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
+Every real agent lives in an external bundle:
 
-Plus 2 optional:
-- `onKick` -- self-correction triggered
-- `onConfirmAction` -- confirmation prompt for destructive tools
+`~/AgentBundles/<agent>.ouro/`
 
-**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.
+The canonical bundle shape is enforced by `src/mind/bundle-manifest.ts`. Important paths include:
 
-**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.
+- `agent.json`
+- `bundle-meta.json`
+- `psyche/SOUL.md`
+- `psyche/IDENTITY.md`
+- `psyche/LORE.md`
+- `psyche/TACIT.md`
+- `psyche/ASPIRATIONS.md`
+- `psyche/memory/`
+- `friends/`
+- `state/`
+- `tasks/`
+- `skills/`
+- `senses/`
+- `senses/teams/`
 
-**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.
+Task docs do not live in this repo anymore. Planning and doing docs live in the owning bundle under:
 
-**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).
+`~/AgentBundles/<agent>.ouro/tasks/one-shots/`
 
-- **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.
+## Runtime Truths
 
-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).
+- `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`.
+- 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.
+- Sense availability is explicit:
+  - `interactive`
+  - `disabled`
+  - `needs_config`
+  - `ready`
+  - `running`
+  - `error`
 
-**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`.
+## Quickstart
 
-**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.
+### Use The Published Runtime
 
-**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()`.
+For a clean smoke test, run from outside the repo:
 
-**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.
-
-**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.
-
-For Anthropic and OpenAI Codex auth bootstrap, use:
-
-- `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`.
+```bash
+cd ~
+npx ouro.bot -v
+npx ouro.bot up
+ouro -v
+ouro status
+```
 
-### What you can modify
+Expected shape:
 
-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.
+- `npx ouro.bot` and `ouro` report the same version.
+- `ouro status` shows the daemon overview plus discovered agents, senses, and workers.
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for repo workflow conventions (branching, commits, testing, task docs).
+### Work On The Harness
 
-## Running
+From the repo:
 
 ```bash
-# CLI (ouroboros agent)
-npm run dev
-
-# CLI (slugger agent, once slugger/ directory exists)
-npm run dev:slugger
+npm test
+npx tsc --noEmit
+npm run test:coverage
+```
 
-# Auth bootstrap (ouroboros defaults)
-npm run auth:claude-setup-token
-npm run auth:openai-codex
+If you are changing runtime code, keep all three green.
 
-# Auth bootstrap for another agent
-npm run auth:claude-setup-token -- --agent slugger
-npm run auth:openai-codex -- --agent slugger
+## Common Commands
 
-# Teams bot
-npm run teams
+```bash
+ouro up
+ouro status
+ouro logs
+ouro stop
+ouro hatch
+ouro chat <agent>
+ouro msg --to <agent> [--session <id>] [--task <ref>] <message>
+ouro poke <agent> --task <task-id>
+ouro link <agent> --friend <id> --provider <provider> --external-id <external-id>
+```
 
-# 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.
 
-# 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.