docs/skill: general hardening — fix inaccuracies, fill workflow/CLI/env gaps, add good-practices + troubleshooting

.claude/skills/archon/SKILL.md

@@ -42,6 +42,8 @@ Determine the user's intent and dispatch to the appropriate guide:
 | **Variable substitution reference** | Read `references/variables.md` |
 | **CLI command reference** | Read `references/cli-commands.md` |
 | **Run an interactive workflow** | Read `references/interactive-workflows.md` — transparent relay protocol |
+| **Workflow good practices / anti-patterns** | Read `references/good-practices.md` — read before designing a non-trivial workflow |
+| **Troubleshoot a failing / stuck workflow** | Read `references/troubleshooting.md` — log locations, common failure modes |
 | **Run a workflow (default)** | Continue with "Running Workflows" below |
 
 If the intent is ambiguous, ask the user to clarify.
@@ -204,6 +206,29 @@ Each node has exactly ONE of: `command`, `prompt`, `bash`, `script`, `loop`, `ap
     until_bash: "bun run test"    # Optional: exit 0 = done
 ```
 
+**Approval node** — pauses the workflow for human review. Requires `interactive: true` at the workflow level for Web UI delivery:
+```yaml
+interactive: true   # workflow level — required for web UI
+
+nodes:
+  - id: review-gate
+    approval:
+      message: "Review the plan above before proceeding."
+      capture_response: true      # Optional: user's comment → $review-gate.output
+      on_reject:                  # Optional: AI rework on rejection instead of cancel
+        prompt: "Revise based on feedback: $REJECTION_REASON"
+        max_attempts: 3           # Range 1-10, default 3
+    depends_on: [plan]
+```
+
+**Cancel node** — terminates the workflow with a reason. Typically gated with `when:`:
+```yaml
+- id: stop-if-unsafe
+  cancel: "Refusing to proceed: input flagged UNSAFE."
+  depends_on: [classify]
+  when: "$classify.output != 'SAFE'"
+```
+
 For the full authoring guide with all fields, conditions, trigger rules, and patterns: Read `references/workflow-dag.md`
 
 ### Creating a Command File

.claude/skills/archon/references/authoring-commands.md

@@ -4,14 +4,29 @@ Commands are plain Markdown files containing AI prompt templates. They are the a
 
 ## File Location
 
+Commands are discovered from three scopes, highest-precedence first:
+
 ```
-.archon/commands/
-├── my-command.md           # Custom command
-├── review-code.md          # Another custom command
-└── defaults/               # Optional: override bundled defaults
-    └── archon-assist.md    # Overrides the bundled archon-assist
+<repoRoot>/.archon/commands/     # 1. Repo-scoped (wins)
+├── my-command.md                #    Custom command for this repo
+├── archon-assist.md             #    Overrides the bundled archon-assist
+└── triage/                      #    Subfolders allowed, 1 level deep
+    └── review.md                #    Resolves as 'review', not 'triage/review'
+
+~/.archon/commands/              # 2. Home-scoped (user-level, shared across all repos)
+├── review-checklist.md          #    Personal helper available in every repo
+└── pr-style-guide.md
+
+<bundled defaults>                # 3. Shipped with Archon (archon-assist, etc.)
 ```
 
+**Resolution rules:**
+
+- Filename-without-extension is the command name (e.g. `my-command.md` → `my-command`).
+- 1-level subfolders are supported for grouping; resolution is still by filename (`triage/review.md` → `review`).
+- Repo scope overrides home scope overrides bundled, by name.
+- Duplicate basenames **within a scope** (e.g. two different `review.md` files in `triage/` and `security/`) are a user error — keep names unique within each scope.
+
 Commands are referenced by name (without `.md`) in workflow YAML files.
 
 ## File Format
@@ -78,11 +93,14 @@ Command names must:
 ## Discovery and Priority
 
 When a workflow references `command: my-command`, Archon searches in this order:
-1. `.archon/commands/my-command.md` (repo custom)
-2. `.archon/commands/defaults/my-command.md` (repo default overrides)
+
+1. `<repoRoot>/.archon/commands/my-command.md` (repo scope)
+2. `~/.archon/commands/my-command.md` (home scope — shared across every repo on the machine)
 3. Bundled defaults (shipped with Archon)
 
-First match wins. To override a bundled command, create a file with the same name in your repo.
+First match wins. To override a bundled command, drop a file with the same name at either scope. To override a home-scoped command for a specific repo, drop a file with the same name in that repo's `.archon/commands/`.
+
+> **Web UI note**: Home-scoped commands appear in the workflow builder's node palette under a dedicated "Global (~/.archon/commands/)" section, distinct from project and bundled entries.
 
 ## Referencing Commands from Workflows
 

.claude/skills/archon/references/cli-commands.md

@@ -32,7 +32,7 @@ archon workflow run archon-fix-github-issue --resume
 | `--branch <name>` / `-b` | Branch name for worktree. Reuses existing worktree if healthy |
 | `--from <name>` / `--from-branch <name>` | Start-point branch for new worktree (default: repo default branch) |
 | `--no-worktree` | Skip isolation — run in the live checkout |
-| `--resume` | Resume the last failed run of this workflow (skips completed steps/nodes) |
+| `--resume` | Resume the last failed run of this workflow at this cwd (skips completed nodes) |
 | `--cwd <path>` | Working directory override |
 
 **Flag conflicts** (errors):
