convoke-agents 2.4.0 → 3.0.1

package/_bmad/bme/_gyre/guides/ATLAS-USER-GUIDE.md

@@ -0,0 +1,177 @@
+# Atlas 📐 User Guide
+
+**(model-curator.md)**
+
+- **Version:** 1.0.0
+- **Module:** Gyre Pattern (Production Readiness)
+- **Last Updated:** 2026-03-24
+
+---
+
+## Quick Start
+
+**Who is Atlas?** Atlas is a knowledgeable curator who generates a capabilities manifest unique to your project's detected tech stack. Atlas combines industry standards (DORA, OpenTelemetry, Google PRR), current best practices from web research, and your guard question answers to build a model of what production readiness looks like *for your specific project* — not a generic checklist.
+
+**When to use Atlas:**
+
+- Scout has produced a Stack Profile and you need a capabilities model
+- You want to regenerate the model after amending it through Coach
+- You need to validate model accuracy against a known stack
+
+**Atlas vs Other Gyre Agents:**
+
+| If you want to... | Use... |
+|---|---|
+| Know what tech stack a project uses | **Scout** 🔎 |
+| Generate a capabilities model for that stack | **Atlas** 📐 |
+| Find what's missing from the project | **Lens** 🔬 |
+| Review and refine the findings | **Coach** 🏋️ |
+
+**What you'll get:** A Capabilities Manifest (`.gyre/capabilities.yaml`) with 20+ capabilities across observability, deployment, reliability, and security domains — each with a plain-language description.
+
+---
+
+## How to Invoke
+
+**Claude Code (skills) — recommended:**
+
+```
+/bmad-agent-bme-model-curator
+```
+
+**Claude Code (terminal) / Other AI assistants:**
+
+```bash
+cat _bmad/bme/_gyre/agents/model-curator.md
+```
+
+**Claude.ai:**
+
+Open `_bmad/bme/_gyre/agents/model-curator.md` and paste its contents into your conversation.
+
+---
+
+## Menu Options
+
+| # | Code | Description |
+|---|------|-------------|
+| 1 | **MH** | Redisplay Menu Help |
+| 2 | **CH** | Chat with Atlas about capabilities and models |
+| 3 | **GM** | Generate Model — build a capabilities manifest from the Stack Profile |
+| 4 | **AV** | Accuracy Validation — validate model quality against test repos |
+| 5 | **FA** | Full Analysis — run the complete Gyre pipeline |
+| 6 | **PM** | Start Party Mode |
+| 7 | **DA** | Dismiss Agent |
+
+Select by number, code, or fuzzy text match.
+
+---
+
+## Workflows
+
+### [GM] Generate Model
+
+Loads the Stack Profile (GC1) and generates a contextual capabilities manifest tailored to your project's tech stack.
+
+- **Prerequisite:** `.gyre/stack-profile.yaml` must exist (run Scout first)
+- **Output:** `.gyre/capabilities.yaml` (GC2 contract)
+- **When to use:** After stack detection, or when regenerating the model
+
+**How Atlas generates capabilities:**
+
+1. **Load profile** — reads Stack Profile and checks for existing amendments from Coach (GC4)
+2. **Generate capabilities** — uses stack context + industry standards (DORA metrics, OpenTelemetry, Google PRR) to produce domain-specific capabilities
+3. **Web enrichment** — searches for current best practices relevant to your stack
+4. **Write manifest** — produces the final capabilities.yaml
+
+**Capability domains:** observability (6-10 capabilities), deployment (5-8), reliability (4-6), security (3-5).
+
+**Capability sources:**
+
+- **standard** — derived from industry standards (DORA, OTel, PRR)
+- **practice** — discovered via web search for current best practices
+- **reasoning** — inferred from stack context by Atlas
+
+**Limited coverage warning:** If fewer than 20 capabilities are generated, Atlas surfaces a warning and offers you the choice to continue or abort.
+
+**Amendment respect:** When regenerating, Atlas preserves your previous Coach amendments — removed capabilities stay removed, edited descriptions stay edited.
+
+### [AV] Accuracy Validation
+
+Validates model quality by scoring capabilities against synthetic ground truth across multiple stack archetypes.
+
+- **Output:** Accuracy report with per-archetype scores
+- **When to use:** Quality gate before trusting the model for gap analysis
+
+**Scoring:**
+
+- 1.0 = Relevant (appropriate for this stack)
+- 0.5 = Partially relevant (tangential or poorly described)
+- 0.0 = Irrelevant (no relation to stack)
+
+**Gate:** Must achieve ≥70% accuracy across ≥3 stack archetypes. If any archetype falls below 70%, Atlas iterates.
+
+### [FA] Full Analysis
+
+Same as Scout's Full Analysis — runs the complete pipeline. Atlas handles step 3 (model generation).
+
+---
+
+## Philosophy
+
+- **Context over generic** — Every capability is relevant to *this* stack. Atlas doesn't dump a universal checklist; it reasons about what matters for Node.js on Kubernetes differently than Python on ECS.
+- **Standards inform, they don't dictate** — DORA and OpenTelemetry are starting points, not requirements. Atlas adapts to your project's actual architecture.
+- **Transparency** — Each capability shows its source (standard, practice, or reasoning) so you know where it came from and can judge accordingly.
+- **Team ownership** — The capabilities manifest belongs to your team. Amendments persist. The model improves with use.
+
+---
+
+## Chat with Atlas
+
+Use **[CH]** to discuss model generation topics:
+
+- "Why did you include distributed tracing for my project?"
+- "What DORA metrics are relevant to my stack?"
+- "Can you explain the difference between standard and practice sources?"
+- "My project is a CLI tool, not a web service — should I regenerate?"
+
+---
+
+## Troubleshooting
+
+**"GC1 not found" error**
+
+Atlas requires a Stack Profile to generate the model. Run Scout's **[DS]** workflow first, then return to Atlas.
+
+**Model seems too generic**
+
+Check that Scout's guard answers are accurate — Atlas uses them to tune the model. If guard answers are wrong or missing, re-run Scout's **[DS]** with corrected answers, then regenerate.
+
+**Fewer than 20 capabilities generated**
+
+Atlas surfaces a limited-coverage warning. This can happen with unusual or very simple stacks. You can continue (the model is still useful) or abort and check if Scout's stack classification is accurate.
+
+**Amendments disappeared after regeneration**
+
+Atlas reads GC4 (Coach amendments) before regenerating. If amendments are missing, check that `.gyre/capabilities.yaml` contains the `amended` and `removed` flags from your last Coach review.
+
+---
+
+## Tips
+
+- **Don't skip Scout.** Atlas needs the Stack Profile as input. Running Atlas without it produces an error, not a generic model.
+- **Web search results are fresh.** Atlas searches for current-year best practices every time — no stale caches. This means models improve naturally over time.
+- **Regeneration preserves your work.** Coach amendments survive regeneration. You don't lose your customizations when the model updates.
+- **Capabilities.yaml IS the cache.** In anticipation mode, Atlas's model is reused rather than regenerated. This is by design — the model is stable until you explicitly regenerate.
+
+---
+
+## Credits
+
+- **Agent:** Atlas (Model Curator)
+- **Module:** Gyre Pattern v1.0.0
+- **Pattern:** Convoke Agent Architecture
+
+---
+
+*Scout finds the facts. Atlas builds the model. Lens finds the gaps. Coach helps you act on them.*

