fix(multi-repo): address review feedback on PR #974

Bundles six review fixes:

- TUI strict-mode: add 'p' to the bare-lowercase blocklist so the new
  Projects dialog does not bypass the strict-mode contract. In strict
  mode, reach Projects via the command palette.
- TUI discoverability: add ("p", "Projects") to the help overlay
  (non-strict) and a "projects" entry to the command palette so the
  feature is reachable from `?` and Ctrl+K. Bumped help DIALOG_HEIGHT
  43 -> 44 to fit the extra row.
- Web API: introduce typed RegistryError (Conflict / NotFound / Other)
  in projects::add and projects::remove. Server now returns 409 only
  on conflicts and 500 on I/O errors; delete returns 404 only on
  missing entries. CLI and TUI callers compile unchanged via
  Into<anyhow::Error>.
- Refactor: extract apply_picked_project() and open_projects_picker()
  out of handle_worktree_config_key, drop the
  #[allow(clippy::too_many_lines)].
- Docs: add docs/guides/multi-repo-workspaces.md with the full user
  story (registry, scopes, CLI/TUI/web flows, limitations). Wire it
  into website sync-docs PAGES, URL_MAP, and docsNav.
- E2E: add tests/e2e/project_registry.rs with six tests covering
  add/list/remove round-trip, JSON output, non-git rejection,
  duplicate-within-scope, cross-scope override, --project requires
  --worktree, and unknown --project name fast-fail.

Verified: cargo fmt, cargo clippy --all-targets --features serve,
cargo test --features serve --lib (1604 pass), cargo test --test e2e
project_registry (6 pass), web/tsc --noEmit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: njbrake

docs/guides/multi-repo-workspaces.md

