@hanzlaa/rcode 2.1.0

package/rihal/workflows/from-template.md

@@ -0,0 +1,173 @@
+# Workflow: rihal:from-template
+
+<purpose>
+Seed a fresh project's `.planning/` directory from a canonical starter template (saas-b2b, api-backend, mobile-app). Replaces the blank-page moment after `rihal init` with a PROJECT.md skeleton, a ROADMAP.md with typical phases for this kind of project, and a REQUIREMENTS.md of common REQ-IDs.
+
+Templates are a starting point, not a prescription. Every section is meant to be edited. The goal is to have something concrete to react to instead of an empty file.
+</purpose>
+
+<output_format>
+Open with banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RIHAL ► FROM TEMPLATE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+End with a file summary and Next Up routing.
+</output_format>
+
+<required_reading>
+@.rihal/references/output-format.md
+</required_reading>
+
+<process>
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty, contains `--help`, `-h`, or `list` — print the catalog:
+
+```
+/rihal:from-template <template-name> [--project-name "<name>"] [--force]
+
+Available templates:
+  saas-b2b      Multi-tenant B2B SaaS — auth, orgs, billing, RBAC, admin
+  api-backend   Headless API service — auth, contract, SDK, docs, SLOs
+  mobile-app    iOS + Android app — onboarding, offline, push, store launch
+
+Flags:
+  --project-name "<name>"   Name substituted into PROJECT.md / ROADMAP.md placeholders (default: basename of cwd)
+  --force                   Overwrite .planning/ files that already exist (destructive)
+```
+
+STOP.
+
+## Step 1 — Resolve the template
+
+```bash
+TEMPLATE="${1}"
+TEMPLATE_DIR=".rihal/templates/projects/${TEMPLATE}"
+
+if [ ! -d "$TEMPLATE_DIR" ]; then
+  echo "Unknown template: ${TEMPLATE}"
+  echo "Run: /rihal:from-template --help  for the catalog."
+  exit 0
+fi
+```
+
+Read `${TEMPLATE_DIR}/template.yaml` to show the user what will be seeded:
+
+```
+Template: {display}
+  {description}
+
+Phases that will be seeded:
+  - {phase_1}
+  - {phase_2}
+  ...
+
+Recommended modules: {modules}
+```
+
+## Step 2 — Safety check
+
+```bash
+PLANNING=".planning"
+EXISTING=()
+for f in PROJECT.md ROADMAP.md REQUIREMENTS.md; do
+  [ -f "${PLANNING}/${f}" ] && EXISTING+=("${f}")
+done
+```
+
+If `EXISTING` is non-empty and `--force` was NOT passed:
+
+```
+.planning/ already contains:
+  - {each existing file}
+
+Refusing to overwrite. Options:
+  - Pass --force to overwrite (destructive)
+  - Delete the existing files first, then re-run
+  - Use /rihal:new-project for the interactive discovery flow instead
+```
+
+STOP.
+
+## Step 3 — Substitute placeholders
+
+Compute substitutions:
+
+```bash
+PROJECT_NAME="${PROJECT_NAME_FLAG:-$(basename "$PWD")}"
+DATE="$(date -u +%Y-%m-%d)"
+```
+
+Placeholders supported in template files:
+- `{{project_name}}` → `$PROJECT_NAME`
+- `{{date}}` → `$DATE`
+
+All other `{{...}}` tokens are left in place intentionally — they're prompts for the user to fill in.
+
+## Step 4 — Copy + substitute
+
+```bash
+mkdir -p "${PLANNING}"
+
+for f in PROJECT.md ROADMAP.md REQUIREMENTS.md; do
+  SRC="${TEMPLATE_DIR}/${f}"
+  DEST="${PLANNING}/${f}"
+  [ -f "$SRC" ] || continue
+  # Substitute only the two known placeholders; leave all other {{...}} for the user to edit.
+  sed -e "s|{{project_name}}|${PROJECT_NAME//|/\\|}|g" \
+      -e "s|{{date}}|${DATE}|g" \
+      "$SRC" > "$DEST"
+done
+```
+
+## Step 5 — Record the seeding
+
+```bash
+node .rihal/bin/rihal-tools.cjs state add-decision \
+  "Seeded .planning/ from template '${TEMPLATE}' (project: ${PROJECT_NAME})" 2>/dev/null || true
+```
+
+This surfaces the seeding both in local state AND `/rihal:decisions` cross-project memory.
+
+## Step 6 — Commit
+
+Suggest (do not execute without confirmation) a baseline commit:
+
+```
+git add .planning/PROJECT.md .planning/ROADMAP.md .planning/REQUIREMENTS.md
+git commit -m "docs(planning): seed from template — ${TEMPLATE}"
+```
+
+## Step 7 — Summary + Next Up
+
+```
+✓ Seeded .planning/ from template '${TEMPLATE}'
+  - .planning/PROJECT.md       ({size})
+  - .planning/ROADMAP.md       ({size})
+  - .planning/REQUIREMENTS.md  ({size})
+
+Next Up (from template.yaml.next_steps):
+  {next_steps_block}
+
+Also consider:
+  /rihal:discuss-phase 01   — adapt phase 01 to your specifics
+  /rihal:council            — sanity-check the starter phases before committing to them
+```
+</process>
+
+## Success Criteria
+
+- Unknown template name → catalog is printed, not a crash
+- Existing `.planning/` files → refused unless `--force`
+- `{{project_name}}` and `{{date}}` are substituted; other `{{...}}` tokens remain for the user to edit
+- Seeded files are exactly the template files with only the two substitutions applied
+- Seeding is recorded via `state add-decision` for traceability
+
+## On Error
+
+- Missing `.rihal/templates/projects/` directory → tell the user their install is missing the module; suggest `rihal:install`
+- `sed` substitution failure (unusual characters in project name) → fall back to literal-string `awk` substitution, or ask the user to pass a simpler name via `--project-name`