package/_bmad/bme/_gyre/guides/COACH-USER-GUIDE.md

@@ -0,0 +1,172 @@
+# Coach 🏋️ User Guide
+
+**(review-coach.md)**
+
+- **Version:** 1.0.0
+- **Module:** Gyre Pattern (Production Readiness)
+- **Last Updated:** 2026-03-24
+
+---
+
+## Quick Start
+
+**Who is Coach?** Coach is a patient guide who walks you through your capabilities model and findings. Coach never pushes — it presents options and respects your expertise. Through conversational review, you can amend capabilities, adjust findings, and capture feedback that improves the model for your entire team.
+
+**When to use Coach:**
+
+- Lens has produced findings and you want to review them
+- You want to customize the capabilities model (remove irrelevant capabilities, add missing ones)
+- You want to capture feedback about gaps Gyre missed
+
+**Coach vs Other Gyre Agents:**
+
+| If you want to... | Use... |
+|---|---|
+| Know what tech stack a project uses | **Scout** 🔎 |
+| Generate a capabilities model for that stack | **Atlas** 📐 |
+| Find what's missing from the project | **Lens** 🔬 |
+| Review and refine the findings | **Coach** 🏋️ |
+
+**What you'll get:** An amended capabilities manifest, reviewed findings, and feedback captured in `.gyre/feedback.yaml` — all persisted for future runs.
+
+---
+
+## How to Invoke
+
+**Claude Code (skills) — recommended:**
+
+```
+/bmad-agent-bme-review-coach
+```
+
+**Claude Code (terminal) / Other AI assistants:**
+
+```bash
+cat _bmad/bme/_gyre/agents/review-coach.md
+```
+
+**Claude.ai:**
+
+Open `_bmad/bme/_gyre/agents/review-coach.md` and paste its contents into your conversation.
+
+---
+
+## Menu Options
+
+| # | Code | Description |
+|---|------|-------------|
+| 1 | **MH** | Redisplay Menu Help |
+| 2 | **CH** | Chat with Coach about findings and customization |
+| 3 | **RF** | Review Findings — walk through Lens's findings |
+| 4 | **RM** | Review Model — walk through Atlas's capabilities |
+| 5 | **FA** | Full Analysis — run the complete Gyre pipeline |
+| 6 | **PM** | Start Party Mode |
+| 7 | **DA** | Dismiss Agent |
+
+Select by number, code, or fuzzy text match.
+
+---
+
+## Workflows
+
+### [RF] Review Findings
+
+Walk through Lens's findings severity-first — blockers, then recommended, then nice-to-have. Amend capabilities and capture feedback.
+
+### [RM] Review Model
+
+Walk through Atlas's capabilities manifest — keep, remove, edit, or add capabilities to tailor the model to your project.
+
+Both RF and RM invoke the same model-review workflow. Coach asks which mode you want, or you can do both in sequence.
+
+- **Prerequisite:** `.gyre/capabilities.yaml` (GC2) required; `.gyre/findings.yaml` (GC3) required for findings review
+- **Output:** Amended capabilities.yaml + `.gyre/feedback.yaml` (GC4 contract)
+- **When to use:** After Lens produces findings, or any time you want to refine the model
+
+**Review flow:**
+
+1. **Load context** — reads artifacts, displays any existing feedback, checks for deferred reviews
+2. **Walkthrough** — walks through each capability or finding. For each item: keep, remove, edit, or add new
+3. **Apply amendments** — writes changes directly to capabilities.yaml with amendment flags (`amended`, `removed`, timestamps)
+4. **Capture feedback** — prompts "Did Gyre miss anything you know about?" Persists responses to `.gyre/feedback.yaml` with timestamp
+5. **Summary** — presents review summary and Compass routing to next agent
+
+**Findings are presented severity-first:** blockers, then recommended, then nice-to-have. You see the most critical items first.
+
+**Amendment types:**
+
+| Action | What happens |
+|---|---|
+| **Keep** | Capability unchanged |
+| **Remove** | Capability flagged `removed: true` with timestamp. Excluded from future analysis. |
+| **Edit** | Description or category updated. Original values preserved with `amended: true`. |
+| **Add** | New capability added with `source: user-added`. Included in future analysis. |
+
+**Feedback types:** missed-capability, missed-gap, severity-adjustment, other.
+
+**Team benefit:** Coach explains that `feedback.yaml` should be committed to your repo. When teammates run Gyre, their analysis benefits from your amendments and feedback.
+
+### [FA] Full Analysis
+
+Same as Scout's Full Analysis — runs the complete pipeline. Coach handles step 5 (review).
+
+---
+
+## Philosophy
+
+- **Your expertise wins** — Coach presents information and options. It never argues that you should keep a capability you want to remove. You know your project better than any model.
+- **Non-destructive amendments** — Removals are flags, not deletions. Original values are preserved. Nothing is lost, and amendments can be reversed.
+- **Feedback compounds** — Every review makes the model better for the next person. Feedback persists across runs and across team members.
+- **Deferral is fine** — If you're not ready to review, Coach records a "review deferred" flag and reminds you on the next run. No pressure.
+
+---
+
+## Chat with Coach
+
+Use **[CH]** to discuss review topics:
+
+- "Should I remove capabilities that my project doesn't need yet?"
+- "How do amendments affect future Gyre runs?"
+- "What happens to my feedback when Atlas regenerates the model?"
+- "Can my team members see and build on my amendments?"
+
+---
+
+## Troubleshooting
+
+**"GC2 not found" or "GC3 not found" error**
+
+Coach needs the capabilities manifest for model review and the findings report for findings review. Run Atlas and/or Lens first, then return to Coach.
+
+**I accidentally removed a capability I need**
+
+Amendments are flags, not deletions. The original capability is still in capabilities.yaml with `removed: true`. Edit the YAML directly to remove the flag, or ask Coach to re-add it.
+
+**Feedback not showing on next run**
+
+Coach displays existing feedback at the start of each review. Check that `.gyre/feedback.yaml` exists and was committed to your repo if working across branches.
+
+**Review feels overwhelming**
+
+You don't have to review everything in one session. Coach supports deferral — stop when you need to and resume later. Blockers-first ordering means you always see the most important items first.
+
+---
+
+## Tips
+
+- **Review findings before the model.** Findings give you context about which capabilities matter for your project. Reviewing the model cold is harder.
+- **Commit `.gyre/feedback.yaml` to your repo.** This is how your team shares Gyre improvements. Feedback from one person's review benefits everyone.
+- **Use "missed-gap" feedback liberally.** If you know about a gap Gyre didn't catch, tell Coach. This is the primary mechanism for model improvement.
+- **Amendments persist through regeneration.** When Atlas rebuilds the model, your removals and edits are preserved. Don't worry about losing your customizations.
+
+---
+
+## Credits
+
+- **Agent:** Coach (Review Coach)
+- **Module:** Gyre Pattern v1.0.0
+- **Pattern:** Convoke Agent Architecture
+
+---
+
+*Scout finds the facts. Atlas builds the model. Lens finds the gaps. Coach helps you act on them.*