@@ -0,0 +1,137 @@
+# Multi-Repo Workspaces
+
+Run a single AoE session across several git repositories at once. Each repo gets its own worktree on a shared branch name, all rooted under one workspace directory, attached to one tmux session.
+
+Use this when a unit of work, a feature, a bug fix, an investigation, touches more than one repo and you want one agent driving all of them, not N agents you have to mentally reconcile.
+
+## When to Use
+
+| Scenario | Multi-repo? |
+|---|---|
+| Bug spans backend and frontend repos | Yes |
+| Refactor across an OSS core and a private wrapper | Yes |
+| Feature limited to a single repo | No, regular session |
+| Investigating logs that touch many repos | Yes, agent picks the relevant ones |
+| OSS core is pinned and rarely changes | Use [`on_create` hooks](repo-config.md) instead |
+
+## Quick Start
+
+### 1. Register your repos once
+
+```bash
+aoe project add /path/to/backend
+aoe project add /path/to/frontend
+aoe project add /path/to/shared-lib
+```
+
+`aoe project list` shows what is registered.
+
+### 2. Start a multi-repo session
+
+CLI:
+
+```bash
+aoe add /path/to/backend \
+  --project frontend \
+  --project shared-lib \
+  -w feat/auth-rewrite -b
+```
+
+TUI: open the new-session dialog (`n`), enter the worktree branch, focus the **Extra Repos** field, press `Ctrl+R`, and pick the registered projects you want to include.
+
+Web: `+ New session`, pick a primary repo, then click registered projects in the **Extra repos** picker (or paste a path with the free-text input).
+
+### 3. The agent sees one workspace
+
+The session starts in the workspace root with all the worktrees as siblings:
+
+```
+~/aoe-workspaces/feat-auth-rewrite/
+├── backend/      ← branch feat/auth-rewrite
+├── frontend/     ← branch feat/auth-rewrite
+└── shared-lib/   ← branch feat/auth-rewrite
+```
+
+The agent navigates between them like any normal multi-repo working tree. Use `cd` and standard git commands; AoE does not impose any cross-repo orchestration.
+
+## The Project Registry
+
+Saved repo paths the multi-repo pickers draw from. Two scopes:
+
+| Scope | File | Visibility |
+|---|---|---|
+| Global | `<app_dir>/projects.json` | Every profile |
+| Profile | `<app_dir>/profiles/{profile}/projects.json` | Only that profile |
+
+`<app_dir>` is `$XDG_CONFIG_HOME/agent-of-empires/` on Linux, `~/.agent-of-empires/` on macOS.
+
+When both scopes hold the same canonical path, the **profile entry wins** in merged views (this is how `--allow-override` is meant to be used: stage a profile-specific name on top of a global default).
+
+### Default scope
+
+| Invocation | Default scope |
+|---|---|
+| `aoe project add <path>` | Global |
+| `aoe -p <profile> project add <path>` | Profile |
+
+Pass `--scope global` or `--scope profile` to override.
+
+### Cross-scope collisions
+
+```bash
+aoe project add /repo/foo                     # global
+aoe -p other project add /repo/foo            # ERROR: same path in global scope
+aoe -p other project add /repo/foo --allow-override  # OK, profile shadows global
+```
+
+## CLI Reference
+
+```bash
+# List
+aoe project list                       # merged (global + active profile)
+aoe project list --scope global        # globals only
+aoe project list --scope profile       # active profile only
+aoe project list --json                # machine-readable
+
+# Add
+aoe project add /path/to/repo                          # global, name = basename
+aoe project add /path/to/repo --name shortname        # custom display name
+aoe project add /path/to/repo --scope profile         # profile-only
+aoe project add /path/to/repo --allow-override        # shadow other-scope entry
+
+# Remove
+aoe project remove backend                # by name (case-insensitive)
+aoe project remove /path/to/repo          # by canonical path
+aoe project remove backend --scope profile
+
+# Use in a session
+aoe add /path/to/primary --project name1 --project name2 -w branch -b
+aoe add /path/to/primary --repo /literal/path --project registered -w branch -b
+```
+
+`--repo` and `--project` may be mixed; the union is passed to the workspace builder. The builder rejects duplicate repo names, so the same repo via two paths is a hard error.
+
+`aoe list --json` includes a `workspace_repos` array for each session; the array is empty for single-repo sessions.
+
+## Web Dashboard
+
+The Projects page (folder icon in the sidebar footer) is full CRUD over the registry: add, remove, switch scope, opt into `allow_override`. Read-only servers (`aoe serve --read-only`) hide the destructive controls.
+
+The new-session wizard surfaces the registry as toggleable chips on the Project step. The free-text input still works for paths that aren't registered.
+
+Multi-repo sessions are bucketed into a single **Multi-repo** group at the bottom of the sidebar, regardless of which repo was chosen as the primary. Each session row shows a chip per repo under the title.
+
+## Limitations
+
+These are out of scope for the current release; tracked separately:
+
+- **One branch name per workspace**: every repo gets the same `-w <branch>` value. Per-repo branch names is a future feature.
+- **No agent-driven repo pull-in mid-session**: if the agent realizes it needs another repo, you have to start a new session. Tracked alongside the orchestrator work.
+- **No saved workspace templates** ("named bundles of repos"): each session picks the set fresh. If your bundle is fixed, register the repos and select them all from the picker.
+- **No per-repo PR tracking**: AoE does not track PRs today. Coordinated PR workflow happens outside AoE.
+
+## Related
+
+- [Worktrees Reference](worktrees.md) — how the per-repo worktrees are created.
+- [Repository Configuration & Hooks](repo-config.md) — `on_create` hooks for fixed sibling repos that don't need a registry entry.
+- [CLI Reference](../cli/reference.md) — full `aoe project` and `aoe add --project` flag listing.

src/server/api/projects.rs

