docs: refocus README on team outcomes and move deep details to docs/ (#60)

Author: benvinegar

AGENTS.md

@@ -150,7 +150,7 @@ Add new test files to `bin/test.sh` — don't scatter test invocations across CI
 - Extensions are deployed from `pi/extensions/` → agent's `~/.pi/agent/extensions/`.
 - Skills are deployed from `pi/skills/` → agent's `~/.pi/agent/skills/`.
 - Agent commits operational learnings to its own skills dir (not back to source).
-- **When changing behavior, update all docs.** Check and update: `README.md`, `CONFIGURATION.md`, skill files (`pi/skills/*/SKILL.md`), and `AGENTS.md`. Inline code examples in docs must match the actual implementation.
+- **When changing behavior, update all docs.** Check and update: `README.md`, relevant pages in `docs/`, `CONFIGURATION.md`, skill files (`pi/skills/*/SKILL.md`), and `AGENTS.md`. Inline code examples in docs must match the actual implementation.
 - **No distro-specific commands.** Scripts must work on both Arch and Ubuntu (and any standard Linux). Use `grep -E` (not `grep -P`), POSIX-compatible tools, and avoid package manager calls (`pacman`, `apt`, etc.). If a package is needed, document it as a prerequisite rather than auto-installing it.
 
 ## Testing on Droplets

CONTRIBUTING.md

@@ -7,10 +7,17 @@ git clone https://github.com/modem-dev/baudbot.git ~/baudbot
 npm install
 ```
 
+## Documentation map
+
+- Product/team workflow overview: [README.md](README.md)
+- Deep architecture and operations docs: [`docs/`](docs)
+- Security model: [SECURITY.md](SECURITY.md)
+- Configuration reference: [CONFIGURATION.md](CONFIGURATION.md)
+
 ## Running Tests
 
 ```bash
-# All tests (8 suites)
+# All tests (10 suites)
 bin/test.sh
 
 # JS/TS only

README.md

@@ -1,5 +1,7 @@
 # Security
 
+For product overview and team workflow context, start with [README.md](README.md). For architecture and operations docs, see [`docs/architecture.md`](docs/architecture.md) and [`docs/operations.md`](docs/operations.md).
+
 ## Architecture: Source / Runtime Separation
 
 ```

SECURITY.md

@@ -0,0 +1,79 @@
+# Agents
+
+Baudbot uses a small multi-agent architecture: one persistent orchestrator and task-scoped workers. This keeps the team-facing interface stable while allowing parallel execution in the background.
+
+## Role overview
+
+| Agent | Lifecycle | Primary responsibility |
+|------|-----------|------------------------|
+| `control-agent` | Persistent | Intake, triage, delegation, user communication, orchestration |
+| `dev-agent` | Ephemeral per task | Code changes, tests, PRs, CI/review iteration |
+| `sentry-agent` | Persistent/on-demand | Sentry alert triage and investigation support |
+
+## Control-agent
+
+The control-agent is the team-facing coordinator.
+
+Responsibilities:
+
+- monitor inbound requests (Slack/email)
+- create and manage todos
+- select target repo(s)
+- spawn and supervise dev-agent sessions
+- relay progress/results to users
+- enforce operational guardrails (cleanup, escalation)
+
+It should remain lightweight on coding itself and focus on orchestration quality.
+
+## Dev-agent
+
+The dev-agent is a coding worker launched in a dedicated git worktree for each task.
+
+Responsibilities:
+
+- read project guidance (`CODEX.md`, `AGENTS.md`, `CLAUDE.md` as available)
+- implement requested changes
+- run tests/build checks
+- open PR and monitor CI
+- fix failures and address review comments
+- report completion details back to control-agent
+
+Each dev-agent is task-scoped and should exit when work is done.
+
+## Sentry-agent
+
+The sentry-agent handles incident-oriented analysis.
+
+Responsibilities:
+
+- investigate Sentry issues by issue ID
+- summarize likely impact and root cause
+- provide actionable recommendations for fixes
+- hand off coding tasks to dev-agent through control-agent
+
+## Session model
+
+- Control and sentry sessions are long-lived.
+- Dev sessions are ephemeral and tied to todos.
+- Session-control sockets allow inter-agent messaging (`send_to_session`).
+- Naming conventions encode role and task context (for observability and cleanup).
+
+## Concurrency
+
+Baudbot limits concurrent dev agents to keep resource usage predictable and avoid context thrash.
+
+Use this model when scaling:
+
+- keep a fixed max active dev-agent count
+- queue additional tasks
+- prioritize by urgency or user/channel policy
+
+## Communication contract
+
+- **Users talk to control-agent**
+- **Dev-agent reports to control-agent**
+- **Control-agent reports back to users**
+
+This keeps the external interface stable while allowing internal execution strategies to evolve.
+
+For flow details, see [team-workflow.md](team-workflow.md).

docs/agents.md

@@ -0,0 +1,62 @@
+# Architecture
+
+Baudbot separates admin-owned source from agent-owned runtime to reduce blast radius while still enabling always-on autonomous execution.
+
+## Source / release / runtime layout
+
+```text
+admin user
+├── ~/baudbot/                     # source repo (admin-owned)
+│   ├── bin/
+│   ├── pi/extensions/
+│   ├── pi/skills/
+│   └── slack-bridge/
+
+root-managed releases
+├── /opt/baudbot/
+│   ├── releases/<sha>/            # immutable, git-free snapshots
+│   ├── current -> releases/<sha>
+│   └── previous -> releases/<sha>
+
+baudbot_agent user
+├── ~/runtime/                     # deployed runtime used by live agent
+├── ~/.pi/agent/                   # skills/extensions/memory/manifests
+└── ~/workspace/                   # project repos + task worktrees
+```
+
+## Deployment flow
+
+1. Admin updates source repo.
+2. Deploy/update scripts build a staged snapshot.
+3. Snapshot is published to `/opt/baudbot/releases/<sha>`.
+4. Runtime files are deployed for `baudbot_agent`.
+5. Symlink switch (`current`) is updated atomically on success.
+
+This allows reproducible releases and fast rollback.
+
+## Agent topology
+
+```text
+control-agent (persistent)
+├── sentry-agent (persistent/on-demand)
+└── dev-agent-* (ephemeral task workers)
+```
+
+Inter-session communication is handled over pi session-control sockets.
+
+## Data path summary
+
+```text
+Slack/Email → bridge + wrapping → control-agent
+            → todo + delegation → dev-agent worktree execution
+            → PR/CI outcomes → control-agent response in source thread
+```
+
+## Why this architecture
+
+- clear trust boundaries between admin and agent runtime
+- predictable operations for deploy/update/rollback
+- support for concurrent, task-scoped coding workers
+- safer enablement of high-privilege tools via layered controls
+
+For security controls and known risks, see [../SECURITY.md](../SECURITY.md).

docs/architecture.md

@@ -0,0 +1,58 @@
+# Linux Runtime
+
+Baudbot is designed to run as Linux-native infrastructure, not a browser-only assistant, so it can execute against your real stack instead of a simulated environment.
+
+## Execution model
+
+- runs as unprivileged `baudbot_agent` user
+- operates in real filesystem workspaces and git worktrees
+- executes shell commands, test suites, and build pipelines directly
+- supports container workflows via guarded Docker wrapper
+
+## What this enables for teams
+
+- run actual project commands (lint/test/build/migrate)
+- validate fixes against real local/runtime dependencies
+- automate browser tasks through cloud browser tooling
+- handle long-running operational loops in tmux/systemd
+
+## Docker support
+
+Agents must use:
+
+```bash
+sudo /usr/local/bin/baudbot-docker
+```
+
+This wrapper blocks common privilege-escalation patterns (for example, privileged mode and unsafe host mounts).
+
+## Process and workspace model
+
+```text
+/home/baudbot_agent/
+├── runtime/           # deployed runtime files
+├── .pi/agent/         # extensions, skills, memory, manifests
+└── workspace/         # repos + git worktrees used by dev agents
+```
+
+Dev agents work inside `~/workspace/worktrees/<branch>` and should not commit directly from base repo checkouts.
+
+## Platform support
+
+Validated in CI against:
+
+- Ubuntu 24.04
+- Arch Linux
+
+Baudbot scripts aim to remain distro-agnostic across standard Linux environments.
+
+## Operational boundaries
+
+Linux-native does not mean unrestricted root access:
+
+- no general sudo for agents
+- security-critical files are read-only at runtime
+- network controls can restrict outbound traffic
+- source/runtime separation limits self-tampering blast radius
+
+See [SECURITY.md](../SECURITY.md) for threat model details.

docs/linux-runtime.md

@@ -0,0 +1,64 @@
+# Persistent Memory
+
+Baudbot uses file-based memory so context survives session restarts and knowledge compounds at the team level.
+
+## Memory location
+
+Memory files live in the deployed runtime under:
+
+```text
+~/.pi/agent/memory/
+```
+
+Typical files:
+
+- `operational.md` — infra learnings and recurring fixes
+- `repos.md` — per-repo build/CI quirks and notes
+- `users.md` — collaboration preferences and communication style
+- `incidents.md` — prior incidents, root cause, and resolution
+
+## Why it matters
+
+Persistent memory lets the system improve over time:
+
+- fewer repeated mistakes
+- faster triage for recurring failures
+- better continuity across restarts or model/session swaps
+
+## Operating rules
+
+- Read memory on startup before executing new work.
+- Append new learnings with dated entries.
+- Keep entries concrete and action-oriented.
+- Never store secrets, API keys, tokens, or private credentials.
+
+## Entry format (example)
+
+```markdown
+## 2026-02-18
+- Repo: myapp
+- Finding: integration tests fail unless REDIS_URL is set explicitly in CI.
+- Fix: export REDIS_URL=redis://127.0.0.1:6379 before running test:integration.
+```
+
+## What belongs in memory vs git docs
+
+Use memory for:
+
+- runtime observations
+- team preferences
+- temporary but useful operational context
+
+Use repository docs/commits for:
+
+- canonical architecture
+- long-term implementation docs
+- user-facing product behavior changes
+
+## Maintenance
+
+- prune stale or duplicated notes periodically
+- keep headings consistent for scanability
+- consolidate repeated points into single authoritative entries
+
+For role behavior around memory usage, see [agents.md](agents.md).