Update Archon configuration and setup documentation

.archon/commands/defaults/scout-consolidate-perf-plan.md

@@ -0,0 +1,96 @@
+---
+description: Merge per-route Scout profiles into a single implementation plan (plan.md)
+argument-hint: (no arguments)
+---
+
+# Consolidate Scout performance plan
+
+**Workflow ID**: $WORKFLOW_ID  
+**Artifacts**: $ARTIFACTS_DIR
+
+---
+
+## Mission
+
+Read:
+
+- `$ARTIFACTS_DIR/routes.json`
+- `$ARTIFACTS_DIR/routes-summary.md`
+- `$ARTIFACTS_DIR/profile-00.md` … `$ARTIFACTS_DIR/profile-09.md` (include only files that exist; skipped indices may say SKIPPED)
+
+Produce **one** implementation plan at **`$ARTIFACTS_DIR/plan.md`** that `archon-plan-setup` / `archon-confirm-plan` / `archon-implement-tasks` can consume.
+
+---
+
+## Plan template (required sections)
+
+Use this structure (fill with real content from profiles):
+
+```markdown
+# Performance: Scout hot-route optimizations
+
+## Summary
+{1–2 sentences}
+
+## Mission
+{Single goal statement}
+
+## NOT Building (Scope Limits)
+- {Explicit non-goals — e.g. unrelated refactors, new features}
+- Do not change behavior except latency/resource usage unless noted.
+
+## Success Criteria
+- [ ] Each targeted route has measurable improvement or documented tradeoff
+- [ ] Project validation suite passes (see CLAUDE.md)
+- [ ] Scout shows no new regressions for these endpoints after deploy (verification note)
+
+## Files to Change
+
+| File | Action |
+|------|--------|
+| `{path}` | UPDATE |
+
+## Patterns to Mirror
+
+| Pattern | Source File | Lines |
+|---------|-------------|-------|
+| {name} | `{path}` | {lines} |
+
+## Task List
+
+### Task 1: {title}
+**Action**: UPDATE  
+**Details**: {specific changes}  
+**Route**: `{METHOD} {path}`  
+**Validate**: {command}
+
+### Task 2: ...
+
+(Add one or more tasks per route or grouped fix.)
+
+## Validation Commands
+1. Commands from CLAUDE.md / package.json (typecheck, lint, test).
+
+## Risks
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| {risk} | {H/M/L} | {mitigation} |
+```
+
+---
+
+## Rules
+
+1. **Deduplicate** overlapping tasks if multiple profiles touch the same file.  
+2. **Order** tasks by dependency (models before handlers, shared utils first).  
+3. **Reference** actual symbols/files from the profile markdown files.  
+4. If profiles disagree, prefer the most evidence-backed recommendation and note the conflict in **Risks**.  
+5. Ignore profiles that are SKIPPED or empty.
+
+---
+
+## Output
+
+- Write **`$ARTIFACTS_DIR/plan.md`** only (plan-setup will create `plan-context.md`).  
+- Stdout: `Plan written to $ARTIFACTS_DIR/plan.md with {N} tasks.`

.archon/commands/defaults/scout-discover-routes.md

@@ -0,0 +1,67 @@
+---
+description: Query Scout APM for top slow + high-traffic routes and write routes.json
+argument-hint: "[optional app name or app id — else first active app]"
+---
+
+# Scout route discovery
+
+**User message**: $ARGUMENTS  
+**Artifacts**: $ARTIFACTS_DIR
+
+---
+
+## Mission
+
+Use **Scout MCP** tools to identify **up to 10 HTTP routes** to optimize. Combine:
+
+- **Slowest** endpoints (p95 / mean response time), and  
+- **Most hit** (throughput / request volume)
+
+Dedupe by route identity (method + path). If you have fewer than 10 distinct hot/slow routes, include the next candidates by severity. If Scout returns fewer than 10, use all available.
+
+---
+
+## Prerequisites
+
+1. **MCP**: Scout tools should be available (`list_apps`, `get_app_endpoints`, `get_endpoint_metrics`, etc.). If MCP is unavailable, ask the user to set `SCOUT_API_KEY`, ensure Docker can run `scoutapp/scout-mcp-local`, or paste a Scout endpoints export into `$ARTIFACTS_DIR/scout-endpoints-export.json` (array of endpoint objects) and continue from that file.
+
+2. **App selection**: If `$ARGUMENTS` names an app or numeric id, use that. Otherwise call `list_apps` and pick the production app that matches this repo (name/hostname) or the most recently active app. State which app you chose.
+
+---
+
+## Steps
+
+1. Call Scout MCP to list endpoints with metrics for the chosen app (`get_app_endpoints` or equivalent).
+
+2. Rank and select up to **10** routes using a clear rule, e.g.:
+   - Take top **5** by p95 latency (or worst mean response time if p95 missing).
+   - Take top **5** by throughput.
+   - Union, dedupe, then fill remaining slots by composite score: `latency × log(throughput)` or similar.
+
+3. Write **`$ARTIFACTS_DIR/routes.json`** — JSON array of exactly the chosen routes, each object including at least:
+
+   - `rank` (1–10)  
+   - `method` (e.g. `GET`)  
+   - `path` (e.g. `/api/foo`)  
+   - `scout_name` or endpoint id if the API exposes one  
+   - `p95_ms`, `mean_ms` (numbers or null)  
+   - `rpm` or throughput (number or null)  
+   - `error_rate` if available  
+
+4. Write **`$ARTIFACTS_DIR/routes-summary.md`** — human-readable table: rank, method, path, p95, throughput, notes.
+
+5. Print a one-line stdout summary: `Discovered N routes for app {name} (id {id}).`
+
+---
+
+## Error handling
+
+- If no endpoints are returned: write `routes.json` as `[]`, explain in summary, and STOP with a clear error in stdout so the workflow can fail visibly.
+
+---
+
+## Success criteria
+
+- `routes.json` exists and is valid JSON.  
+- `routes-summary.md` exists.  
+- At most 10 routes; each profile step can rely on fixed indices `0..N-1`.

.archon/config.yaml

@@ -1,5 +1,8 @@
 worktree:
   baseBranch: dev
+  # Copy local .env into isolated worktrees so Scout MCP sees SCOUT_API_KEY when cwd is ~/.archon/workspaces/...
+  copyFiles:
+    - .env
 
 docs:
   path: packages/docs-web/src/content/docs