@@ -12,7 +12,7 @@ use axum::{
 use serde::{Deserialize, Serialize};
 
 use crate::git::GitWorktree;
-use crate::session::projects;
+use crate::session::projects::{self, RegistryError};
 use crate::session::{Project, ProjectScope};
 
 use super::AppState;
@@ -143,8 +143,18 @@ pub async fn create_project(
     let project = Project::new(name, canonical.to_string_lossy(), scope);
     match projects::add(&state.profile, scope, project, body.allow_override) {
         Ok(saved) => (StatusCode::CREATED, Json(ProjectResponse::from(saved))).into_response(),
-        Err(e) => (
+        Err(RegistryError::Conflict(msg)) => (
             StatusCode::CONFLICT,
+            Json(serde_json::json!({"error": "conflict", "message": msg})),
+        )
+            .into_response(),
+        Err(RegistryError::NotFound(msg)) => (
+            StatusCode::NOT_FOUND,
+            Json(serde_json::json!({"error": "not_found", "message": msg})),
+        )
+            .into_response(),
+        Err(RegistryError::Other(e)) => (
+            StatusCode::INTERNAL_SERVER_ERROR,
             Json(serde_json::json!({"error": "add_failed", "message": e.to_string()})),
         )
             .into_response(),
@@ -190,9 +200,19 @@ pub async fn delete_project(
 
     match projects::remove(&state.profile, scope, &name) {
         Ok(removed) => (StatusCode::OK, Json(ProjectResponse::from(removed))).into_response(),
-        Err(e) => (
+        Err(RegistryError::NotFound(msg)) => (
             StatusCode::NOT_FOUND,
-            Json(serde_json::json!({"error": "not_found", "message": e.to_string()})),
+            Json(serde_json::json!({"error": "not_found", "message": msg})),
+        )
+            .into_response(),
+        Err(RegistryError::Conflict(msg)) => (
+            StatusCode::CONFLICT,
+            Json(serde_json::json!({"error": "conflict", "message": msg})),
+        )
+            .into_response(),
+        Err(RegistryError::Other(e)) => (
+            StatusCode::INTERNAL_SERVER_ERROR,
+            Json(serde_json::json!({"error": "remove_failed", "message": e.to_string()})),
         )
             .into_response(),
     }

src/session/projects.rs

@@ -3,14 +3,47 @@
 //! - Global: `<app_dir>/projects.json`, visible from every profile.
 //! - Profile: `<app_dir>/profiles/{profile}/projects.json`, visible only inside that profile.
 
-use anyhow::{bail, Result};
+use anyhow::Result;
 use serde::{Deserialize, Serialize};
 use std::fs;
 use std::path::{Path, PathBuf};
+use thiserror::Error;
 use tracing::warn;
 
 use super::{get_app_dir, get_profile_dir};
 
+/// Distinct failure modes for registry mutations. The web layer maps these to
+/// HTTP status codes (Conflict → 409, NotFound → 404, Other → 500); CLI/TUI
+/// callers convert via `Into<anyhow::Error>` and surface the message verbatim.
+#[derive(Debug, Error)]
+pub enum RegistryError {
+    /// A project with the same name or canonical path already exists in the
+    /// target scope, or in the other scope when `allow_override` is false.
+    #[error("{0}")]
+    Conflict(String),
+
+    /// `remove` could not find a project matching the given name or path in
+    /// the requested scope.
+    #[error("{0}")]
+    NotFound(String),
+
+    /// Any other failure (I/O, JSON parse, missing app dir).
+    #[error(transparent)]
+    Other(#[from] anyhow::Error),
+}
+
+impl From<std::io::Error> for RegistryError {
+    fn from(e: std::io::Error) -> Self {
+        RegistryError::Other(e.into())
+    }
+}
+
+impl From<serde_json::Error> for RegistryError {
+    fn from(e: serde_json::Error) -> Self {
+        RegistryError::Other(e.into())
+    }
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "lowercase")]
 pub enum ProjectScope {
@@ -154,33 +187,33 @@ pub fn add(
     scope: ProjectScope,
     mut project: Project,
     allow_override: bool,
-) -> Result<Project> {
+) -> std::result::Result<Project, RegistryError> {
     project.scope = scope;
     let path_buf = PathBuf::from(&project.path);
     let canonical = path_buf.canonicalize().unwrap_or_else(|_| path_buf.clone());
     project.path = canonical.to_string_lossy().to_string();
 
     let mut existing = match scope {
-        ProjectScope::Global => load_global()?,
-        ProjectScope::Profile => load_profile(profile)?,
+        ProjectScope::Global => load_global().map_err(RegistryError::Other)?,
+        ProjectScope::Profile => load_profile(profile).map_err(RegistryError::Other)?,
     };
 
     for p in &existing {
         if p.name.eq_ignore_ascii_case(&project.name) {
-            bail!(
+            return Err(RegistryError::Conflict(format!(
                 "Project '{}' already registered in {} scope (as '{}')",
                 project.name,
                 scope.as_str(),
                 p.name,
-            );
+            )));
         }
         if canonical_key(&p.path) == canonical_key(&project.path) {
-            bail!(
+            return Err(RegistryError::Conflict(format!(
                 "Path '{}' already registered as '{}' in {} scope",
                 project.path,
                 p.name,
                 scope.as_str()
-            );
+            )));
         }
     }
 
@@ -195,7 +228,7 @@ pub fn add(
         };
         for p in &other {
             if canonical_key(&p.path) == canonical_key(&project.path) {
-                bail!(
+                return Err(RegistryError::Conflict(format!(
                     "Path '{}' is already registered as '{}' in {} scope.\n\
                      Tip: remove it first with `aoe project remove {} --scope {}`,\n\
                      or pass `--allow-override` to keep both entries (the profile entry shadows the global entry in merged views).",
@@ -204,22 +237,26 @@ pub fn add(
                     other_scope.as_str(),
                     p.name,
                     other_scope.as_str(),
-                );
+                )));
             }
         }
     }
 
     existing.push(project.clone());
-    save_scope(profile, scope, &existing)?;
+    save_scope(profile, scope, &existing).map_err(RegistryError::Other)?;
     Ok(project)
 }
 
 /// Remove the entry matching `name_or_path` from the given scope. Returns the
 /// removed project, or errors if no match was found.
-pub fn remove(profile: &str, scope: ProjectScope, name_or_path: &str) -> Result<Project> {
+pub fn remove(
+    profile: &str,
+    scope: ProjectScope,
+    name_or_path: &str,
+) -> std::result::Result<Project, RegistryError> {
     let mut existing = match scope {
-        ProjectScope::Global => load_global()?,
-        ProjectScope::Profile => load_profile(profile)?,
+        ProjectScope::Global => load_global().map_err(RegistryError::Other)?,
+        ProjectScope::Profile => load_profile(profile).map_err(RegistryError::Other)?,
     };
 
     let canonical_target = canonical_key(name_or_path);
@@ -229,10 +266,14 @@ pub fn remove(profile: &str, scope: ProjectScope, name_or_path: &str) -> Result<
             p.name.eq_ignore_ascii_case(name_or_path) || canonical_key(&p.path) == canonical_target
         })
         .ok_or_else(|| {
-            anyhow::anyhow!("No project '{}' in {} scope", name_or_path, scope.as_str())
+            RegistryError::NotFound(format!(
+                "No project '{}' in {} scope",
+                name_or_path,
+                scope.as_str()
+            ))
         })?;
     let removed = existing.remove(idx);
-    save_scope(profile, scope, &existing)?;
+    save_scope(profile, scope, &existing).map_err(RegistryError::Other)?;
     Ok(removed)
 }
 

src/tui/components/help.rs

@@ -7,7 +7,7 @@ use crate::session::config::SortOrder;
 use crate::tui::styles::Theme;
 
 const DIALOG_WIDTH: u16 = 50;
-const DIALOG_HEIGHT: u16 = 43;
+const DIALOG_HEIGHT: u16 = 44;
 #[cfg(test)]
 const BORDER_HEIGHT: u16 = 2;
 #[cfg(test)]
@@ -118,6 +118,7 @@ fn shortcuts(strict: bool) -> Vec<(&'static str, Vec<(&'static str, &'static str
                     ("n/N", "Next/prev match"),
                     ("s", "Settings"),
                     ("P", "Profiles"),
+                    ("p", "Projects"),
                     ("R", "Serve (LAN / Tunnel)"),
                     ("u", "Update aoe (when available)"),
                     ("Ctrl+x", "Dismiss update bar (this session)"),

src/tui/dialogs/command_palette.rs

@@ -207,6 +207,14 @@ pub fn builtin_commands(serve_enabled: bool, strict_hotkeys: bool) -> Vec<Palett
             hotkey: "P",
             payload: PaletteAction::Key(KeyEvent::new(KeyCode::Char('P'), KeyModifiers::SHIFT)),
         },
+        PaletteCommand {
+            id: "projects",
+            title: "Manage projects".to_string(),
+            group: PaletteGroup::Settings,
+            keywords: vec!["registry", "repos", "multi-repo", "workspace"],
+            hotkey: "p",
+            payload: PaletteAction::Key(key('p')),
+        },
         PaletteCommand {
             id: "help",
             title: "Show keyboard shortcuts".to_string(),