feat: multi-repo workspace support (project registry + pickers + dashboard)

[Seluj78]

Description

First-class multi-repo workspace support for agent-of-empires.

Closes #917

The multi-repo plumbing (WorkspaceInfo.repos, --repo flag, TUI Extra Repos field) already existed. This PR adds the three pieces called out in njbrake's final comment on the issue, plus closes two adjacent gaps that were blocking dashboard parity:

1. Project registry — saved repos with full CRUD across CLI, TUI, and web. Hybrid storage: a global <app_dir>/projects.json visible from every profile, and a per-profile <app_dir>/profiles/{profile}/projects.json. Loader merges them and lets profile entries shadow global ones on path collision.
2. Multi-select picker at session creation — TUI new-session dialog gets Ctrl+R on the Extra Repos field to open a registered-project picker; web wizard gets a chip-based multi-select with free-text fallback.
3. Dashboard surfaces all repos — multi-repo sessions render an inline chip row under the title; SessionResponse now carries workspace_repos so the frontend can show them.

Also fixed along the way:

• The web wizard previously did not POST extra_repo_paths, so the dashboard could not create multi-repo sessions even though the API accepted them.
• SessionResponse did not expose any workspace-repo info, so existing multi-repo sessions had no way to render correctly on the dashboard.

Defaults & ergonomics

• aoe project add <path> defaults to --scope global. When -p <profile> is passed at the top level, the default flips to --scope profile (the user is already in profile context, so registering globally would be surprising). Explicit --scope always wins.
• Cross-scope path collisions error by default with a tip pointing at aoe project remove and an --allow-override opt-in. Without this guard a re-add silently created a phantom duplicate.
• Name matching (add dedup, remove, aoe add --project NAME) is ASCII case-insensitive: aoe project remove smartcaller finds SmartCaller.
• aoe add --project NAME -w branch -b is a shortcut for typed --repo /long/path/... invocations.
• aoe project list pluralizes correctly.
• value_hint = DirPath/AnyPath on the path positionals so zsh and fish shell completion wire _files for ~/<TAB> expansion (bash hits a known clap_complete upstream limitation).

What's not in scope (per njbrake's comment)