package/rihal/workflows/health.md

@@ -0,0 +1,194 @@
+# Workflow: rihal:health
+
+<purpose>
+Run 6-point compliance check on rihal installation. Each check is pass/fail. Summary at the end.
+</purpose>
+
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+
+```
+/rihal:health <argument-here>
+```
+
+**Examples:**
+```
+/rihal:health example 1
+/rihal:health example 2
+```
+
+STOP — do not proceed.
+
+## Step 0 — Verify .rihal/ directory exists and is writable
+
+**Action:** Check if `.rihal/` directory exists and current user can write to it.
+
+```bash
+test -d .rihal && test -w .rihal
+```
+
+**PASS if:**
+- `.rihal/` exists
+- Current user can write to it
+
+**Output on pass:**
+```
+✅ PASS — .rihal/ directory exists and is writable
+```
+
+**Output on fail:**
+```
+❌ FAIL — .rihal/ does not exist or is not writable. Run: /rihal:update to repair
+```
+
+## Step 1 — Verify file manifest exists and is valid CSV
+
+**Action:** Check `.rihal/_config/files-manifest.csv` and parse as CSV.
+
+```bash
+test -f .rihal/_config/files-manifest.csv
+```
+
+Verify:
+- File exists
+- Header row: `rel,sha256,size`
+- At least 1 data row
+- All rows have exactly 3 columns
+
+**Output on pass:**
+```
+✅ PASS — files-manifest.csv is valid (N files tracked)
+```
+
+**Output on fail:**
+```
+❌ FAIL — files-manifest.csv is missing or corrupted. Run: /rihal:update to repair
+```
+
+## Step 2 — Verify all manifest files exist and hashes match
+
+**Action:** For each row in files-manifest.csv, check file exists and hash matches.
+
+For each file:
+- Extract: `rel`, `sha256`, `size`
+- Verify file at `./{rel}` exists
+- Compute SHA256 hash of actual file
+- Compare against manifest entry
+
+Detect drift: files that exist but hash doesn't match.
+
+**Output on pass:**
+```
+✅ PASS — All files match manifest (no drift detected)
+```
+
+**Output on fail (drift found):**
+```
+❌ FAIL — File drift detected: N files changed or missing
+  Modified: file1.md, file2.js
+  Missing: file3.md
+Run: /rihal:update to repair
+```
+
+## Step 3 — Verify state.json exists and is valid
+
+**Action:** Check `.rihal/state.json` and validate JSON structure.
+
+```bash
+test -f .rihal/state.json
+```
+
+Parse as JSON. Verify top-level keys present:
+- `version`
+- `project`
+- `created`
+- `updated`
+- `phases` (array)
+- `executions` (array)
+- `decisions` (array)
+- `blockers` (array)
+- `council_sessions` (array)
+
+**Output on pass:**
+```
+✅ PASS — state.json is valid and initialized
+```
+
+**Output on fail:**
+```
+❌ FAIL — state.json is missing or invalid. Run: /rihal:update to repair
+```
+
+## Step 4 — Verify agent-manifest.csv is present and populated
+
+**Action:** Check `.rihal/_config/agent-manifest.csv` for header and at least one agent.
+
+```bash
+test -f .rihal/_config/agent-manifest.csv
+```
+
+Verify:
+- File exists
+- Header row present
+- At least 1 data row (one agent installed)
+
+**Output on pass:**
+```
+✅ PASS — agent-manifest.csv is valid (N agents installed)
+```
+
+**Output on fail:**
+```
+❌ FAIL — agent-manifest.csv is missing or empty. Run: /rihal:update to repair
+```
+
+## Step 5 — Verify rihal-tools.cjs is executable and responsive
+
+**Action:** Check rihal-tools.cjs exists, is executable, and responds to version command.
+
+```bash
+test -f .rihal/bin/rihal-tools.cjs && test -x .rihal/bin/rihal-tools.cjs
+node .rihal/bin/rihal-tools.cjs version
+```
+
+**Output on pass:**
+```
+✅ PASS — rihal-tools.cjs is executable and responsive
+```
+
+**Output on fail:**
+```
+❌ FAIL — rihal-tools.cjs is missing or broken. Run: /rihal:update to repair
+```
+
+## Step 6 — Count results and print final summary
+
+**Action:** Count all pass/fail results and display overall status.
+
+Total: `{N}/6 checks passed`
+
+If all 6 pass:
+```
+✅ All systems nominal — rihal is healthy
+```
+
+If fewer than 6 pass:
+```
+⚠️ {N}/6 checks passed — {M} issue(s) found
+Run: /rihal:update to repair
+```
+
+## Success Criteria
+
+- [ ] All 6 checks executed
+- [ ] Each check result printed clearly
+- [ ] Final summary shows pass/fail count
+- [ ] Repair instructions shown if any checks fail
+
+## On Error
+
+- **Directory not readable:** Print error and suggest filesystem check
+- **CSV parsing fails:** Print error and suggest re-running update
+- **JSON corruption:** Print error and suggest state.json reset

