feat: add doctor command, enhance logs/status/dashboard, complete skill docs

.claude/skills/symphony/SKILL.md → .agents/skills/symphony/SKILL.md

@@ -39,9 +39,18 @@ symphony start WORKFLOW.md              # run daemon
 | `symphony stop` | Graceful shutdown |
 | `symphony validate WORKFLOW.md` | Validate config + template |
 | `symphony config WORKFLOW.md` | Show resolved config |
+| `symphony logs [--follow] [--level LEVEL] [--since TIME]` | Tail daemon log file (filter by level/time) |
+| `symphony workspaces` | List workspace directories |
+| `symphony workspace STI-123 [--clean]` | Show/manage a workspace |
+| `symphony check` | Run `make smoke` equivalent |
+| `symphony audit` | Full control audit |
+| `symphony test [--crate-name NAME]` | Run tests with filtering |
+| `symphony doctor` | Pre-flight environment check |
 
 Flags: `--port`, `--host`, `--token`, `--format json`, `--concurrency`, `--turns`, `--once`, `--tickets STI-1,STI-2`
 
+> `--format json` is supported by: `status`, `issues`, `workspaces`, `workspace`, `config`.
+
 ## WORKFLOW.md
 
 YAML frontmatter (config) + Liquid template body (agent prompt). For complete reference: [references/workflow-config.md](references/workflow-config.md).
@@ -86,6 +95,23 @@ Set up: create `CONTROL.md` with setpoints, add sensors in `Makefile`, reference
 
 Implement `TrackerClient` trait (4 methods: `fetch_candidate_issues`, `fetch_issues_by_states`, `fetch_issue_states_by_ids`, `set_issue_state`). Register in `create_tracker()` factory.
 
+## Arcan Runtime
+
+When `runtime.kind: arcan` is configured, Symphony dispatches work through the Arcan HTTP daemon instead of spawning local subprocesses.
+
+```yaml
+runtime:
+  kind: arcan
+  base_url: http://localhost:3000    # Arcan daemon URL
+  policy:
+    allow_capabilities: [read, write, shell]
+    gate_capabilities: [network]
+```
+
+**Flow:** health check (`GET /health`) → create session (`POST /sessions`) → execute run (`POST /sessions/{id}/runs`) → poll state until complete.
+
+Arcan session IDs follow the pattern `symphony-{issue_identifier}`.
+
 ## Key Environment Variables
 
 | Variable | Purpose |

.agents/skills/symphony/references/operator-runbook.md

@@ -0,0 +1,91 @@
+# Symphony Operator Runbook
+
+Executable diagnostic recipes for operating Symphony runtimes.
+
+## Pre-flight Check
+
+```bash
+symphony doctor                # checks WORKFLOW.md, env vars, binaries, daemon
+```
+
+## Check Daemon Health
+
+```bash
+curl -s http://localhost:8080/healthz    # 200 = alive
+curl -s http://localhost:8080/readyz     # 200 = ready, 503 = initializing
+symphony status                          # full daemon state
+symphony status --format json | jq .     # machine-readable
+```
+
+## Debug Stuck Issue
+
+```bash
+symphony issue STI-123                      # check state, turn count, tokens
+symphony logs --id STI-123                  # filter logs for this issue
+symphony logs --id STI-123 --level error    # errors only
+symphony logs --since 30m --id STI-123      # last 30 minutes
+```
+
+## Analyze Token Usage
+
+```bash
+symphony status                             # total tokens in status output
+curl -s http://localhost:8080/api/v1/metrics | jq .totals
+curl -s http://localhost:8080/metrics | grep symphony_tokens  # Prometheus
+```
+
+## Inspect Workspaces
+
+```bash
+symphony workspaces                         # list all
+symphony workspace STI-123                  # detail for one
+symphony workspace STI-123 --clean          # remove workspace directory
+ls ~/symphony-workspaces/project/           # manual inspection
+```
+
+## Troubleshoot Hooks
+
+```bash
+# Test hooks in isolation:
+export SYMPHONY_ISSUE_ID="STI-123"
+export SYMPHONY_ISSUE_TITLE="Test issue"
+bash -x -c 'git add -A && git commit -m "test"'    # test after_run
+bash -x -c 'gh pr create --title "test" --body ""'  # test PR creation
+```
+
+## Force Immediate Poll
+
+```bash
+symphony refresh                            # trigger poll now
+curl -X POST http://localhost:8080/api/v1/refresh  # direct API
+```
+
+## Stop Runaway Issue
+
+```bash
+# Move issue to terminal state in tracker (stops retries):
+# Linear: set to "Done" or "Cancelled"
+# GitHub: close the issue
+
+# Or shut down the daemon entirely:
+symphony stop
+```
+
+## View Prometheus Metrics
+
+```bash
+curl -s http://localhost:8080/metrics | grep -v '^#'  # values only
+# Key metrics:
+#   symphony_sessions_running      — active agent count
+#   symphony_sessions_retrying     — retry queue depth
+#   symphony_tokens_total          — cumulative token spend
+#   symphony_issues_completed      — lifetime completions
+```
+
+## Arcan Runtime Diagnostics
+
+```bash
+curl -s http://localhost:3000/health          # Arcan daemon health
+symphony status                               # shows arcan sessions
+# If arcan is unreachable, check base_url in WORKFLOW.md runtime section
+```

.claude/skills/symphony/references/troubleshooting.md → .agents/skills/symphony/references/troubleshooting.md

@@ -61,6 +61,25 @@ after_run: |
 mkdir -p ~/symphony-workspaces/project
 ```
 
+### Arcan daemon unreachable
+**Cause**: `runtime.kind: arcan` configured but Arcan daemon not running.
+**Fix**: Start the Arcan daemon or verify `runtime.base_url` in WORKFLOW.md:
+```bash
+curl http://localhost:3000/health   # should return 200
+# If using a different URL:
+# runtime:
+#   kind: arcan
+#   base_url: http://your-host:3000
+```
+
+### Pre-flight check failures
+**Cause**: Missing binaries, env vars, or config.
+**Fix**: Run `symphony doctor` for a full pre-flight diagnostic:
+```bash
+symphony doctor
+# Checks: WORKFLOW.md, env vars, binaries (claude, gh, git), daemon connectivity
+```
+
 ## Monitoring
 
 ### HTTP Dashboard

.gitignore

@@ -13,9 +13,13 @@
 .obsidian/core-plugins-migration.json
 
 # Skills CLI — agent symlinks created by `npx skills add`
-# The source skill lives in .claude/skills/symphony/ (tracked)
+# The canonical skill source lives in .agents/skills/symphony/ (tracked)
+# .claude/skills/symphony is a symlink → ../../.agents/skills/symphony
 # These are auto-generated per-agent symlinks (not tracked)
-.agents/
+.agents/*
+!.agents/skills/
+.agents/skills/*
+!.agents/skills/symphony/
 .agent/
 .augment/
 .codebuddy/
@@ -38,7 +42,7 @@
 .trae/
 .windsurf/
 .zencoder/
-skills/
+/skills/
 skills-lock.json
 
 # Claude Code worktrees and local state