• Agent-driven mid-session repo pull-in (orchestrator work, Orchestrator agent #553).
• Per-repo PR tracking (its own issue, tied to track opened PRs by the session #927).
• Saved workspace templates / named bundles.

PR Type

• New Feature
• Bug Fix
• Refactor
• Documentation
• Infrastructure / CI

Checklist

• I understand the code I am submitting
• New and existing tests pass
• Documentation was updated where necessary
• For UI changes: included screenshot or recording

(Recordings/screenshots: pending — opening as draft so reviewers can request specific captures.)

AI Usage

• No AI was used
• AI was used for drafting/refactoring
• This is fully AI-generated

AI Model/Tool used: Claude Code (Sonnet/Opus) drove planning, exploration of the existing multi-repo plumbing, scaffolding of the new modules, and incremental commits. Each commit was reviewed and tested locally before being staged.

Any Additional AI Details you'd like to share: Plan was iterated in plan mode before implementation began. After landing, the user (Seluj78) walked the surfaces by hand and reported several rough edges (cross-scope override behaviour, plural noun, unclear "worktree" tip wording, case-sensitivity on remove, scope-default ergonomics under -p); each was diagnosed and fixed in a follow-up commit.

• I am an AI Agent filling out this form (check box if true)

---

Manual Testing TODO

Setup once at the top of a session:

TMPHOME=$(mktemp -d)
export HOME="$TMPHOME"
export XDG_CONFIG_HOME="$TMPHOME/.config"

mkdir -p "$TMPHOME/repoA" "$TMPHOME/repoB" "$TMPHOME/repoC"
for d in repoA repoB repoC; do
  git -C "$TMPHOME/$d" init -q -b main
  git -C "$TMPHOME/$d" -c user.email=t@t -c user.name=t commit --allow-empty -q -m init
done

cargo build --features serve
AOE=./target/debug/aoe

Reset registry state between scenarios with: rm -rf "$TMPHOME/.config/agent-of-empires" "$TMPHOME/.agent-of-empires".

1. CLI: aoe project

• 1.1 — $AOE project list on empty registry shows "No projects registered." + hint
• 1.2 — $AOE project add "$TMPHOME/repoA" registers as [global], name repoA
• 1.3 — $AOE project list shows repoA [global] /…/repoA
• 1.4 — $AOE project list --json returns valid JSON array with scope: "global"
• 1.5 — $AOE project add "$TMPHOME/repoB" --scope profile shows [profile] badge
• 1.6 — $AOE project list --scope global shows only repoA
• 1.7 — $AOE project list --scope profile shows only repoB
• 1.8 — $AOE project list (default merged) shows both
• 1.9 — $AOE project add /not/a/repo errors with "not a git repository" + .git folder tip
• 1.10 — $AOE project add "$TMPHOME/repoA" (duplicate) errors with "already registered in global scope"
• 1.11 — $AOE project add "$TMPHOME/repoA" --name something --scope profile --allow-override succeeds; profile shadows global
• 1.12 — Without --allow-override, the same cross-scope add errors with the tip pointing at aoe project remove --scope global
• 1.13 — $AOE project list after 1.11 shows the profile entry (one row, name something)
• 1.14 — $AOE project remove repoA removes from global; profile entry survives
• 1.15 — $AOE project remove SOMETHING --scope profile (uppercase) finds the lowercase entry — case-insensitive
• 1.16 — $AOE project remove "$TMPHOME/repoB" --scope profile removes by full path
• 1.17 — $AOE project remove ghost errors with "no project 'ghost' in global scope"
• 1.18 — $AOE -p custom project add "$TMPHOME/repoC" (no --scope) defaults to PROFILE scope
• 1.19 — $AOE -p custom project add "$TMPHOME/repoC" --scope global honors the explicit override
• 1.20 — $AOE project list (default) vs $AOE -p custom project list shows different visible sets
• 1.21 — $AOE project list after registering 1 project prints "Total: 1 project" (singular)
• 1.22 — Shell completion: with aoe completion zsh sourced, $AOE project add ~/<TAB> expands paths

2. CLI: aoe add --project

Pre-reqs: register repoB as global, repoC as profile-only.

• 2.1 — $AOE add "$TMPHOME/repoA" --project repoB -w feat -b creates a 2-worktree workspace
• 2.2 — $AOE add "$TMPHOME/repoA" --project repoB --project repoC -w feat2 -b creates a 3-worktree workspace
• 2.3 — $AOE add "$TMPHOME/repoA" --project ghost -w feat3 -b fails fast with "Unknown project 'ghost'. Available: repoB, repoC"
• 2.4 — $AOE add "$TMPHOME/repoA" --project repoB (no -w) fails: --repo/--project requires --worktree
• 2.5 — $AOE add "$TMPHOME/repoA" --project REPOB -w feat5 -b resolves case-insensitively
• 2.6 — $AOE add "$TMPHOME/repoA" --repo "$TMPHOME/repoB" --project repoB -w feat4 -b fails the duplicate-name guard (same repo via two routes)
• 2.7 — $AOE add "$TMPHOME/repoA" -w solo -b (no project flag) regression: single-repo session unchanged
• 2.8 — After 2.1, aoe list shows the session and stored JSON has 2 repos in workspace_info

3. Web API (aoe serve --no-auth --port 41234 --host 127.0.0.1)

BASE=http://127.0.0.1:41234.

• 3.1 — curl $BASE/api/projects returns [] initially
• 3.2 — POST /api/projects with {"path":".../repoA"} returns 201 + scope: "global"
• 3.3 — POST with "scope":"profile" returns 201 + scope: "profile"
• 3.4 — POST with "scope":"weird" returns 400 bad_scope
• 3.5 — POST with a non-git path returns 400 not_a_git_repo
• 3.6 — POST duplicate within scope returns 409 add_failed
• 3.7 — POST cross-scope dup without allow_override returns 409
• 3.8 — POST cross-scope dup with "allow_override": true returns 201
• 3.9 — GET /api/projects?scope=global returns only globals
• 3.10 — GET /api/projects?scope=profile returns only profile entries
• 3.11 — GET /api/projects?scope=invalid returns 400
• 3.12 — DELETE /api/projects/repoA?scope=global returns 200 with the removed entry
• 3.13 — DELETE /api/projects/ghost?scope=global returns 404
• 3.14 — Restart with --read-only: POST/DELETE return 403 read_only
• 3.15 — GET /api/sessions for a multi-repo session populates workspace_repos; single-repo sessions return [], never null/missing

4. Web Wizard (localhost:41234, "+ New session")

• 4.1 — Step 1, no project selected: "Extra repos" picker hidden
• 4.2 — Pick a repo via Browse tab: picker appears below
• 4.3 — Pick again from Recent: picker still appears
• 4.4 — Picker with empty registry: "No registered projects yet." hint
• 4.5 — Picker with registered projects: each shown as a chip with [global]/[profile] badge
• 4.6 — Click a project chip: toggles to "selected" with brand color
• 4.7 — Click again: deselects
• 4.8 — Free-text input + "Add" button: path appears as a selected chip with × button
• 4.9 — Free-text input + Enter: same
• 4.10 — Primary repo path is filtered out of the registered list
• 4.11 — Submit wizard with 0 extras: single-repo session created, no extra_repo_paths in POST
• 4.12 — Submit with 2 extras: POST body includes extra_repo_paths: [...]; session created with workspace
• 4.13 — Submit with primary repo path also in extras: backend hard-fails, error bubbles to wizard
• 4.14 — DevTools network tab confirms POST /api/sessions body includes extra_repo_paths only when non-empty

5. Web Projects page (/projects, folder icon in sidebar footer)

• 5.1 — Empty state: "No registered projects yet." + CLI hint
• 5.2 — Click "+ Add project": form expands inline
• 5.3 — DirectoryBrowser opens via "Browse"; selection writes path back into the form
• 5.4 — Empty path: Add button disabled
• 5.5 — Non-git path: error banner with "not a git repository"
• 5.6 — Valid path, scope=global, no name: adds with directory basename, [global] badge
• 5.7 — Same path, scope=global again: 409 conflict error
• 5.8 — Same path, scope=profile, allow_override unchecked: 409
• 5.9 — Same path, scope=profile, allow_override checked: 201, profile shadows global in merged view
• 5.10 — List shows global = brand-tinted badge, profile = neutral
• 5.11 — Click Remove on a profile entry: confirm prompt; on accept the row disappears
• 5.12 — --read-only server: Add button hidden, Remove button hidden
• 5.13 — Resize to mobile (DevTools iPhone preset): page usable, no overflow, tap-friendly
• 5.14 — Close button returns to last route (session or dashboard)
• 5.15 — Back/forward nav between /projects and /session/:id: no flicker, sidebar reappears when leaving

6. Web dashboard cards

• 6.1 — Single-repo session in sidebar renders unchanged (label + branch subtitle)
• 6.2 — Multi-repo session shows a small chip row with each repo name under the label
• 6.3 — Hovering the chip row exposes full source paths via title
• 6.4 — Two sessions in the same multi-repo workspace render chips independently
• 6.5 — Reload page: chips persist (server returns workspace_repos)

7. TUI projects picker (in new-session dialog)

aoe to open TUI, press n for new session.

• 7.1 — Fill path + worktree branch, Tab to "Worktree" field: field shows
• 7.2 — Ctrl+P on Worktree: worktree config overlay opens
• 7.3 — Tab to "Extra Repos" field: hint row shows C-r pick project
• 7.4 — Ctrl+R on empty registry: error message "No registered projects available…"
• 7.5 — After registering one project, Ctrl+R: picker overlay opens with "Add registered project" title
• 7.6 — Pick a project via Enter: project's path appended to repo list
• 7.7 — Ctrl+R again: already-added project filtered out
• 7.8 — Primary repo (not in registry) is filtered out of picker
• 7.9 — Esc out of picker: closes, no change
• 7.10 — Submit dialog: multi-repo session created with selected project's path
• 7.11 — Free-text path entry still works (regression for typed paths)

8. TUI projects panel

• 8.1 — Press p on home screen: Projects dialog opens
• 8.2 — Empty registry: "No registered projects. Press 'a' to add one."
• 8.3 — Press a: add form appears with Path field focused
• 8.4 — Type non-git path, Enter: inline error "Not a git repository"
• 8.5 — Type valid path, Enter: added with default scope=global, returns to browse mode
• 8.6 — Press a again, Tab to Scope field: scope label underlined
• 8.7 — Space / ← / → on Scope field: toggles global ↔ profile-only
• 8.8 — Tab to Override field, Space toggles [ ] ↔ [x]
• 8.9 — Submit with profile scope: adds with [profile] badge
• 8.10 — j/k on the list: cursor moves
• 8.11 — d (or Delete): removes selected entry, status line shows "Removed '…'"
• 8.12 — q or Esc: dialog closes
• 8.13 — Re-open after d: list reflects removal
• 8.14 — Press P (capital): profile picker opens (regression — no collision with p)
• 8.15 — While dialog is open, other home keybinds are ignored (dialog has focus)

9. Cross-surface consistency

• 9.1 — Add via CLI, observe in TUI panel after dialog reload
• 9.2 — Add via web Projects page, observe in aoe project list
• 9.3 — Add via TUI, refresh dashboard: chip appears in wizard picker
• 9.4 — Same path added in global + profile (different names): merged shows one entry; profile name wins; CLI scoped lists show both
• 9.5 — Switch profile (-p other): profile-scoped entries from default not visible; globals still visible
• 9.6 — Remove a project that a session is using: session unaffected (paths stored on session, not by lookup)
• 9.7 — Move a registered repo on disk, then re-list: path still shown; new sessions with --project NAME may fail (documented limitation)

10. Edge / regression

• 10.1 — Single-repo session created before this branch loads fine; web returns workspace_repos: []; sidebar unchanged
• 10.2 — aoe add /path -w feat -b (no --repo, no --project): single worktree path unchanged
• 10.3 — aoe add /path -r /other -w feat -b (only --repo): multi-repo workspace built, no registry interaction
• 10.4 — --repo and --project together: both merged into extras; duplicate-name guard fires only on real duplicates
• 10.5 — Empty profile name (env unset): defaults to default; profile-scoped projects.json lives at profiles/default/projects.json
• 10.6 — After 2nd save in either scope, .bak sibling exists
• 10.7 — Hand-edit projects.json to invalid JSON: loaders return error; CLI list shows error; TUI/web log warning, no panic
• 10.8 — Delete projects.json while server running: next API call returns empty list, no crash
• 10.9 — Path with spaces / special chars: canonicalizes correctly; chips render the basename
• 10.10 — Symlinked repo path: canonicalizes to target; same-repo dedup matches

11. Build / CI

• 11.1 — cargo fmt --check clean
• 11.2 — cargo clippy --all-targets --features serve no warnings
• 11.3 — cargo test passes (2 known pre-existing Docker containers::runtime failures unrelated)
• 11.4 — cargo build --features serve --release clean
• 11.5 — cd web && npx tsc --noEmit clean
• 11.6 — cd web && npx vite build clean
• 11.7 — cargo xtask gen-docs then git diff docs/cli/reference.md shows no diff

[Seluj78]

@njbrake what is this commit you pushed ? 👀

Edit: nevermind I was able to read the commit body ! Thanks ! 🥰

[njbrake]

Note: this comment was drafted by Claude via back-and-forth with @njbrake. The reasoning and decisions are his; the prose is Claude's.

Substantive code review came back positive. Claude did the deep dive, I spot-checked, and pushed one follow-up commit (49dbe7a) fixing a few structural items I wanted in before merge:

• Strict-mode p blocklist gap (bare p was bypassing the strict-mode contract).
• ? overlay and Ctrl+K command palette entries for the new Projects panel.
• Typed RegistryError in projects::add / remove so the API returns 409 only on conflict and 500 on actual I/O (was 409 for everything).
• Extracted the picker logic out of handle_worktree_config_key and dropped the #[allow(clippy::too_many_lines)].
• docs/guides/multi-repo-workspaces.md plus website wiring.
• 6 e2e tests in tests/e2e/project_registry.rs covering aoe project round-trip, the typed error paths, and --project flag interactions.

Tests, clippy, fmt, tsc all clean. Architecture maps cleanly to the 3-piece plan in #917.

Two asks before flipping out of draft:

1. Lock scope. Bugs you find during your remaining manual testing should land here. Anything that feels like a new feature or a different surface should go to a follow-up issue. The PR is already at +2,600 lines and I'd rather merge a tight scope than let it balloon. You've been disciplined already (the "out of scope" list in the PR body is exactly right); I'm just reinforcing the boundary so you don't feel pressure to keep adding "while I'm here" items.

2. Finish the manual checks. Sections 7 (TUI picker), 8 (TUI panel), 9 (cross-surface consistency), 10 (edge cases), and 6.4 (two sessions in the same multi-repo workspace) are still unchecked. One screenshot or short recording of the dashboard chips and the TUI picker would help for posterity.

If anything else surfaces, file a follow-up and I'll fast-track it. Concrete punt targets so you don't feel cut off:

• Per-repo branch names (you flagged it yourself as low priority).
• Saved workspace templates / named bundles.
• Per-repo PR tracking (track opened PRs by the session #927 territory).
• TUI Projects panel polish (delete confirm, name editing).

Thanks for the iteration so far. The cross-scope override and case-insensitivity fixes were good catches.

[njbrake]

@Seluj78 looks like failing playwright test to address

[Seluj78]

@njbrake Fix pushed 😀