docs: refresh README and align documentation with current runtime (#112)

Author: benvinegar

AGENTS.md

@@ -18,7 +18,7 @@ bin/                        security & operations scripts
   scan-extensions.mjs       extension static analysis
   redact-logs.sh            secret scrubber for session logs
   prune-session-logs.sh     retention cleanup for old pi session logs
-  config.sh                 env var validation helper
+  config.sh                 interactive secrets/config setup
   broker-register.mjs       Slack broker workspace registration CLI
   doctor.sh                 system health checks
   uninstall.sh              clean removal of baudbot
@@ -30,9 +30,12 @@ bin/                        security & operations scripts
     setup-ubuntu.sh         Ubuntu droplet: prereqs + setup + tests
     setup-arch.sh           Arch Linux droplet: prereqs + setup + tests
   lib/                      shared shell helpers sourced by CLI/release scripts
-    baudbot-runtime.sh      runtime/status/session/attach helper module for bin/baudbot
+    shell-common.sh         strict mode + shared logging/error/root-check helpers
     release-common.sh       shared update/rollback helpers
+    deploy-common.sh        deploy/runtime helper functions
+    doctor-common.sh        doctor status/check formatting helpers
     json-common.sh          shared JSON field extraction helper (jq)
+    baudbot-runtime.sh      runtime/status/session/attach helper module for bin/baudbot
 hooks/
   pre-commit                blocks agent from modifying security files in git
 pi/
@@ -42,7 +45,7 @@ pi/
     heartbeat.ts            periodic health check loop
     auto-name.ts            session naming
     control.ts              inter-session communication
-    idle-compact.ts         compact context during idle periods (40% threshold)
+    idle-compact.ts         compact context during idle periods (default 25% threshold)
     ...
   skills/                   source of truth for agent skill templates
     control-agent/          orchestration agent
@@ -66,7 +69,7 @@ See [CONFIGURATION.md](CONFIGURATION.md) for all env vars and how to obtain them
 
 ## Architecture: Source / Runtime Separation
 
-The admin owns source checkouts (for example `~/baudbot/`). The agent (`baudbot_agent` user) owns runtime state. The agent **cannot read the source repo** — admin home is `700`.
+Live execution is release/runtime-based (`/opt/baudbot` + `baudbot_agent` runtime).
 
 Live operations are now release-based under `/opt/baudbot` (git-free):
 
@@ -109,12 +112,12 @@ Agent runtime layout:
 
 ```bash
 # First-time install (interactive — handles everything)
-sudo ~/baudbot/install.sh
+sudo ./install.sh
 
-# Edit source files directly in ~/baudbot/
+# Edit source files in this repository checkout
 
 # For source-only changes (extensions/skills/bridge), deploy directly:
-~/baudbot/bin/deploy.sh
+./bin/deploy.sh
 
 # For operational updates from git (recommended for live bot):
 sudo baudbot update

SECURITY.md

@@ -2,31 +2,24 @@
 
 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
-
-```
-~/baudbot/                              ← READ-ONLY source repo (admin-managed)
-  ├── pi/extensions/                   ← source of truth for extensions
-  ├── pi/skills/                       ← source of truth for skill templates
-  ├── bin/                             ← admin scripts (deploy.sh, audit, firewall)
-  └── slack-bridge/                    ← source of truth for bridge
-
-~/.pi/agent/
-  ├── extensions/                      ← DEPLOYED copies (real dir, not symlink)
-  │   ├── tool-guard.ts               ← security-critical (deployed by admin)
-  │   ├── auto-name.ts                ← agent-modifiable
-  │   └── ...
-  └── skills/                          ← agent-owned (agent updates freely)
-
-~/runtime/
-  └── slack-bridge/                    ← DEPLOYED copy (bridge runs from here)
-      ├── bridge.mjs                   ← agent-modifiable
-      ├── security.mjs                 ← security-critical (deployed by admin)
-      └── node_modules/
+## Architecture: Release / Runtime Separation
+
+```text
+root-managed releases
+├── /opt/baudbot/releases/<sha>/       # immutable, git-free snapshots
+├── /opt/baudbot/current -> <sha>
+└── /opt/baudbot/previous -> <sha>
+
+agent runtime (baudbot_agent)
+├── ~/runtime/                         # launcher + bridge + runtime scripts
+├── ~/.pi/agent/                       # deployed extensions/skills + memory + manifests
+└── ~/workspace/                       # repos + task worktrees
 ```
 
-The agent runs from deployed copies, never from the source repo directly.
-Admin edits source → runs `bin/deploy.sh` → copies to runtime with correct permissions.
+Live execution runs from deployed/runtime copies.
+`baudbot update` publishes a snapshot, deploys runtime files, validates health, then atomically flips `current`.
+
+Live execution runs from release snapshots under `/opt/baudbot`.
 
 ## Trust Boundaries
 
@@ -48,8 +41,8 @@ Admin edits source → runs `bin/deploy.sh` → copies to runtime with correct p
 ┌─────────────────────────────────────────────────────────────────┐
 │               BOUNDARY 2: OS User Isolation                      │
 │   baudbot_agent (uid 1001) — separate home, no sudo              │
-│   Cannot read admin home directory (admin home is 700)           │
-│   Source repo ~/baudbot/ is read-only (permissions first, tool-guard backup) │
+│   In default hardened installs, admin home is not readable by agent (typically mode 700) │
+│   Runtime executes from release snapshots under /opt/baudbot              │
 │   Docker only via wrapper (blocks --privileged, host mounts)     │
 └──────────────────────────────┬──────────────────────────────────┘
                                │
@@ -66,14 +59,13 @@ Admin edits source → runs `bin/deploy.sh` → copies to runtime with correct p
 
 | Layer | What | Bypassed by |
 |-------|------|-------------|
-| **Read-only source** | ~/baudbot/ lives under admin home (700 perms) — agent has zero access. Optional bind mount for defense-in-depth (not applied by default). | Root access |
+| **Immutable releases** | Runtime deploys from git-free snapshots under `/opt/baudbot/releases/<sha>`, reducing direct source-tampering risk during live execution. | Root access |
 | **File permissions** | Security-critical runtime files deployed `chmod a-w` by deploy.sh. Hard OS-level boundary — blocks `sed`, `python`, any write mechanism. | Root access or `chmod u+w` (which tool-guard blocks) |
 | **Tool-guard rules** | Policy/guidance layer: blocks many high-risk Edit/Write/bash patterns and returns safety-interruption reasoning. Not a hard sandbox; novel command patterns may bypass it. | Novel bypass patterns; rely on OS file perms + runtime hardening for hard boundaries |
 | **Integrity checks** | security-audit.sh compares runtime file hashes against deploy manifest | None (detection, not prevention) |
-| **Pre-commit hook** | Blocks git commit of protected files in source repo | --no-verify (root-owned hook) |
+| **Pre-commit hook** | Blocks git commit of protected files in the repository | --no-verify (root-owned hook) |
 
-The read-only source repo is the primary defense. Even if the agent modifies runtime copies,
-the admin can re-deploy from the untampered source at any time.
+Primary hard boundaries are runtime permissions, user isolation, and release-based deployment. If local source isolation is also enforced, admin can re-deploy from source to restore expected state.
 
 ## User Model
 
@@ -84,21 +76,18 @@ the admin can re-deploy from the untampered source at any time.
 
 **Admin → baudbot_agent access**: The admin user is in the `baudbot_agent` group and has `NOPASSWD: ALL` as baudbot_agent via sudo. This is intentional for management. Run `bin/harden-permissions.sh` to ensure pi state files are owner-only (prevents passive group-level reads).
 
-**baudbot_agent → admin access**: None. Admin home is `700`, baudbot_agent is not in the admin user's group.
+**baudbot_agent → admin access**: Expected to be none in default installs. This depends on host permissions (for example, admin home mode and group membership) remaining hardened.
 
 ## Data Flows
 
-```
-Slack @mention
-  → slack-bridge (Socket Mode, admin user)
+```text
+Slack message (Socket Mode or broker pull mode)
+  → bridge process (runs in baudbot_agent runtime)
     → content wrapping (security boundaries added)
-      → Unix socket (~/.pi/session-control/*.sock)
-        → control-agent (pi session, baudbot_agent user)
-          → creates todo
-          → delegates to dev-agent (pi session, baudbot_agent user)
-            → git worktree → code changes → git push
-          → dev-agent reports back
-        → control-agent replies via curl → bridge HTTP API (127.0.0.1:7890)
+      → control-agent (pi session)
+        → creates todo + delegates to dev-agent in worktree
+          → code/test/PR/CI loop
+        → control-agent posts status via bridge local API (127.0.0.1:7890)
       → Slack thread reply
 ```
 
@@ -112,18 +101,21 @@ Slack @mention
 | `KERNEL_API_KEY` | `~/.config/.env` | `600` | Kernel cloud browsers |
 | `BAUDBOT_SECRET` | `~/.config/.env` | `600` | Email authentication shared secret |
 | SSH key | `~/.ssh/id_ed25519` | `600` | Git push (agent GitHub account) |
-| `SLACK_BOT_TOKEN` | Bridge `.env` | `600` | Slack bot OAuth token |
-| `SLACK_APP_TOKEN` | Bridge `.env` | `600` | Slack Socket Mode token |
+| `SLACK_BOT_TOKEN` | `~/.config/.env` | `600` | Slack bot OAuth token |
+| `SLACK_APP_TOKEN` | `~/.config/.env` | `600` | Slack Socket Mode token |
+| `SLACK_BROKER_*` keys | `~/.config/.env` | `600` | Broker pull-mode encryption/signing + workspace linkage |
 
 ## Deploy Workflow
 
 ```bash
-# Admin edits source files in ~/baudbot/
-# Then deploys to runtime:
-~/baudbot/bin/deploy.sh
+# Source-only changes from local checkout
+sudo baudbot deploy
+
+# Operational update from git (recommended for live bot)
+sudo baudbot update
 
-# If bridge is running, restart it:
-sudo -u baudbot_agent bash -c 'cd ~/runtime/slack-bridge && node bridge.mjs'
+# Roll back if needed
+sudo baudbot rollback previous
 ```
 
 ## Known Risks

bin/deploy.sh

@@ -5,7 +5,7 @@
 #   ~/baudbot/bin/deploy.sh
 #   ~/baudbot/bin/deploy.sh --dry-run
 #
-# The source repo lives in the admin's home (agent can't read it).
+# In default hardened installs, source lives in admin-owned paths not readable by the agent.
 # This script stages files to a temp dir, then uses sudo -u baudbot_agent
 # to install them into the agent's runtime directories. It also stamps
 # a version file + hash manifest so the agent can verify integrity

docs/architecture.md

@@ -1,17 +1,10 @@
 # Architecture
 
-Baudbot separates admin-owned source from agent-owned runtime to reduce blast radius while still enabling always-on autonomous execution.
+Baudbot runs live operations from release snapshots under `/opt/baudbot`, with an agent-owned runtime under `/home/baudbot_agent`.
 
-## Source / release / runtime layout
+## Release / runtime layout (production)
 
 ```text
-admin user
-├── ~/baudbot/                     # source repo (admin-owned)
-│   ├── bin/
-│   ├── pi/extensions/
-│   ├── pi/skills/
-│   └── slack-bridge/              # Slack integration (Socket Mode + broker pull mode)
-
 root-managed releases
 ├── /opt/baudbot/
 │   ├── releases/<sha>/            # immutable, git-free snapshots
@@ -24,9 +17,13 @@ baudbot_agent user
 └── ~/workspace/                   # project repos + task worktrees
 ```
 
+## Deployment source vs live runtime
+
+`baudbot update` publishes a git-free snapshot into `/opt/baudbot/releases/<sha>` and runs live execution from that release path.
+
 ## Deployment flow
 
-1. Admin updates source repo.
+1. Update is initiated from a target ref/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`.

docs/operations.md

@@ -78,20 +78,27 @@ sudo baudbot doctor
 sudo baudbot audit
 
 # Deep audit (extension scanner + extra checks)
-~/baudbot/bin/security-audit.sh --deep
+sudo baudbot audit --deep
 ```
 
 ## Test commands
 
 ```bash
 # Full test suite
-bin/test.sh
+npm test
 
 # JS/TS only
-bin/test.sh js
+npm run test:js
 
-# Shell only
-bin/test.sh shell
+# Shell/security-script suites
+npm run test:shell
+
+# Coverage
+npm run test:coverage
+
+# Lint + typecheck
+npm run lint
+npm run typecheck
 ```
 
 ## Common runbook actions

setup.sh

@@ -218,7 +218,7 @@ fi
 
 echo "=== Setting up runtime directories ==="
 # The agent runs from deployed copies, not from the source repo directly.
-# Source: ~/baudbot/ (read-only to agent)
+# Source: ~/baudbot/ (typically not readable by agent in hardened default installs)
 # Runtime: ~/.pi/agent/extensions/, ~/.pi/agent/skills/, ~/runtime/slack-bridge/
 sudo -u baudbot_agent bash -c '
   mkdir -p ~/.pi/agent/extensions