package/_bmad/bme/_gyre/guides/LENS-USER-GUIDE.md

@@ -0,0 +1,181 @@
+# Lens 🔬 User Guide
+
+**(readiness-analyst.md)**
+
+- **Version:** 1.0.0
+- **Module:** Gyre Pattern (Production Readiness)
+- **Last Updated:** 2026-03-24
+
+---
+
+## Quick Start
+
+**Who is Lens?** Lens is a thorough analyst who compares your capabilities manifest against what actually exists in your project. Lens detects *absences* — capabilities that should be present for your stack but aren't — and surfaces cross-domain patterns where gaps compound each other's risk.
+
+**When to use Lens:**
+
+- Atlas has generated a capabilities model and you want to find gaps
+- You've made changes to your project and want to see what's improved (delta report)
+- You need a severity-prioritized view of what's missing
+
+**Lens vs Other Gyre Agents:**
+
+| If you want to... | Use... |
+|---|---|
+| Know what tech stack a project uses | **Scout** 🔎 |
+| Generate a capabilities model for that stack | **Atlas** 📐 |
+| Find what's missing from the project | **Lens** 🔬 |
+| Review and refine the findings | **Coach** 🏋️ |
+
+**What you'll get:** A Findings Report (`.gyre/findings.yaml`) with absence-based findings tagged by severity, confidence, and source — plus cross-domain compound findings that show how gaps amplify each other.
+
+---
+
+## How to Invoke
+
+**Claude Code (skills) — recommended:**
+
+```
+/bmad-agent-bme-readiness-analyst
+```
+
+**Claude Code (terminal) / Other AI assistants:**
+
+```bash
+cat _bmad/bme/_gyre/agents/readiness-analyst.md
+```
+
+**Claude.ai:**
+
+Open `_bmad/bme/_gyre/agents/readiness-analyst.md` and paste its contents into your conversation.
+
+---
+
+## Menu Options
+
+| # | Code | Description |
+|---|------|-------------|
+| 1 | **MH** | Redisplay Menu Help |
+| 2 | **CH** | Chat with Lens about analysis and findings |
+| 3 | **AG** | Analyze Gaps — compare capabilities against what exists |
+| 4 | **DR** | Delta Report — track progress between analysis runs |
+| 5 | **FA** | Full Analysis — run the complete Gyre pipeline |
+| 6 | **PM** | Start Party Mode |
+| 7 | **DA** | Dismiss Agent |
+
+Select by number, code, or fuzzy text match.
+
+---
+
+## Workflows
+
+### [AG] Analyze Gaps
+
+Loads the Capabilities Manifest (GC2) and searches the project filesystem for evidence of each capability. Produces a severity-prioritized findings report.
+
+- **Prerequisite:** `.gyre/capabilities.yaml` must exist (run Atlas first)
+- **Output:** `.gyre/findings.yaml` (GC3 contract)
+- **When to use:** After model generation, or after significant project changes
+
+**How Lens analyzes:**
+
+1. **Load manifest** — reads the capabilities model
+2. **Observability analysis** — searches for observability evidence (logging, metrics, tracing, alerting)
+3. **Deployment analysis** — searches for deployment evidence (CI/CD, containerization, environment config, rollback)
+4. **Cross-domain correlation** — identifies compound patterns where gaps in different domains amplify each other
+5. **Present findings** — severity-first summary with blockers, recommended, and nice-to-have counts
+
+**Finding tags:**
+
+| Tag | Meaning |
+|---|---|
+| **Severity** | blocker / recommended / nice-to-have |
+| **Source** | static-analysis (file evidence) or contextual-model (inferred from model) |
+| **Confidence** | high / medium / low |
+
+Each finding includes a brief rationale for its severity classification.
+
+**Compound findings:** Lens identifies cross-domain patterns — for example, "no health checks" + "no deployment rollback" is a compound risk where each gap makes the other more dangerous. Compound findings are suppressed when either component has low confidence.
+
+**Novelty ratio:** Lens reports what proportion of findings come from the contextual model vs static analysis ("X of Y findings are contextual"), so you know how much of the analysis is evidence-based vs model-driven.
+
+### [DR] Delta Report
+
+Compares current findings against a previous analysis run to show what changed.
+
+- **Prerequisite:** `.gyre/findings.yaml` must exist from a previous run
+- **Output:** Delta analysis with change tags
+- **When to use:** After making improvements, to track progress
+
+**Delta tags:**
+
+- **[NEW]** — Finding appeared since last run
+- **[CARRIED]** — Finding persists from previous run
+- **Resolved** — Finding from previous run no longer present (you fixed it)
+
+On first run, all findings are tagged [NEW] and saved as the baseline for future comparisons.
+
+### [FA] Full Analysis
+
+Same as Scout's Full Analysis — runs the complete pipeline. Lens handles step 4 (gap analysis).
+
+---
+
+## Philosophy
+
+- **Absences, not misconfigurations** — Lens looks for what's missing, not what's wrong with what exists. A missing health check is a finding; a misconfigured health check is not Gyre's scope.
+- **Evidence-based honesty** — Every finding shows its source and confidence level. Lens doesn't inflate severity to look thorough.
+- **Compound thinking** — Individual gaps are important, but gaps that amplify each other are critical. Lens surfaces these relationships explicitly.
+- **Progress, not perfection** — The delta report exists because production readiness is a journey. Tracking resolved findings is as important as finding new ones.
+
+---
+
+## Chat with Lens
+
+Use **[CH]** to discuss analysis topics:
+
+- "Why is this finding marked as a blocker?"
+- "What evidence would you need to see to resolve this finding?"
+- "Can you explain the compound relationship between these two gaps?"
+- "My project is internal-only — should security findings still be blockers?"
+
+---
+
+## Troubleshooting
+
+**"GC2 not found" error**
+
+Lens requires a Capabilities Manifest. Run Atlas's **[GM]** workflow first, then return to Lens.
+
+**Too many findings, hard to prioritize**
+
+Start with blockers only — these are the gaps with the highest risk. Use Coach to review and potentially downgrade findings that aren't relevant to your context.
+
+**Delta report shows all [NEW]**
+
+This is expected on the first run. The current findings become the baseline. Run **[DR]** again after your next analysis to see meaningful deltas.
+
+**Findings seem wrong for my project**
+
+The findings depend on Atlas's capabilities model. If the model includes irrelevant capabilities, use Coach to remove them. Lens will exclude removed capabilities on re-analysis.
+
+---
+
+## Tips
+
+- **Read the severity rationale.** Lens provides a brief explanation for every severity classification. If you disagree, Coach lets you adjust.
+- **Compound findings are your highest-value signal.** They reveal systemic gaps that individual findings miss. Pay attention to these.
+- **Run delta reports after sprints.** Tracking resolved findings over time gives leadership visibility into readiness progress.
+- **The novelty ratio tells you how much to trust.** A high contextual ratio means the model is doing more inference and less evidence-finding. Consider whether the model needs refining through Coach.
+
+---
+
+## Credits
+
+- **Agent:** Lens (Readiness Analyst)
+- **Module:** Gyre Pattern v1.0.0
+- **Pattern:** Convoke Agent Architecture
+
+---
+
+*Scout finds the facts. Atlas builds the model. Lens finds the gaps. Coach helps you act on them.*

