@fluentcommerce/ai-skills 0.13.0 → 0.14.0

package/content/knowledge/platform/permissions-and-contexts.md

@@ -234,10 +234,10 @@ A single role assignment can carry **multiple contexts** — e.g., one FINANCE_U
 User A1 has ADMIN role at RETAILER context for Retailer 1 → can access Retailer 1 data only.
 
 **Example 2 — Admin access to multiple retailers:**
-User A2 has ADMIN role at RETAILER context for Retailer 1 AND Retailer 2 → can access both. The context switcher in the UI allows filtering by retailer.
+User A2 has ADMIN role at RETAILER context for Retailer 1 AND Retailer 2 → can access both. The context switcher in the UI allows filtering by retailer. See [mystique-routing.md § Context Switching](mystique-routing.md#context-switching--default-location--retailer-via-url-parameter) for URL parameter deep-linking (`user.retailer.ref`) and localStorage persistence.
 
 **Example 3 — Store access to specific locations:**
-User S1 has STORE_ASSISTANT role at AGENT context for Location 1 AND Location 2 under Retailer 1 → can access Retailer 1 data filtered to those two locations. The context switcher filters by retailer-specific data (fulfilments only).
+User S1 has STORE_ASSISTANT role at AGENT context for Location 1 AND Location 2 under Retailer 1 → can access Retailer 1 data filtered to those two locations. The context switcher filters by retailer-specific data (fulfilments only). See [mystique-routing.md § Context Switching](mystique-routing.md#context-switching--default-location--retailer-via-url-parameter) for URL parameter deep-linking (`user.location.ref`) and localStorage persistence.
 
 ### Decision guide: Setting up a new user
 

package/content/knowledge/platform/rule-test-patterns.md

@@ -2,7 +2,7 @@
 name: rule-test-patterns
 description: "Reusable test patterns for Fluent Commerce Rubix backend rules: RuleExecutor, TestExecutor, WorkflowExecutor, Mockito, query mocks, mutation assertions, ApolloUtils, TestUtils API, fixtures, coverage checklist, and POM dependency guidance. Derived from module-core 2.2.1, module-order 2.1.0, and official util-test documentation."
 version: 2.0
-relevant-skills: [fluent-rule-test, fluent-rule-scaffold, fluent-custom-code, fluent-build, fluent-module-scaffold, fluent-source-onboard]
+relevant-skills: [fluent-rule-test, fluent-rule-scaffold, fluent-custom-code, fluent-build, fluent-module-scaffold, fluent-module-convert]
 load: on-demand
 ---
 

package/docs/01-first-session.md

@@ -0,0 +1,175 @@
+# Your First Session
+
+> 20 minutes to a productive session, with just enough prompts to get confidence.
+> Works with Claude Code, Codex, and Gemini CLI.
+
+Use this in order, exactly. Ask the next prompt only after the previous one is done.
+
+## 1) First 20 minutes (minimum viable setup)
+
+> **`npm` vs `npx`:** `npm install -g` permanently installs a tool. `npx` runs a package without installing. All `@fluentcommerce/ai-skills` commands use `npx`.
+
+1. Install and connect your workspace (replace placeholders):
+
+```bash
+# Pick your target:
+npx @fluentcommerce/ai-skills install --profile MY_PROFILE                  # Claude Code (default)
+npx @fluentcommerce/ai-skills install --target codex --profile MY_PROFILE   # Codex
+npx @fluentcommerce/ai-skills install --target gemini --profile MY_PROFILE  # Gemini CLI
+
+# Verify everything is working:
+npx @fluentcommerce/ai-skills doctor
+```
+
+2. Connect the workspace to your Fluent account:
+
+| In Claude Code | In Codex or Gemini CLI |
+|---|---|
+| `/fluent-connect --profile MY_PROFILE` | `Use the fluent-connect skill to connect this workspace with profile MY_PROFILE.` |
+
+3. Confirm what was created:
+
+`Show me the workspace tree`
+
+If your output is confusing, try:
+
+`What folders were created for this account?` and share the reply with your teammate.
+
+## 2) Three things newcomers usually ask first
+
+### A. “What can I do with this?”
+
+Use these read-only prompts first:
+
+`What's deployed on this account?`
+- **Triggers:** `fluent-account-snapshot` (read-only, safe)
+- **You get:** workflows, modules, settings, retailers — a full implementation inventory
+- **Artifact:** summary in `accounts/<PROFILE>/analysis/`
+
+`How does Home Delivery work end-to-end?`
+- **Triggers:** `fluent-feature-explain` (read-only, safe)
+- **You get:** state machine diagrams, cross-entity sequence diagrams, rules table, settings dependencies
+- **Artifact:** `accounts/<PROFILE>/features/home-delivery/architecture.md`
+
+### B. “How do I debug?”
+
+`Why is order HD-001 stuck in BOOKED?`
+- **Triggers:** `fluent-trace` (read-only, safe)
+- **You get:** event timeline, which rules fired or failed, root cause, and suggested fix
+- **No artifacts** — output is inline in the conversation
+
+### C. “How do I start building?”
+
+`Help me define use cases for return orders`
+- **Triggers:** `fluent-use-case-discover` (interactive wizard)
+- **You get:** structured business spec with completeness score
+- **Artifact:** `accounts/<PROFILE>/features/return-order/spec.md`
+
+Then, after review:
+
+`Plan the return order feature`
+- **Triggers:** `fluent-feature-plan` (presents plan, waits for approval)
+- **You get:** 18-section implementation plan with diagrams, rules inventory, risk assessment
+- **Artifact:** `accounts/<PROFILE>/features/return-order/plan.md`
+
+**Wait for approval** after plan review before any change. Say `”approved”` to proceed.
+
+## 3) Prompt ladder (don’t memorize anything)
+
+Pick one path and follow it:
+
+**Path 1: Explore only** (all read-only, safe)
+
+| Prompt | Skill triggered |
+|--------|----------------|
+| `Show me what's deployed on this account` | `fluent-account-snapshot` |
+| `Show me the workspace tree` | `fluent-workspace-tree` |
+| `Explain how Home Delivery works end-to-end` | `fluent-feature-explain` |
+| `List all in-progress features` | `fluent-feature-status` |
+
+**Path 2: Investigate one issue** (all read-only, safe)
+
+| Prompt | Skill triggered |
+|--------|----------------|
+| `Why is order HD-001 stuck in BOOKED?` | `fluent-trace` |
+| `Show me the event timeline for that order` | `fluent-trace` (continued) |
+| `What settings does this flow use?` | `fluent-settings` |
+| `What transitions are allowed for ORDER?` | `fluent-transition-api` |
+
+**Path 3: Build one small feature** (creates artifacts, approval required)
+
+| Prompt | Skill triggered |
+|--------|----------------|
+| `Help me define use cases for <feature>` | `fluent-use-case-discover` |
+| `Plan the <feature> feature` | `fluent-feature-plan` |
+| `Approved` | Plan gate clears, implementation begins |
+| `Scaffold the module` | `fluent-module-scaffold` |
+| `Build the workflow from the plan` | `fluent-workflow-builder` |
+
+Pause after each step to check output before continuing.
+
+## 4) Where artifacts land (so you can find them quickly)
+
+- `accounts/<PROFILE>/workflows/<RETAILER>/`
+  - Downloaded workflow JSONs
+  - `workflow-context.json`
+- `accounts/<PROFILE>/features/<slug>/`
+  - `spec.md` (requirements)
+  - `plan.md` (approved implementation plan)
+  - `architecture.md` (feature explain output)
+  - `status.json` (current lifecycle state)
+- `accounts/<PROFILE>/SOURCE/backend/`
+  - Java/Maven sources the skill reads and writes
+- `accounts/<PROFILE>/analysis/`
+  - Persisted reverse-engineering outputs
+- `accounts/<PROFILE>/reports/`
+  - Quality gates, pre-deploy checks, and validation outputs
+- `accounts/<PROFILE>/sessions/`
+  - Audit trail exports from sessions
+
+Use this command-style prompt when you lose track:
+
+`What artifacts were created in the last two hours and where?`
+
+This avoids rebuilding context from scratch.
+
+## 5) What to do when nothing responds
+
+1. `npx @fluentcommerce/ai-skills doctor` in the workspace folder
+2. `Show me the installed skill list`
+3. Ask the specific issue: `What failed when I tried to run ...?`
+4. Retry the same first prompt for the task.
+
+## 6) Keep it beginner-safe
+
+- Start with read-only prompts. No code changes in first 20 minutes.
+- Approve only after the plan is clear.
+- Use explicit nouns in prompts: order ref, workflow name, module name.
+- If a prompt fails, simplify it and retry rather than changing everything.
+
+At the end of the day, copy this into team docs:
+
+- one example of a successful debug (`why is this order stuck`)
+- one example of a successful feature plan approval
+- one artifact map screenshot from `Show me the workspace tree`
+
+That becomes your team memory baseline.
+
+## 7) Setting up a second workspace
+
+Skills, agents, and platform knowledge install **globally** to `~/.claude/` — once installed, they're available in every workspace. A second workspace only needs MCP config (credentials are per-workspace):
+
+```bash
+mkdir client-b && cd client-b
+git init
+npx @fluentcommerce/ai-skills mcp-setup --profile CLIENT_B_PROFILE
+npx @fluentcommerce/ai-skills doctor   # verify everything
+```
+
+That's it — `mcp-setup` wires MCP, generates a starter `CLAUDE.md`, and knowledge falls back to the global copy. If you want a full local copy of knowledge and docs too, run `install` instead of `mcp-setup`.
+
+## 8) Next reading (after this)
+
+- [prompt-guide.md](02-prompt-guide.md) — progressive skill navigator (which of the 60+ skills matter, and when)
+- [Setup Reference & Troubleshooting](05-getting-started.md) — prerequisites, workspace layout, and troubleshooting
+- [onboarding-plan.md](04-onboarding-plan.md) — structured two-week team ramp

package/docs/02-prompt-guide.md

@@ -0,0 +1,246 @@
+# Prompt Guide — Navigating 60+ Skills
+
+> You have 60+ skills. You don't need to learn them all.
+> This guide organizes them into a progressive path: start with 5, expand as your work demands.
+
+> [!TIP]
+> **First time?** Start with [first-session.md](01-first-session.md) — a 20-minute guided walkthrough.
+> **Need full examples?** See [Setup Reference & Troubleshooting](05-getting-started.md).
+> **This doc** answers: "which skills exist, what do they do, and what should I type?"
+
+---
+
+## How Prompting Works
+
+You describe what you want in plain English. The AI picks the right skill. You don't need to name skills — but you can use `/slash-commands` if you know them.
+
+The AI **always asks before changing anything**. You'll see a plan and say `"approved"` before any files are created or anything is deployed.
+
+---
+
+## Level 1 — Your First Session (5 skills)
+
+Safe, read-only, instant value. Nothing is changed or created.
+
+| Skill | What it does | Try this |
+|-------|-------------|----------|
+| `fluent-connect` | Links workspace to your Fluent account | `/fluent-connect --profile MY_PROFILE` |
+| `fluent-account-snapshot` | Shows what's deployed — workflows, modules, retailers | `"What's deployed on this account?"` |
+| `fluent-feature-explain` | Explains a feature with diagrams and rule inventory | `"Explain how Home Delivery works end-to-end"` |
+| `fluent-trace` | Investigates stuck orders with event timeline and root cause | `"Why is order HD-001 stuck in BOOKED?"` |
+| `fluent-workspace-tree` | Shows annotated directory layout | `"Show me the workspace tree"` |
+
+**After this level:** You understand the account, can explain features, and can investigate issues.
+
+---
+
+## Quick Reference — Common Prompt Chains
+
+These are the most common end-to-end workflows. Each row is a complete prompt chain you can follow in order.
+
+| I'm building... | Prompt chain (say these in order) | Skills that trigger | What you get |
+|-----------------|----------------------------------|---------------------|-------------|
+| **A new feature (end-to-end)** | "I need to handle return orders" → "Plan the return order feature" → "Approved" → "Build the workflow" → "Scaffold the module" → "Deploy to staging" → "Run E2E test" | `use-case-discover` → `feature-plan` → `workflow-builder` → `module-scaffold` → `workflow-deploy` + `module-deploy` → `e2e-test` | `spec.md`, `plan.md`, workflow JSON, Java classes, module ZIP, test results |
+| **A new workflow** | "Build an ORDER::RETURN workflow" → review plan → "Approved" → "Deploy to staging" | `workflow-builder` → `workflow-deploy` | Workflow JSON in `accounts/<PROFILE>/workflows/` |
+| **A new rule + tests** | "Create a rule called ValidateReturnWindow" → "Generate tests for it" → "Build the module" | `rule-scaffold` → `rule-test` → `build` | Java class, JUnit test, module ZIP |
+| **A UI page** | "Add a returns page to the order manifest" → "Preview it" → "Deploy the manifest" | `mystique-builder` → `mystique-preview` → `settings` | Manifest JSON in `accounts/<PROFILE>/manifests/` |
+| **Debug a stuck order** | "Why is order HD-001 stuck in BOOKED?" → "Show the event timeline" → "Compare runtime vs workflow" | `trace` → `entity-flow-diagnose` | Timeline, root-cause report |
+| **Understand what's deployed** | "What's deployed on this account?" → "Explain how Home Delivery works" → "Map the entire implementation" | `account-snapshot` → `feature-explain` → `implementation-map` | Account summary, feature diagrams, implementation inventory |
+| **Go-live readiness** | "Run pre-deploy checks" → "Run a Ready For Launch assessment" | `pre-deploy-check` → `rfl-assess` | GO/NO-GO report, RFL assessment |
+
+All artifacts land under `accounts/<PROFILE>/` in your workspace.
+
+---
+
+## Level 2 — Your First Week (add 12 skills)
+
+These create or change things — the AI presents a plan and waits for your approval first.
+
+### Understand and Plan
+
+| Skill | What it does | Try this |
+|-------|-------------|----------|
+| `fluent-use-case-discover` | Gathers requirements through interactive prompts | `"I need to handle return orders"` |
+| `fluent-feature-plan` | Creates an 18-section implementation plan with diagrams | `"Plan the return order feature"` |
+| `fluent-implementation-map` | Maps what's already been built across the workspace | `"Map the entire implementation"` |
+
+### Build
+
+| Skill | What it does | Try this |
+|-------|-------------|----------|
+| `fluent-workflow-builder` | Creates workflow JSON with statuses, rulesets, and triggers | `"Build an ORDER::RETURN workflow"` |
+| `fluent-rule-scaffold` | Scaffolds Java rule classes with annotations and tests | `"Create a rule called ValidateReturnWindow"` |
+| `fluent-rule-test` | Generates or repairs JUnit 5 tests for existing rules | `"Generate tests for ValidateReturnWindow"` |
+| `fluent-module-scaffold` | Creates Maven project skeleton with pom.xml and module.json | `"Scaffold a module for returns"` |
+| `fluent-build` | Compiles and packages a module into a deployable ZIP | `"Build the returns module"` |
+
+### Deploy and Verify
+
+| Skill | What it does | Try this |
+|-------|-------------|----------|
+| `fluent-pre-deploy-check` | Runs 35+ quality gates across 9 phases — produces GO/NO-GO report | `"Run pre-deploy checks"` |
+| `fluent-workflow-deploy` | Uploads workflow JSON to target environment | `"Deploy ORDER::RETURN to staging"` |
+| `fluent-module-deploy` | Deploys compiled module to target environment | `"Deploy the returns module to staging"` |
+| `fluent-e2e-test` | Runs end-to-end test with event firing and assertions | `"Run E2E test of the return flow"` |
+
+**After this level:** You can plan, build, deploy, and verify features. For prerequisites and troubleshooting, see [Setup Reference](05-getting-started.md).
+
+---
+
+## How Routing Works
+
+You don't need to know this — the AI picks the right agent automatically. But if you're curious:
+
+| Agent | Handles | Example prompts |
+|-------|---------|----------------|
+| `fluent-dev` | Cross-cutting: planning, mapping, status, E2E | "Plan the return feature", "What features are in progress?" |
+| `fluent-backend-dev` | Workflows, rules, modules, events, Java, deploy | "Build a workflow", "Create a rule", "Trace this event" |
+| `fluent-frontend-dev` | Manifests, pages, SDK components, UI testing | "Add a page to the manifest", "Scaffold a component" |
+| `fluent-cli` | CLI profiles, retailers, account setup | "Create a profile", "List retailers" |
+| `fluent-mcp` | MCP servers, GraphQL, events, batch ops | "Send a test event", "Query orders via GraphQL" |
+| `fluent-rfl` | Production readiness audits | "Run an RFL assessment" |
+
+---
+
+## Skills by Lifecycle Stage
+
+If you're following a structured development process:
+
+| Stage | What you're doing | Key skills |
+|-------|------------------|-----------|
+| **Setup** | Connect workspace, configure profiles | `fluent-connect`, `fluent-bootstrap`, `fluent-profile` |
+| **Discover** | Understand what exists | `fluent-account-snapshot`, `fluent-feature-explain`, `fluent-implementation-map` |
+| **Requirements** | Define what to build | `fluent-use-case-discover` |
+| **Plan** | Design the solution | `fluent-feature-plan`, `fluent-scope-plan` |
+| **Build (backend)** | Workflows, rules, modules | `fluent-workflow-builder`, `fluent-rule-scaffold`, `fluent-module-scaffold` |
+| **Build (frontend)** | Manifests, components | `fluent-mystique-builder`, `fluent-mystique-scaffold` |
+| **Validate** | Quality gates | `fluent-pre-deploy-check`, `fluent-module-validate`, `fluent-mystique-assess` |
+| **Deploy** | Push to environment | `fluent-workflow-deploy`, `fluent-module-deploy` |
+| **Test** | Verify behavior | `fluent-e2e-test`, `fluent-ui-test`, `fluent-test-data` |
+| **Diagnose** | Debug failures | `fluent-trace`, `fluent-entity-flow-diagnose`, `fluent-rollback` |
+
+---
+
+## Level 3 — All Skills by Category
+
+Pick what's relevant to your work. Each table is independent — skip categories you don't need.
+
+### Backend: Workflows
+
+| Skill | What it does | Try this |
+|-------|-------------|----------|
+| `fluent-workflow-analyzer` | Static analysis — orphaned rulesets, trigger conflicts, schema validation | `"Analyze the HD workflow for issues"` |
+| `fluent-workflow` | CLI workflow operations — list, download, compare | `"Download all workflows for MY_RETAILER"` |
+| `fluent-transition-api` | Entity status transitions and allowed actions | `"What transitions are available for ORDER?"` |
+
+### Backend: Rules and Modules
+
+| Skill | What it does | Try this |
+|-------|-------------|----------|
+| `fluent-custom-code` | Analyzes existing Java rules — explains logic, annotations | `"Explain what SendEventForArticles does"` |
+| `fluent-rule-lookup` | Finds rules by name, annotation, or behavior across deployed modules | `"Find all rules that use @ParamString 'eventName'"` |
+| `fluent-module-validate` | Validates module structure, registrations, dependencies | `"Validate the returns module"` |
+| `fluent-entity-flow-diagnose` | Traces entity flow across multiple workflows | `"Trace the fulfilment lifecycle for HD"` |
+| `fluent-module-convert` | Onboards existing source code into a proper module | `"Onboard this legacy code into a module"` |
+| `fluent-data-module-scaffold` | Creates data-only modules (no Java, just config) | `"Create a data module for reference data"` |
+
+### Frontend: Mystique UI
+
+| Skill | What it does | Try this |
+|-------|-------------|----------|
+| `fluent-mystique-builder` | Builds or modifies manifest JSON pages | `"Add a returns page to the order manifest"` |
+| `fluent-mystique-scaffold` | Creates new manifest project from scratch | `"Scaffold a manifest for my-returns"` |
+| `fluent-mystique-component` | Scaffolds custom SDK component projects | `"Create a ReturnReasonPicker component"` |
+| `fluent-mystique-assess` | Analyzes and validates manifest structure and correctness | `"Analyze and validate the order manifest"` |
+| `fluent-mystique-diff` | Compares manifest versions | `"Diff the manifest against staging"` |
+| `fluent-mystique-sdk-reference` | SDK API and pattern reference | `"How do I use the fc-table component?"` |
+| `fluent-mystique-preview` | Preview manifest rendering | `"Preview what the returns page looks like"` |
+| `fluent-frontend-build` | Builds frontend artifacts | `"Build the manifest for deployment"` |
+| `fluent-frontend-review` | Reviews frontend code quality | `"Review the returns manifest"` |
+| `fluent-frontend-readme` | Generates frontend documentation | `"Generate README for the manifest project"` |
+| `fluent-ui-test` | UI testing with assertions | `"Test the order detail page"` |
+| `fluent-ui-record` | Records UI interactions for test replay | `"Record a test for the returns form"` |
+
+### Operations and CLI
+
+| Skill | What it does | Try this |
+|-------|-------------|----------|
+| `fluent-profile` | Manage CLI profiles — create, switch, list | `"Show available profiles"` |
+| `fluent-bootstrap` | Set up new accounts from scratch | `"Bootstrap a new test account"` |
+| `fluent-settings` | Query and manage platform settings | `"Audit settings for ORDER::HD"` |
+| `fluent-retailer-config` | Retailer and location configuration | `"Show retailer configuration"` |
+| `fluent-cli-retailer` | CLI retailer operations | `"List retailers on this account"` |
+| `fluent-connection-analysis` | Check connector and webhook health | `"Are all connectors working?"` |
+| `fluent-rollback` | Roll back a failed deployment | `"Roll back ORDER::HD to previous version"` |
+
+### Monitoring, Events, and Quality
+
+| Skill | What it does | Try this |
+|-------|-------------|----------|
+| `fluent-system-monitoring` | Event processing metrics from Prometheus | `"Show event failure rates"` |
+| `fluent-event-api` | Send and inspect events | `"Send a test event to order HD-001"` |
+| `fluent-rfl-assess` | Ready For Launch production readiness audit | `"Run a Ready For Launch assessment"` |
+| `fluent-job-batch` | Batch data ingestion jobs | `"Batch ingest inventory from CSV"` |
+| `fluent-test-data` | Generate test data and fixtures | `"Create test orders for the HD flow"` |
+
+### Data and Sourcing
+
+| Skill | What it does | Try this |
+|-------|-------------|----------|
+| `fluent-sourcing` | Responsive Sourcing Framework reference — profiles, strategies, scoring | `"How does sourcing work for HD fulfilment?"` |
+| `fluent-inventory-catalog` | Inventory and catalog setup | `"Set up inventory for Click & Collect"` |
+| `fluent-knowledge-init` | Initialize workspace knowledge docs | `"Set up knowledge docs for this workspace"` |
+
+### Feature Lifecycle and Tracking
+
+| Skill | What it does | Try this |
+|-------|-------------|----------|
+| `fluent-feature-status` | Check feature progress across workspace | `"What features are in progress?"` |
+| `fluent-scope-plan` | Phases and scope decomposition for large features | `"Decompose the returns spec into phases"` |
+| `fluent-goal` | Goal-oriented task tracking with deadlines | `"My goal is to ship returns by Friday"` |
+| `fluent-session` | Session tracking and resume across conversations | `"What did we do in the last session?"` |
+| `fluent-archive` | Archive completed features | `"Archive the returns feature"` |
+| `fluent-skill-observability` | Skill tracing, routing reports, and feedback | `"Which skill handled my last prompt?"` |
+
+### MCP and Reference
+
+| Skill | What it does | Try this |
+|-------|-------------|----------|
+| `fluent-mcp-tools` | MCP extension tool reference (55+ tools) | `"What MCP tools are available for events?"` |
+| `fluent-mcp-core` | Official CLI MCP server reference | `"How do I use the official MCP server?"` |
+| `fluent-cli-reference` | CLI command reference and skill index | `"Show me the CLI command for workflow download"` |
+| `fluent-cli-mcp-cicd` | MCP and CI/CD pipeline setup | `"Set up MCP for CI/CD"` |
+
+---
+
+## Tips for Effective Prompting
+
+**Be specific about what you want, not which skill to use:**
+- Good: `"Why is order HD-001 stuck in BOOKED?"`
+- Less useful: `"Run the trace skill"`
+
+**Chain prompts to go deeper:**
+```
+"Explain how Home Delivery works"           ← start broad
+"What rules handle the BOOKED status?"      ← zoom in
+"Show me the code for SendEventForArticles" ← inspect
+"Are there tests for that rule?"            ← verify
+```
+
+**Use the approval gate — it's your safety net:**
+- When the AI shows a plan, ask questions before approving
+- `"What are the risks?"` or `"Change the workflow name to X"` before `"approved"`
+
+**Resume across sessions:**
+- `"Continue working on return orders"` — the AI reads `status.json` and picks up where you left off
+
+---
+
+## How This Relates to Other Docs
+
+| Doc | Purpose | When to use it |
+|-----|---------|---------------|
+| **This guide** | Which skills exist, what to type, routing, and lifecycle | When you're wondering "can AI do X?" |
+| [first-session.md](01-first-session.md) | 20-minute guided first session | Your very first time |
+| [Setup Reference](05-getting-started.md) | Prerequisites, workspace layout, troubleshooting | When you need setup details or hit errors |
+| [use-cases.md](03-use-cases.md) | 21 detailed scenario walkthroughs | When you need a specific scenario end-to-end |