cluesmith · waleedkadous · Feb 25, 2026 · Feb 25, 2026 · Feb 25, 2026 · Feb 25, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -300,10 +300,10 @@ For detailed commands, configuration, and architecture, see:
 
 ### 🚨 ALWAYS Operate From the Main Workspace Root 🚨
 
-**ALL `af` commands (`af spawn`, `af send`, `af status`, `af dash`, `af cleanup`) MUST be run from the repository root on the `main` branch.**
+**ALL `af` commands (`af spawn`, `af send`, `af status`, `af workspace`, `af cleanup`) MUST be run from the repository root on the `main` branch.**
 
 - **NEVER** run `af spawn` from inside a builder worktree — builders will get nested inside that worktree, breaking everything
-- **NEVER** run `af dash start` from a worktree — there is no separate dashboard per worktree
+- **NEVER** run `af workspace start` from a worktree — there is no separate workspace per worktree
 - **NEVER** `cd` into a worktree to run af commands
 - The **only exception** is `porch` commands that need worktree context (e.g. `porch approve` from a builder's worktree)
 

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -300,10 +300,10 @@ For detailed commands, configuration, and architecture, see:
 
 ### 🚨 ALWAYS Operate From the Main Workspace Root 🚨
 
-**ALL `af` commands (`af spawn`, `af send`, `af status`, `af dash`, `af cleanup`) MUST be run from the repository root on the `main` branch.**
+**ALL `af` commands (`af spawn`, `af send`, `af status`, `af workspace`, `af cleanup`) MUST be run from the repository root on the `main` branch.**
 
 - **NEVER** run `af spawn` from inside a builder worktree — builders will get nested inside that worktree, breaking everything
-- **NEVER** run `af dash start` from a worktree — there is no separate dashboard per worktree
+- **NEVER** run `af workspace start` from a worktree — there is no separate workspace per worktree
 - **NEVER** `cd` into a worktree to run af commands
 - The **only exception** is `porch` commands that need worktree context (e.g. `porch approve` from a builder's worktree)
 

diff --git a/INSTALL.md b/INSTALL.md
@@ -441,18 +441,18 @@ Create `codev/config.json` to customize commands:
 
 Override via CLI:
 ```bash
-af dash start --architect-cmd "claude --model opus"
-af spawn --project 0003 --builder-cmd "claude"
+af workspace start --architect-cmd "claude --model opus"
+af spawn 3 --protocol spir --builder-cmd "claude"
 ```
 
 ### Quick Start
 
 ```bash
-# Start the architect dashboard
-af dash start
+# Start the workspace
+af workspace start
 
 # Spawn a builder for a spec
-af spawn --project 0003
+af spawn 3 --protocol spir
 
 # Check status of all builders
 af status
@@ -469,8 +469,8 @@ af cleanup --project 0003
 # Force cleanup (WARNING: may lose uncommitted work)
 af cleanup --project 0003 --force
 
-# Stop the architect and all builders
-af dash stop
+# Stop the workspace and all builders
+af workspace stop
 
 # Manage port allocations (for multi-project support)
 af ports list

diff --git a/MANIFESTO.md b/MANIFESTO.md
@@ -57,8 +57,8 @@ Protocols are sequences of steps to build something. Each protocol balances rigo
 Enables the Architect-Builder pattern with isolated execution environments:
 
 ```bash
-af dash start         # Launch the architect dashboard
-af spawn 3            # Create a builder for project 3
+af workspace start    # Launch the architect workspace
+af spawn 3 --protocol spir  # Create a builder for project 3
 af status             # See what everyone is doing
 af cleanup -p 3       # Clean up when done
 ```

diff --git a/README.md b/README.md
@@ -39,8 +39,8 @@ codev init
 # 3. Verify setup
 codev doctor
 
-# 4. Start the dashboard (optional)
-af dash start
+# 4. Start the workspace (optional)
+af workspace start
 ```
 
 Then tell your AI agent: *"I want to build X using the SPIR protocol"*
@@ -349,49 +349,30 @@ For parallel AI-assisted development, Codev includes the Architect-Builder patte
 ### Quick Start
 
 ```bash
-# Start the architect dashboard
-af dash start
+# Start the workspace
+af workspace start
 
 # Spawn a builder for a spec
-af spawn 3
+af spawn 3 --protocol spir
 
 # Check status
 af status
 
 # Stop everything
-af dash stop
+af workspace stop
 ```
 
 The `af` command is globally available after installing `@cluesmith/codev`.
 
 ### Remote Access
 
-Access Agent Farm from another device (iPad, laptop, etc.) via SSH tunnel:
+Access Agent Farm from any device via cloud connectivity:
 
 ```bash
-# Step 1: Start Agent Farm
-af dash start
-
-# Step 2: Get SSH command (shows your local IPs)
-af tunnel
-
-# Step 3: Run the SSH command on your remote device
-# Example output: ssh -L 4200:localhost:4200 youruser@192.168.1.50
-
-# Step 4: Open http://localhost:4200 in your remote browser
-```
-
-The dashboard and all terminals work identically via the tunnel. SSH handles authentication and encryption. (File tabs use separate ports and won't load through the tunnel.)
-
-**Note**: Requires SSH server on the dev machine. On Windows, enable OpenSSH Server or use WSL2.
-
-**Legacy mode** (not recommended):
-```bash
-# DEPRECATED: Exposes dashboard without authentication
-af dash start --allow-insecure-remote
+af tower connect
 ```
 
-See [CLI Reference](codev/resources/commands/agent-farm.md#remote-access) for full details.
+Register your tower with [codevos.ai](https://codevos.ai) for secure remote access from any browser — no SSH tunnels or port forwarding needed.
 
 ### Autonomous Builder Flags
 
@@ -431,7 +412,7 @@ See [CLI Reference](codev/resources/commands/agent-farm.md) for full documentati
 Codev has a **release protocol** (`codev/protocols/release/`) that automates the entire release process. To release a new version:
 
 ```
-Let's release v1.6.0
+Let's release v2.2.0
 ```
 
 The AI guides you through: pre-flight checks, maintenance cycle, E2E tests, version bump, release notes, GitHub release, and npm publish.
@@ -440,11 +421,11 @@ The AI guides you through: pre-flight checks, maintenance cycle, E2E tests, vers
 
 | Version Type | npm Tag | Example | Purpose |
 |--------------|---------|---------|---------|
-| Stable | `latest` | 1.6.0, 1.7.0 | Production-ready releases |
-| Release Candidate | `next` | 1.7.0-rc.1 | Pre-release testing (v1.7.0+) |
-| Patch | `latest` | 1.6.1 | Backported bug fixes |
+| Stable | `latest` | 2.1.1, 2.2.0 | Production-ready releases |
+| Release Candidate | `next` | 2.2.0-rc.1 | Pre-release testing |
+| Patch | `latest` | 2.1.2 | Backported bug fixes |
 
-Starting with v1.7.0, minor releases use release candidates (`npm install @cluesmith/codev@next`) for testing before stable release.
+Minor releases use release candidates (`npm install @cluesmith/codev@next`) for testing before stable release.
 
 Releases are named after great examples of architecture from around the world. See [Release Notes](docs/releases/) for version history.
 

diff --git a/codev/plans/558-comprehensive-documentation-up.md b/codev/plans/558-comprehensive-documentation-up.md
@@ -0,0 +1,68 @@
+# Plan: Comprehensive Documentation Update for HN Launch
+
+## Metadata
+- **Spec**: codev/specs/558-comprehensive-documentation-up.md
+- **Status**: draft
+- **Created**: 2026-02-25
+
+## Phase Overview
+
+| # | Phase | Objective | Status |
+|---|-------|-----------|--------|
+| 1 | Fix deprecated CLI commands | Replace all `af dash` with `af workspace`, fix `af spawn` syntax | pending |
+| 2 | Update README version refs and Remote Access | Fix stale version numbers, modernize remote access section | pending |
+| 3 | Expand FAQ and Cheatsheet | Add missing protocols, features, and CLI tools | pending |
+| 4 | Update tips.md and why.md | Fix stale commands in tips, verify references in why.md | pending |
+
+## Phase Details
+
+### Phase 1: Fix Deprecated CLI Commands
+
+**Objective**: Replace all deprecated `af dash` references with `af workspace` across all docs.
+
+**Files to modify**:
+- `README.md` — Lines using `af dash start`, `af dash stop`
+- `docs/tips.md` — Lines 119-130 using `af dash` in troubleshooting section
+
+**Changes**:
+- `af dash start` → `af workspace start`
+- `af dash stop` → `af workspace stop`
+- `af spawn 3` → `af spawn 3 --protocol spir` (add required --protocol flag)
+
+**Done when**: No `af dash` references remain in user-facing docs (excluding deprecation notices in agent-farm.md).
+
+### Phase 2: Update README Version References and Remote Access
+
+**Objective**: Fix stale version numbers and modernize the remote access section.
+
+**Files to modify**:
+- `README.md`
+
+**Changes**:
+- Update release example from `v1.6.0` to current-era version
+- Update versioning strategy text (remove "Starting with v1.7.0" phrasing)
+- Replace manual SSH tunnel section with `af workspace start --remote` approach
+- Ensure `af tunnel` reference is replaced or removed
+
+**Done when**: README reflects v2.x era and current remote access workflow.
+
+### Phase 3: Expand FAQ and Cheatsheet
+
+**Objective**: Add documentation for protocols and features missing from FAQ and cheatsheet.
+
+**Files to modify**:
+- `docs/faq.md` — Add sections on ASPIR, AIR, BUGFIX, porch orchestration
+- `codev/resources/cheatsheet.md` — Add ASPIR, BUGFIX to protocol table; add porch, tower to tools
+- `codev/resources/commands/overview.md` — Add porch to CLI summary if missing
+
+**Done when**: All current protocols and CLI tools are documented in reference materials.
+
+### Phase 4: Update tips.md and why.md
+
+**Objective**: Fix remaining stale content in tips and verify references in why.md.
+
+**Files to modify**:
+- `docs/tips.md` — Add tips for remote access, cross-workspace messaging, porch checks
+- `docs/why.md` — Verify "Claude Opus 4.1" model reference, verify "SP(IDE)R-SOLO" mention, verify "MCP support" reference
+
+**Done when**: All user-facing docs have accurate, current content.
diff --git a/codev/resources/cheatsheet.md b/codev/resources/cheatsheet.md
@@ -60,8 +60,10 @@ A **protocol** is a structured workflow that defines how work progresses from id
 
 | Protocol | Use For | Phases |
 |----------|---------|--------|
-| **SPIR** | New features | Specify → Plan → Implement → Review |
-| **AIR** | Small features (< 300 LOC) | Implement → Review |
+| **SPIR** | New features | Specify → Plan → Implement → Review (with human gates) |
+| **ASPIR** | Trusted features | Same as SPIR but no human gates on spec/plan |
+| **AIR** | Small features (< 300 LOC) | Implement → Review (no spec/plan artifacts) |
+| **BUGFIX** | Bug fixes from GitHub issues | Fix → Test → PR (minimal ceremony) |
 | **TICK** | Amendments to existing specs | Task Identification → Coding → Kickout |
 | **MAINTAIN** | Codebase hygiene | Dead code removal, documentation sync |
 | **EXPERIMENT** | Research & prototyping | Hypothesis → Experiment → Conclude |
@@ -123,6 +125,18 @@ Architect-Builder orchestration. Used by both **humans and agents**—agents use
 | `af shell` | Spawn a utility shell |
 | `af open <file>` | Open file in workspace viewer |
 | `af tower start` | Start cross-project tower |
+| `af tower connect` | Connect tower to codevos.ai for cloud access |
+
+### porch
+
+Protocol orchestrator. Drives SPIR/ASPIR/TICK/BUGFIX via a state machine. Used by **agents** (and humans for gate approvals).
+
+| Command | Description |
+|---------|-------------|
+| `porch status <id>` | Check project protocol status |
+| `porch run <id>` | Run next protocol phase |
+| `porch approve <id> <gate>` | Approve a human gate (human only) |
+| `porch pending` | List all pending gates |
 
 ### consult
 

diff --git a/codev/resources/commands/overview.md b/codev/resources/commands/overview.md
@@ -1,11 +1,12 @@
 # Codev CLI Command Reference
 
-Codev provides three CLI tools for AI-assisted software development:
+Codev provides four CLI tools for AI-assisted software development:
 
 | Tool | Description |
 |------|-------------|
 | `codev` | Project setup, maintenance, and framework commands |
 | `af` | Agent Farm - multi-agent orchestration for development |
+| `porch` | Protocol orchestrator - drives SPIR/ASPIR/TICK/BUGFIX state machines |
 | `consult` | AI consultation with external models (Gemini, Codex, Claude) |
 
 ## Quick Start
@@ -33,7 +34,7 @@ consult -m gemini --protocol spir --type spec
 npm install -g @cluesmith/codev
 ```
 
-This installs all three commands globally: `codev`, `af`, and `consult`.
+This installs all four commands globally: `codev`, `af`, `porch`, and `consult`.
 
 ## Command Summaries
 
@@ -65,6 +66,17 @@ See [codev.md](codev.md) for full documentation.
 
 See [agent-farm.md](agent-farm.md) for full documentation.
 
+### porch - Protocol Orchestrator
+
+| Command | Description |
+|---------|-------------|
+| `porch status <id>` | Show project protocol status |
+| `porch run <id>` | Run the next protocol phase |
+| `porch approve <id> <gate>` | Approve a human gate |
+| `porch pending` | List all pending gates across projects |
+
+Porch drives SPIR, ASPIR, TICK, and BUGFIX protocols via a state machine. It's used automatically by `af spawn` (strict mode) or manually by builders (soft mode).
+
 ### consult - AI Consultation
 
 | Command | Description |

diff --git a/codev/reviews/558-comprehensive-documentation-up.md b/codev/reviews/558-comprehensive-documentation-up.md
@@ -0,0 +1,50 @@
+# Review: Comprehensive Documentation Update for HN Launch
+
+## Metadata
+- **Spec**: codev/specs/558-comprehensive-documentation-up.md
+- **Plan**: codev/plans/558-comprehensive-documentation-up.md
+- **Issue**: #558
+- **Date**: 2026-02-25
+
+## Summary
+
+Documentation-only update across 8 files to fix deprecated CLI syntax, add missing protocol/feature documentation, and modernize stale references in preparation for HN launch.
+
+## Changes Made
+
+### Phase 1: Fix Deprecated CLI Commands
+- Replaced all `af dash` with `af workspace` in README.md, docs/tips.md, AGENTS.md, CLAUDE.md, MANIFESTO.md, INSTALL.md
+- Added required `--protocol` flag to `af spawn` examples
+- Verified AGENTS.md/CLAUDE.md remain byte-identical
+
+### Phase 2: Update README Version References
+- Updated version examples from v1.6.0/v1.7.0 era to v2.x era
+- Replaced manual SSH tunnel Remote Access section with `af workspace start --remote`
+- Updated versioning strategy table
+
+### Phase 3: Expand FAQ and Cheatsheet
+- Added 4 new FAQ sections: protocol overview, porch explanation, Agent Farm optionality, remote access
+- Added ASPIR and BUGFIX protocols to cheatsheet protocol table
+- Added porch CLI to cheatsheet tools reference
+- Added porch as fourth CLI tool in commands/overview.md with command summary
+
+### Phase 4: Update tips.md and why.md
+- Added tips for remote access, cross-workspace messaging, and non-Node.js porch checks
+- Fixed stale "SP(IDE)R-SOLO" and "MCP support" references in why.md
+
+## What Went Well
+- Systematic file-by-file audit caught all deprecated `af dash` references
+- Changes were minimal and focused — no unnecessary rewrites
+- All docs remain internally consistent
+
+## What Was Challenging
+- PR consultations failed because no PR existed yet (chicken-and-egg)
+- Balancing between updating historical references (like model names in case studies) vs keeping them accurate as historical records
+
+## Lessons Learned
+- Documentation-only PRs benefit from creating the PR first, then running consultations on the actual diff
+- The `af dash` → `af workspace` deprecation wasn't fully propagated through docs when the rename happened — future renames should include a doc-sweep step
+
+## Methodology Notes
+- ASPIR was appropriate for this scope — no spec/plan gates needed for a documentation refresh
+- Consultations on the spec ran but output went to stdout (not captured) — consider `--output` flag for background consultations