package/_bmad/bme/_gyre/guides/SCOUT-USER-GUIDE.md

@@ -0,0 +1,158 @@
+# Scout 🔎 User Guide
+
+**(stack-detective.md)**
+
+- **Version:** 1.0.0
+- **Module:** Gyre Pattern (Production Readiness)
+- **Last Updated:** 2026-03-24
+
+---
+
+## Quick Start
+
+**Who is Scout?** Scout is a methodical investigator who detects your project's technology stack by analyzing filesystem artifacts — package manifests, config files, IaC templates, CI/CD definitions. Scout builds a structured profile of what your project actually uses, not what someone documented months ago.
+
+**When to use Scout:**
+
+- You're starting a Gyre analysis on a new project
+- You need a structured inventory of a project's tech stack
+- You want to confirm or correct assumptions about what technologies are in use
+
+**Scout vs Other Gyre Agents:**
+
+| If you want to... | Use... |
+|---|---|
+| Know what tech stack a project uses | **Scout** 🔎 |
+| Generate a capabilities model for that stack | **Atlas** 📐 |
+| Find what's missing from the project | **Lens** 🔬 |
+| Review and refine the findings | **Coach** 🏋️ |
+
+**What you'll get:** A Stack Profile (`.gyre/stack-profile.yaml`) covering primary language/framework, container orchestration, CI/CD platform, observability tooling, cloud provider, and communication protocols.
+
+---
+
+## How to Invoke
+
+**Claude Code (skills) — recommended:**
+
+```
+/bmad-agent-bme-stack-detective
+```
+
+**Claude Code (terminal) / Other AI assistants:**
+
+```bash
+cat _bmad/bme/_gyre/agents/stack-detective.md
+```
+
+**Claude.ai:**
+
+Open `_bmad/bme/_gyre/agents/stack-detective.md` and paste its contents into your conversation.
+
+---
+
+## Menu Options
+
+| # | Code | Description |
+|---|------|-------------|
+| 1 | **MH** | Redisplay Menu Help |
+| 2 | **CH** | Chat with Scout about stack detection |
+| 3 | **DS** | Detect Stack — scan the project and build a Stack Profile |
+| 4 | **FA** | Full Analysis — run the complete Gyre pipeline (Scout → Atlas → Lens → Coach) |
+| 5 | **PM** | Start Party Mode |
+| 6 | **DA** | Dismiss Agent |
+
+Select by number, code, or fuzzy text match (e.g., "detect" matches DS).
+
+---
+
+## Workflows
+
+### [DS] Detect Stack
+
+Scans the project filesystem for technology indicators and produces a classified Stack Profile.
+
+- **Output:** `.gyre/stack-profile.yaml` (GC1 contract)
+- **When to use:** Starting a new Gyre analysis, or re-detecting after significant project changes
+
+**What Scout detects:**
+
+- Primary language/framework (package.json, go.mod, requirements.txt, Cargo.toml, pom.xml)
+- Container orchestration (Dockerfile, docker-compose.yaml, Kubernetes manifests, ECS task definitions)
+- CI/CD platform (.github/workflows/, .gitlab-ci.yml, Jenkinsfile)
+- Observability tooling (OpenTelemetry, Prometheus, Datadog configs)
+- Cloud provider (Terraform, CloudFormation, Pulumi templates)
+- Communication protocols (gRPC protos, REST controllers, message queues)
+
+**Guard questions:** After detection, Scout asks up to 3 targeted questions to resolve ambiguities. If detection is unambiguous, guard questions are skipped. You can correct any answer without re-running the full scan.
+
+**Monorepo support:** If Scout detects multiple service boundaries, it asks you to select which service to analyze.
+
+### [FA] Full Analysis
+
+Orchestrates the complete Gyre pipeline across all 4 agents. Scout handles initialization and detection (steps 1-2), then hands off to Atlas, Lens, and Coach in sequence.
+
+- **Output:** Complete `.gyre/` directory with all artifacts
+- **When to use:** First time running Gyre on a project, or when you want the full end-to-end experience
+
+**Modes:**
+
+- **Crisis** — No `.gyre/` directory exists. Full pipeline runs from scratch.
+- **Anticipation** — Previous analysis exists. Model generation is skipped (capabilities.yaml serves as cache). Only gap analysis and review run.
+- **Regeneration** — You explicitly ask to regenerate. Fresh model generation replaces the cached manifest.
+
+---
+
+## Philosophy
+
+- **Evidence over assumption** — Scout reports what it finds in the filesystem, not what it expects to find. Every classification is backed by a file reference.
+- **Categories, not contents** — The Stack Profile records technology categories only. No file contents, paths, version numbers, or secrets ever enter `.gyre/` artifacts.
+- **Minimal questions** — Guard questions are derived from detection gaps, not a generic questionnaire. If detection is clean, Scout doesn't waste your time.
+
+---
+
+## Chat with Scout
+
+Use **[CH]** to discuss stack detection topics:
+
+- "What indicators do you look for to detect Kubernetes?"
+- "My project uses both Python and Go — how do you handle that?"
+- "Why did you classify my project as AWS when we also use some GCP?"
+- "What's the difference between crisis and anticipation mode?"
+
+---
+
+## Troubleshooting
+
+**Scout can't find my tech stack**
+
+Scout relies on filesystem artifacts (package manifests, config files). If your project uses non-standard locations or custom tooling, use the guard questions to correct the classification manually.
+
+**`.gyre/` directory already exists but I want a fresh start**
+
+Delete the `.gyre/` directory and run **[DS]** or **[FA]** again. Scout will detect crisis mode and run the full pipeline from scratch.
+
+**Multiple stacks detected, wrong one selected as primary**
+
+Scout surfaces secondary stacks as a warning and lets you confirm or override via guard questions. If the wrong stack was selected, correct it in the guard answer — Scout re-classifies without re-scanning.
+
+---
+
+## Tips
+
+- **Start with Full Analysis [FA] your first time.** It orchestrates the entire pipeline so you see the complete Gyre experience. Use individual workflows once you're familiar.
+- **Guard answers matter downstream.** Atlas uses your guard answers to tune the capabilities model. Accurate answers here mean more relevant findings later.
+- **Re-detect after major changes.** If you add Kubernetes, switch CI providers, or adopt a new observability stack, re-run **[DS]** to update the Stack Profile before re-analyzing.
+- **Privacy is built in.** Scout's Stack Profile contains technology categories only — safe to commit to your repo for team-wide use.
+
+---
+
+## Credits
+
+- **Agent:** Scout (Stack Detective)
+- **Module:** Gyre Pattern v1.0.0
+- **Pattern:** Convoke Agent Architecture
+
+---
+
+*Scout finds the facts. Atlas builds the model. Lens finds the gaps. Coach helps you act on them.*