@@ -42,6 +42,87 @@ archon workflow run archon-fix-github-issue --resume
 
 **Default behavior** (no flags): Auto-creates a worktree with branch name `{workflow-name}-{timestamp}`.
 
+**Auto-resume without `--resume`**: If a prior invocation of the same workflow at the same cwd failed, the next invocation automatically skips completed nodes. `--resume` is only needed when you want to force resume a specific failed run or to reuse the worktree from that run.
+
+### `archon workflow status`
+
+Show the currently running workflow (if any) with its run ID, state, and last activity.
+
+```bash
+archon workflow status
+archon workflow status --json       # Machine-readable output
+```
+
+### `archon workflow approve <run-id> [comment]`
+
+Approve a paused approval-node workflow. Auto-resumes the workflow.
+
+```bash
+archon workflow approve abc123
+archon workflow approve abc123 --comment "Plan looks good"
+archon workflow approve abc123 "Plan looks good"   # positional form
+```
+
+For interactive loop nodes, the comment becomes `$LOOP_USER_INPUT` on the next iteration. For approval nodes with `capture_response: true`, the comment becomes `$<gate-id>.output` for downstream nodes.
+
+### `archon workflow reject <run-id> [reason]`
+
+Reject a paused approval gate. Without `on_reject` on the node, cancels the workflow. With `on_reject`, runs the rework prompt with `$REJECTION_REASON` substituted and re-pauses.
+
+```bash
+archon workflow reject abc123
+archon workflow reject abc123 --reason "Plan misses test coverage"
+archon workflow reject abc123 "Plan misses test coverage"
+```
+
+### `archon workflow abandon <run-id>`
+
+Mark a non-terminal workflow run as cancelled. Use when a `running` row is stuck after a server crash or when you want to discard a paused run without rejecting. This does NOT kill an in-flight subprocess — it only transitions the DB row.
+
+```bash
+archon workflow abandon abc123
+```
+
+> **There is no `archon workflow cancel` CLI subcommand.** To actively cancel a running workflow (terminate its subprocess), use the chat slash command `/workflow cancel <run-id>` on the platform that started it (Web UI, Slack, Telegram, etc.), or the Cancel button on the Web UI dashboard. The CLI only offers `abandon`, which is the right tool for orphan cleanup but does not interrupt a live subprocess.
+
+### `archon workflow resume <run-id> [message]`
+
+Explicitly re-run a failed run. Most workflows auto-resume without this — use it when you want to force a specific run ID.
+
+```bash
+archon workflow resume abc123
+archon workflow resume abc123 "continue with the plan"
+```
+
+### `archon workflow cleanup [days]`
+
+**Deletes** old terminal workflow runs (`completed`/`failed`/`cancelled`) from the database for disk hygiene. Does NOT transition `running` rows — use `abandon`/`cancel` for those.
+
+```bash
+archon workflow cleanup             # Default: 7 days
+archon workflow cleanup 30          # Custom: 30 days
+```
+
+### `archon workflow event emit --run-id <uuid> --type <event-type> [--data <json>]`
+
+Emit a workflow event to a running workflow. Used inside loop prompts to signal state (e.g. "checkpoint written") for observability. Rarely invoked from the shell directly.
+
+```bash
+archon workflow event emit --run-id abc123 --type checkpoint --data '{"step":"plan"}'
+```
+
+### `archon continue <branch> [flags] [message]`
+
+Continue work on a branch with prior context. Defaults to `archon-assist`; use `--workflow` to pick a different workflow. Useful for iterative sessions on the same worktree without typing the full `workflow run` incantation.
+
+```bash
+archon continue feat/auth "Add password reset"
+archon continue feat/auth --workflow archon-feature-development "Continue from step 3"
+archon continue feat/auth --no-context "Start fresh without loading prior artifacts"
+```
+
+Flags: `--workflow <name>`, `--no-context`.
+
 ## Isolation Commands
 
 ### `archon isolation list`
@@ -59,11 +140,20 @@ Outputs: branch name, path, workflow type, platform, last activity age. Ghost en
 Remove stale worktree environments.
 
 ```bash
-archon isolation cleanup          # Default: 7 days
-archon isolation cleanup 14       # Custom: 14 days
-archon isolation cleanup --merged # Remove branches merged into main (+ remote branches)
+archon isolation cleanup                             # Default: 7 days
+archon isolation cleanup 14                          # Custom: 14 days
+archon isolation cleanup --merged                    # Also remove worktrees whose branches merged into main (deletes remote branches too)
+archon isolation cleanup --merged --include-closed   # Also remove worktrees whose PRs were closed without merging
 ```
 
+**Flags:**
+
+| Flag | Description |
+|------|-------------|
+| `[days]` | Positional — age threshold in days. Environments untouched for longer than this are removed. Default: 7 |
+| `--merged` | Union of three signals — ancestry (`git branch --merged`), patch equivalence (`git cherry`), and PR state (`gh`) — safely catches squash-merges |
+| `--include-closed` | With `--merged`, also remove worktrees whose PRs were closed (abandoned, not merged) |
+
 ## Validate Commands
 
 ### `archon validate workflows [name]`