package/rihal/workflows/help.md

@@ -0,0 +1,318 @@
+<purpose>
+Display the Rihal command reference at the requested tier. Output ONLY the tier section. Do NOT add project-specific analysis, git status, next-step suggestions, or any commentary beyond the reference.
+</purpose>
+
+## Step 0 — Parse arguments
+
+Read `$ARGUMENTS` and resolve to one of: `basic`, `intermediate`, `advanced`, `all`.
+
+| Input | Tier shown |
+|-------|------------|
+| (empty) or `basic` or `1` | **TIER 1 — Basic** |
+| `intermediate` or `int` or `2` | **TIER 2 — Intermediate** |
+| `advanced` or `adv` or `3` | **TIER 3 — Advanced** |
+| `all` or `full` | **All three tiers in sequence** |
+| `--help` or `-h` | Show usage block, then exit |
+
+Usage block:
+
+```
+Usage: /rihal:help [basic|intermediate|advanced|all]
+
+  basic         Show the 8 essentials (default)
+  intermediate  Show real-project ops (council, review, ship, capture)
+  advanced      Show power tools (audits, workspaces, council variants, etc.)
+  all           Show everything
+```
+
+## Step 1 — Render the requested tier
+
+Output the matching `<tier-N>` block below verbatim. For `all`, output all three blocks separated by `---`.
+
+---
+
+<tier-1>
+# Rihal — Tier 1 (Basic)
+
+> **Rihal** is council-driven project automation built for solo agentic work in Claude Code.
+> Tier 1 is everything you need to ship a small project end-to-end. **8 commands.**
+
+## The loop
+
+```
+init → new-project → plan → execute → next → status → ship
+```
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `/rihal:init` | First-time setup in this repo. Detects state, asks config questions, writes `.rihal/RIHLA.md`. Run once per project. |
+| `/rihal:new-project` | Take an idea to a planned roadmap. Questioning → optional research → REQUIREMENTS → ROADMAP. |
+| `/rihal:plan <phase>` | Create executable plans for a phase. Produces `SPRINT.md` files. |
+| `/rihal:execute <phase>` | Run all plans in a phase in dependency waves. Updates STATE on completion. |
+| `/rihal:next` | Auto-route to the next logical step based on project state. Zero friction. |
+| `/rihal:status` | Where am I — current phase, plan progress, recent decisions, blockers. |
+| `/rihal:progress` | Visual progress + intelligent suggestion for next action. |
+| `/rihal:help [tier]` | This reference. Add `intermediate`, `advanced`, or `all` for more. |
+
+## Minimal happy path
+
+```
+/rihal:init
+/rihal:new-project
+/rihal:plan 1
+/rihal:execute 1
+/rihal:next
+```
+
+## Files Rihal creates
+
+```
+.planning/
+├── PROJECT.md            # vision
+├── REQUIREMENTS.md       # scoped requirements
+├── ROADMAP.md            # phase breakdown
+├── STATE.md              # project memory
+└── phases/
+    └── 01-foundation/
+        ├── 01-01-SPRINT.md   # the plan
+        └── 01-01-SUMMARY.md  # what got done
+```
+
+**Done with Tier 1?** → `/rihal:help intermediate` for council, review, ship, and capture.
+</tier-1>
+
+---
+
+<tier-2>
+# Rihal — Tier 2 (Intermediate)
+
+> Real-project ops: strategic input, quality gates, capture, and session continuity.
+> Assumes you know Tier 1. **~18 commands.**
+
+## Strategy & input
+
+| Command | When to use |
+|---------|-------------|
+| `/rihal:council <question>` | Strategic decision needing multiple perspectives — 3-5 agents debate in parallel, 2 rounds with cross-talk. |
+| `/rihal:discuss <agent> <q>` | Quick single-agent sync — fast, conversational, no artifact. |
+| `/rihal:discuss-phase <n>` | Gather context through adaptive questioning before planning. Produces CONTEXT.md. |
+| `/rihal:explore <topic>` | Socratic ideation — think through ideas before committing to plans. |
+| `/rihal:do <description>` | Smart router — natural language in, picks the right `/rihal:*` command. |
+
+## Quality & shipping
+
+| Command | When to use |
+|---------|-------------|
+| `/rihal:code-review` | Adversarial code review of changed files — bugs, security, style. |
+| `/rihal:code-review-fix` | Auto-apply fixes from a code-review report. |
+| `/rihal:verify-phase <n>` | Goal-backward audit — does the codebase deliver what the phase promised? |
+| `/rihal:verify-work` | Conversational UAT against acceptance criteria. |
+| `/rihal:ship` | Create PR, run review, prepare for merge after verification passes. |
+
+## Phase & plan management
+
+| Command | When to use |
+|---------|-------------|
+| `/rihal:show <id>` | Print a phase or plan in full with execution status. |
+| `/rihal:add-phase <name>` | Append a new phase to the active milestone. |
+| `/rihal:insert-phase <after> <name>` | Insert urgent decimal phase (e.g. 7.1) without renumbering. |
+| `/rihal:remove-phase <n>` | Remove a future phase and renumber. |
+| `/rihal:quick [flags]` | Small ad-hoc tasks with Rihal guarantees but skip optional agents. Flags: `--discuss`, `--research`, `--full`. |
+| `/rihal:fast "<task>"` | Trivial inline task — typo, gitignore tweak, etc. No subagents, ≤3 file edits. |
+
+## Capture & session continuity
+
+| Command | When to use |
+|---------|-------------|
+| `/rihal:note "<text>"` | Zero-friction idea capture — appends to dated note file. |
+| `/rihal:add-todo [desc]` | Capture an idea or task as a todo (infers from conversation if no arg). |
+| `/rihal:check-todos [area]` | List pending todos and pick one to work on. |
+| `/rihal:plant-seed "<idea>"` | Capture a forward-looking idea with trigger conditions — surfaces at the right milestone. |
+| `/rihal:resume-work` | Restore project context after a break. |
+| `/rihal:pause-work` | Create HANDOFF.json and continue-here.md before stopping mid-phase. |
+| `/rihal:session-report` | Work summary, decisions, open blockers from this session. |
+
+**Done with Tier 2?** → `/rihal:help advanced` for audits, workspaces, milestone ops, and power variants.
+</tier-2>
+
+---
+
+<tier-3>
+# Rihal — Tier 3 (Advanced)
+
+> Power tools: milestone ops, parallel workspaces, audits, council variants, and rare ops.
+> Assumes Tier 1 + 2. Use these when you know exactly what you need.
+
+## Milestone lifecycle
+
+| Command | Use |
+|---------|-----|
+| `/rihal:new-milestone` | Start the next milestone — initializes ROADMAP, REQUIREMENTS, STATE. |
+| `/rihal:complete-milestone <ver>` | Archive milestone → move to `.planning/milestones/`. |
+| `/rihal:milestone-summary` | Human-readable summary of all phases, decisions, outcomes. |
+| `/rihal:audit-milestone` | Cross-phase audit — verify completion against original goals. |
+| `/rihal:plan-milestone-gaps` | Create phases to close gaps from the audit. |
+| `/rihal:cleanup` | Archive accumulated phase dirs from completed milestones. |
+
+## Workspaces & parallel work
+
+| Command | Use |
+|---------|-----|
+| `/rihal:new-workspace` | Isolated workspace with separate ROADMAP/STATE for parallel work. |
+| `/rihal:list-workspaces` | List all active workspaces. |
+| `/rihal:remove-workspace` | Delete a workspace and clean up artifacts. |
+| `/rihal:workstream` | Manage parallel workstreams (milestone tracks). |
+
+## Audits & specialty review
+
+| Command | Use |
+|---------|-----|
+| `/rihal:secure-phase <n>` | Retroactively verify threat mitigations exist in code. |
+| `/rihal:validate-phase <n>` | Audit Nyquist validation gaps for a completed phase. |
+| `/rihal:add-tests <n>` | Generate unit + E2E tests based on SPRINT/SUMMARY/CONTEXT. |
+| `/rihal:audit-uat` | Cross-phase audit of all outstanding UAT items. |
+| `/rihal:audit-fix` | Autonomous audit-to-fix pipeline — find, classify, fix, test, commit. |
+| `/rihal:karpathy-audit` | Audit recent code against Karpathy's 4 LLM coding principles. |
+| `/rihal:ui-phase <n>` | Generate UI design contract (UI-SPEC.md) for frontend phases. |
+| `/rihal:ui-review` | Retroactive 6-pillar visual audit of completed UI work. |
+| `/rihal:review-adversarial` | Hostile-perspective report — vulnerabilities, race conditions, abuse. |
+| `/rihal:review-edge-case-hunter` | Enumerate edge cases by category and severity. |
+| `/rihal:review` | Cross-AI peer review — invoke external AI CLIs to review plans. |
+
+## Council variants & strategy power tools
+
+| Command | Use |
+|---------|-----|
+| `/rihal:discuss-phase-power` | Bulk question generation with async UI for context-heavy phases. |
+| `/rihal:chain <preset> <topic>` | Sequential agent pipeline (research → scope → build), typed artifacts. |
+| `/rihal:brainstorm` | Guided brainstorming — pick a method, generate ideas systematically. |
+| `/rihal:why <decision>` | Explain reasoning behind a decision, classification, or panel pick. |
+
+## Document, scaffold, integrate
+
+| Command | Use |
+|---------|-----|
+| `/rihal:map-codebase` | Brownfield: parallel Explore agents → 7 codebase docs. |
+| `/rihal:scan` | Rapid codebase assessment — lighter than map-codebase. |
+| `/rihal:document-project` | Audit missing/stale docs, file SPRINT tasks for each gap. |
+| `/rihal:docs-update` | Generate or update docs verified against codebase. |
+| `/rihal:install <module>` | Install a Rihal capability bundle into the project. |
+| `/rihal:enable-hooks` | Install optional Rihal hooks into `.claude/settings.json`. |
+| `/rihal:scaffold-project` | Scaffold a new project from the official Rihal template. |
+| `/rihal:bootstrap` | Bootstrap repo with Vercel-linked resources and integrations. |
+
+## Story-level epics workflow
+
+| Command | Use |
+|---------|-----|
+| `/rihal:create-prd` | Create a PRD from scratch through guided facilitation. |
+| `/rihal:edit-prd` | Update an existing PRD with revisions or clarifications. |
+| `/rihal:validate-prd` | Validate an existing PRD for completeness and consistency. |
+| `/rihal:create-epics-and-stories` | Parse a PRD into numbered epic + story files. |
+| `/rihal:create-story` | Prepare a dev-ready STORY.md with full implementation context. |
+| `/rihal:dev-story <file>` | Execute an approved STORY by writing tests + code per AC. |
+| `/rihal:check-implementation-readiness` | Verify PRD + architecture + epics aligned before build. |
+| `/rihal:create-architecture` | Write an Architecture Decision Record (ADR). |
+| `/rihal:create-ux-design` | Realize a UX design that informs architecture and implementation. |
+| `/rihal:correct-course` | Course-correct mid-sprint when major change is discovered. |
+| `/rihal:sprint-planning` | Compute capacity, prioritize stories, create SPRINT.md. |
+| `/rihal:sprint-status` | Sprint progress — stories, points, velocity, burndown. |
+| `/rihal:list-plans` | Table of every SPRINT.md across phases — goal, stories, points, state. |
+| `/rihal:decisions` | Browse decisions across every Rihal project (~/.rihal/decisions.jsonl). |
+| `/rihal:replay <slug>` | Re-run a past council session with the same question — fresh panel round. |
+| `/rihal:export-to-github` | Push phases/stories/decisions to GitHub issues (wraps `rihal-code github-sync`). |
+| `/rihal:notify-test` | Verify Slack/Discord/MS Teams webhook wiring — posts a test message. |
+| `/rihal:from-template <type>` | Seed .planning/ from a starter template (saas-b2b, api-backend, mobile-app). |
+| `/rihal:retrospective` | Run an epic retrospective and produce owned action items. |
+
+## Operational / rare
+
+| Command | Use |
+|---------|-----|
+| `/rihal:debug "<issue>"` | Systematic debugging with persistent state across `/clear`. |
+| `/rihal:forensics` | Diagnose incomplete executions — timeline of what broke. |
+| `/rihal:undo <id>` | Safe git revert for a phase or plan with dependency checks. |
+| `/rihal:rerun <id>` | Re-execute a phase or plan, resetting state, fresh commits. |
+| `/rihal:diff <a> <b>` | Show changes to plans and state between commits. |
+| `/rihal:import <path>` | Ingest external plans with conflict detection against decisions. |
+| `/rihal:inbox` | Triage incoming issues and PRs against contribution templates. |
+| `/rihal:pr-branch` | Create clean PR branch — filter out `.planning/` commits. |
+| `/rihal:autonomous` | Run remaining phases autonomously — plan → execute → verify cycles. |
+| `/rihal:research-phase <n>` | Standalone research (usually use `/rihal:plan` instead). |
+| `/rihal:analyze-dependencies` | Suggest "Depends on" entries for ROADMAP.md. |
+| `/rihal:list-phase-assumptions <n>` | Surface agent's intended approach before planning. |
+| `/rihal:profile-user` | Classify developer on 4 dimensions, produce profile artifact. |
+| `/rihal:dashboard` | Start the Diwan view-only dashboard (port 7717). |
+| `/rihal:health` | 6-point health check of the Rihal installation. |
+| `/rihal:stats` | Phases, plans, decisions, council sessions, timeline. |
+| `/rihal:settings` | Interactive config wizard — model profile, gates, branching. |
+| `/rihal:config` | View or edit Rihal configuration directly. |
+| `/rihal:update` | Update Rihal to latest version with changelog preview. |
+| `/rihal:note` | (also Tier 2) Inline note capture. |
+
+## Common compound flows
+
+**New project (full quality):**
+```
+/rihal:new-project → /clear → /rihal:plan 1 → /clear → /rihal:execute 1 → /rihal:verify-phase 1 → /rihal:ship
+```
+
+**Mid-milestone urgent work:**
+```
+/rihal:insert-phase 5 "Critical security fix" → /rihal:plan 5.1 → /rihal:execute 5.1
+```
+
+**Resume after break:**
+```
+/rihal:resume-work   # or just /rihal:next
+```
+
+**Debug across context resets:**
+```
+/rihal:debug "form submission fails" → ...investigation... → /clear → /rihal:debug   # resumes
+```
+
+**Complete + start next milestone:**
+```
+/rihal:audit-milestone → /rihal:plan-milestone-gaps → /rihal:complete-milestone 1.0.0 → /rihal:new-milestone
+```
+
+## Configuration reference
+
+`.planning/config.json`:
+
+```json
+{
+  "mode": "interactive",            // or "yolo"
+  "planning": {
+    "commit_docs": true,            // false = .planning/ kept local
+    "search_gitignored": false      // true = ripgrep with --no-ignore
+  }
+}
+```
+
+## Where to find context
+
+- `.planning/PROJECT.md` — vision
+- `.planning/STATE.md` — current memory
+- `.planning/ROADMAP.md` — phase status
+- `.planning/RETROSPECTIVE.md` — living retrospective
+- `.planning/codebase/` — brownfield maps (STACK, ARCHITECTURE, etc.)
+
+**End of reference.**
+</tier-3>
+
+## Success Criteria
+
+- [ ] Correct tier section is rendered based on `$ARGUMENTS`
+- [ ] No extra analysis, commentary, or project state added
+- [ ] "Next tier" pointer present at end of Tier 1 and Tier 2
+- [ ] `all` renders all three tiers separated by `---`
+- [ ] Unknown args fall back to Tier 1 silently (do not error)
+
+## On Error
+
+- If unable to load or render reference: display fallback `See rihal/workflows/help.md for full reference`
+- Handle missing sections gracefully without breaking output