@fluentcommerce/ai-skills 0.13.0 → 0.15.0

package/docs/04-onboarding-plan.md

@@ -0,0 +1,355 @@
+# Fluent AI Skills — Developer Onboarding Plan
+
+> [!CAUTION]
+> **EXPERIMENTAL - LABS PROJECT**
+>
+> This package is not production-ready. No stability guarantees, no support, no warranty. See `../README.md` for the full disclaimer.
+
+A structured two-week onboarding plan for senior developers adopting AI-assisted development for Fluent OMS. Covers installation through to shipping a complete end-to-end feature using agents and skills as daily tools.
+
+**Prerequisites:** Complete [Your First Session](01-first-session.md) before starting this plan (20 minutes). For skill reference, see [Prompt Guide](02-prompt-guide.md). For prerequisites and troubleshooting, see [Setup Reference & Troubleshooting](05-getting-started.md).
+
+> **Solo developer?** Follow Day 1-2 tasks from Week 1, then jump straight to Week 2 Day 1. Skip team review steps ("review as a team", "share with the team") — the AI-generated plans and architecture docs serve the same validation purpose for individual work.
+
+> **Examples below use Claude Code slash commands.** In Codex or Gemini CLI, use natural-language prompts such as `Use the fluent-connect skill to connect this workspace with profile YOUR_PROFILE.` instead of `/fluent-*`.
+
+---
+
+## Table of Contents
+
+- [Week 1 — Orientation and Read-Only Exploration](#week-1--orientation-and-read-only-exploration)
+  - [Day 1 — Install, Connect, Orient](#day-1--install-connect-orient)
+  - [Day 2 — Understand the Existing Implementation](#day-2--understand-the-existing-implementation)
+  - [End of Week 1 — First Design Work](#end-of-week-1--first-design-work-requirements--planning)
+- [Week 2 — Build, Deploy, and Verify](#week-2--build-deploy-and-verify)
+  - [Day 1 — Backend: Rules, Workflow, Module](#day-1-week-2--backend-rules-workflow-module)
+  - [Day 2 — Frontend: UI Component or Manifest Change](#day-2-week-2--frontend-ui-component-or-manifest-change)
+  - [End of Week 2 — Deploy, Test, and Verify](#end-of-week-2--deploy-test-and-verify)
+- [Summary](#summary)
+- [Calibration Tips for Senior Developers](#calibration-tips-for-senior-developers)
+
+---
+
+## Week 1 — Orientation and Read-Only Exploration
+
+The entire first week is read-only. No code, no workflows, no deployments. The goal is to build a mental model of the implementation *and* of how the AI tools reason about it — so that when you start building in Week 2, you trust the AI's analysis.
+
+---
+
+### Day 1 — Install, Connect, Orient
+
+**Theme:** Get the environment working and understand what the workspace is
+
+**Tasks:**
+
+1. **Complete [Your First Session](01-first-session.md)** (20 minutes) — install, connect, and explore. Once done, you'll have MCP servers running, workspace initialized, and all workflows downloaded.
+
+2. **Go deeper** — Check MCP connectivity and the live environment:
+   ```
+   List all deployed modules and their versions
+   ```
+   Then:
+   ```
+   What settings exist for ORDER workflows?
+   ```
+
+3. **Map what has been built:**
+   ```
+   What has been built on this account? Give me a feature inventory.
+   ```
+   This runs `/fluent-implementation-map` and produces `analysis/implementation-map/` — a feature inventory that reverse-engineers the implementation from workflows, rules, and settings.
+
+**Expected outcomes by end of Day 1:**
+- MCP servers running and all three connected (`fluent-mcp`, `fluent-mcp-extn`, `chrome-devtools`)
+- Workspace fully initialized under `accounts/<PROFILE>/`
+- All workflow JSONs downloaded and accessible
+- Confident the AI has real connectivity to your environment
+- Team can navigate the workspace directory structure without help
+
+---
+
+### Day 2 — Understand the Existing Implementation
+
+**Theme:** Map the full implementation by letting the AI reverse-engineer it for you
+
+**Tasks:**
+
+1. **Explain a key feature end-to-end** — Pick the most important order flow (e.g. Home Delivery):
+   ```
+   Explain how Home Delivery works end-to-end
+   ```
+   This runs `/fluent-feature-explain` and produces `features/home-delivery/architecture.md` — a persisted Feature Architecture Document with Mermaid state machine diagrams, cross-entity sequence diagrams, rules tables with logic descriptions, settings dependencies, and integration points. Share this with the team.
+
+3. **Analyze a workflow structurally:**
+   ```
+   Analyze ORDER::HD for orphaned rulesets and trigger coverage gaps
+   ```
+   This runs `/fluent-workflow-analyzer` — you get a status graph, event chains, orphan detection, and structural issues. This is what the AI uses internally when planning changes.
+
+4. **Understand custom code:**
+   ```
+   Analyze the custom code for this account
+   ```
+   The AI scans `SOURCE/backend/`, maps each rule to the workflow ruleset it serves, generates behavior descriptions, and flags any deployed rules with no local source. This is your introduction to `/fluent-custom-code`.
+
+5. **(Optional) Explain a second feature** — Repeat the `feature-explain` step on another core flow (e.g. Click & Collect, Returns if present) to build broader context.
+
+**Expected outcomes by end of Day 2:**
+- `analysis/implementation-map/` generated and reviewed by the team
+- At least 2 Feature Architecture Documents in `features/*/architecture.md`, with Mermaid diagrams shared in Confluence or equivalent
+- Each developer can explain the main order flow in their own words, validated against the generated documentation
+- Team understands the workflow → ruleset → rule → setting dependency chain
+
+---
+
+### End of Week 1 — First Design Work (Requirements + Planning)
+
+**Theme:** Move from read-only into the planning layer. No environment changes yet — plans only.
+
+**Tasks:**
+
+1. **Debug a real issue or simulate one** — Trace a stuck or interesting entity:
+   ```
+   Why is order HD-12345 stuck in BOOKED?
+   ```
+   Or if no stuck order exists:
+   ```
+   Trace the last failed event in the ORDER workflow
+   ```
+   This runs `/fluent-trace` and introduces the event investigation pattern — `event_list`, `event_flowInspect`, root cause analysis, and remediation suggestions. Practice reading the output before needing it under pressure.
+
+2. **Check the event model:**
+   ```
+   How does event routing work in Fluent? What event types exist for ORDER?
+   ```
+   This runs `/fluent-event-api` and gives you the event data model, causality tracing patterns, and integration event contracts. Essential background before writing rules.
+
+3. **Gather requirements for a new feature** — Choose a small, realistic feature your team actually wants to build (e.g. an appeasement flow, a return order, a click-and-collect extension). Run the requirements wizard:
+   ```
+   Help me define use cases for [your chosen feature]
+   ```
+   This runs `/fluent-use-case-discover` interactively — the AI walks through triggers, actors, business rules, and edge cases. Review the resulting `spec.md` together as a team. Say `"approved"` when the spec is right.
+
+4. **Plan the feature:**
+   ```
+   Plan the [feature name] feature
+   ```
+   This runs `/fluent-feature-plan` and produces the 18-section technical plan in `features/<slug>/plan.md` — rules inventory with NEW/EXISTING/OOTB classification, workflow state machine changes, settings, risk assessment, and test plan. **Do not approve it yet** — the goal this week is to read and critique the plan, not execute it.
+
+5. **Review the plan as a team** — Go through `plan.md` together. Check: Are the rules the AI identified correct? Does the state machine match your understanding? Are there settings or edge cases it missed? This is how you calibrate trust in the AI's planning.
+
+**Expected outcomes by end of Week 1:**
+- At least one complete `spec.md` (approved) and one `plan.md` (reviewed but not yet approved) in `features/<slug>/`
+- Team has practiced the full read-only skill suite: `feature-explain`, `implementation-map`, `workflow-analyzer`, `custom-code`, `trace`, `event-api`
+- Everyone understands the difference between IDE/tool permission prompts and the skill approval gate
+- Confidence level established: the team knows where the AI is reliable and where to verify its output
+
+---
+
+## Week 2 — Build, Deploy, and Verify
+
+Now you build the feature planned in Week 1. The AI does the heavy lifting — your job is to review, approve, and test.
+
+---
+
+### Day 1 (Week 2) — Backend: Rules, Workflow, Module
+
+**Theme:** Approve the plan and build the backend artifacts
+
+**Tasks:**
+
+1. **Approve the plan:**
+   ```
+   Approved
+   ```
+   `status.json` moves to `APPROVED`, and `next` points to `/fluent-module-scaffold`.
+
+2. **Scaffold the module** (if this is a new module — skip if adding to an existing one):
+   ```
+   Scaffold the module
+   ```
+   Creates a Maven project skeleton under `SOURCE/backend/fc-module-<name>/` with `pom.xml`, `module.json`, and source directories.
+
+3. **Create the rules:**
+   ```
+   Create the rules from the plan
+   ```
+   The AI scaffolds each Java rule class with pseudo logic from the plan, generates matching test classes, and registers rules in `module.json`. Review each generated class — the logic is pseudo-code, not production code. This is where your domain expertise shapes the implementation.
+
+4. **Build the workflow:**
+   ```
+   Build the workflow from the plan
+   ```
+   Constructs the workflow JSON, validates with `/fluent-workflow-analyzer` for orphaned rulesets and trigger conflicts, and writes it under `workflows/<RETAILER>/`. Review the output against the plan's state machine diagram.
+
+5. **Audit settings:**
+   ```
+   What settings does this feature need? Are they configured?
+   ```
+   Runs `/fluent-settings` to discover required settings, check live values, and flag anything missing before deployment.
+
+6. **Validate and build:**
+   ```
+   Run pre-deploy checks for [module name]
+   ```
+   37 quality gates across 9 phases. Review the GO/NO-GO report. Fix any blocking issues before continuing.
+
+   Then:
+   ```
+   Build the [module name] module
+   ```
+
+**Expected outcomes by end of Day 1 (Week 2):**
+- Module ZIP built and in `dist/`
+- Workflow JSON created and validated
+- Pre-deploy check report green (or known issues flagged with a plan to fix)
+- Each developer has read and understands at least one generated rule class
+
+---
+
+### Day 2 (Week 2) — Frontend: UI Component or Manifest Change
+
+**Theme:** Extend the OMS UI to surface the new feature
+
+> If the feature has no UI component, substitute this day with a second backend feature or a settings/retailer-config task.
+
+**Tasks:**
+
+1. **Understand the existing UI:**
+   ```
+   Analyze the admin manifest — what pages and components exist?
+   ```
+   Runs `/fluent-mystique-assess` and gives you a complexity-scored breakdown of the manifest with Mermaid route and component tree diagrams.
+
+2. **Preview before building:**
+   ```
+   Preview what the [new feature] card would look like on the order detail page
+   ```
+   Runs `/fluent-mystique-preview` to show the likely UI change before touching any manifest. Fast iteration without risk.
+
+3. **Build the manifest change or SDK component:**
+
+   If the requirement can be met with manifest config:
+   ```
+   Add a [description] component to the order detail page
+   ```
+   Runs `/fluent-mystique-builder`. The AI applies the change and explains each decision.
+
+   If a custom component is needed:
+   ```
+   Scaffold a custom [name] component for the Mystique SDK
+   ```
+   Runs `/fluent-mystique-scaffold` to create a full buildable SDK project with TypeScript, webpack, Storybook, and Jest.
+
+4. **Validate the manifest:**
+   ```
+   Validate the admin manifest
+   ```
+   Runs `/fluent-mystique-assess` — ~50 validation rules across 6 phases: schema compliance, component resolution, query validation, i18n, prop verification, cross-manifest consistency.
+
+5. **Build the frontend (if an SDK project was created):**
+   ```
+   Build the [component project name] project
+   ```
+   Runs `/fluent-frontend-build` through 7 gates: TypeScript compilation, lint, tests with coverage, production webpack build, bundle verification, externals check, GraphQL schema validation.
+
+**Expected outcomes by end of Day 2 (Week 2):**
+- Manifest updated or SDK bundle built
+- Validation passing
+- Developers understand the OOTB-vs-custom decision framework (config first, SDK only when needed)
+
+---
+
+### End of Week 2 — Deploy, Test, and Verify
+
+**Theme:** Ship the feature, run E2E tests, verify in the browser
+
+**Tasks:**
+
+1. **Deploy:**
+   ```
+   Deploy [module name] to [RETAILER]
+   ```
+   Then:
+   ```
+   Deploy [WORKFLOW_NAME] to [RETAILER]
+   ```
+   The AI confirms each step before executing. Review the confirmation summary before approving each deployment.
+
+2. **Create test data:**
+   ```
+   Create a test HD order for the [feature] flow
+   ```
+   Runs `/fluent-test-data` — discovers real locations, products, catalogues, and inventory from your retailer environment and generates valid entity creation payloads. No manual JSON crafting.
+
+3. **Run E2E tests:**
+   ```
+   Run E2E test for the [feature name] flow
+   ```
+   Runs `/fluent-e2e-test` — creates entities, sends events, polls for expected status transitions, and reports pass/fail per scenario from the plan's test plan.
+
+4. **Verify the UI in the browser:**
+   ```
+   Test the OMS orders page in the browser — check the [feature] renders correctly
+   ```
+   Runs `/fluent-ui-test` via Chrome DevTools MCP — automated browser login, navigation, component rendering verification, screenshot capture, and console error detection.
+
+5. **Record evidence:**
+   ```
+   Record before/after screenshots of the [feature] UI
+   ```
+   Runs `/fluent-ui-record` — annotated walkthrough screenshots saved as evidence in `features/<slug>/assets/`.
+
+6. **Run the go-live readiness assessment:**
+   ```
+   Run an RFL assessment for this feature
+   ```
+   Runs `/fluent-rfl-assess` — production readiness audit across workflows, rules, settings, and architecture. Identifies any gaps before promoting to higher environments.
+
+7. **Wrap up the session:**
+   ```
+   What skills ran this session? Show the decision chain.
+   ```
+   Runs `/fluent-session` — the audit trail of every skill invocation, tool call, gate result, and environment change. Export as JSON for the team's records.
+
+**Expected outcomes by end of Week 2:**
+- Feature deployed to the target retailer environment
+- E2E test scenarios passing
+- UI verified in the browser with screenshots as evidence
+- `status.json` at `DEPLOYED` or `VERIFIED`
+- RFL assessment completed with a clear list of any remaining gaps for promotion
+- Session audit exported
+
+---
+
+## Summary
+
+| Milestone | Skills in play | Gate |
+|---|---|---|
+| **Day 1** | `fluent-connect`, `fluent-workspace-tree`, `fluent-settings` | Read-only — no gate |
+| **Day 2** | `fluent-implementation-map`, `fluent-feature-explain`, `fluent-workflow-analyzer`, `fluent-custom-code` | Read-only — no gate |
+| **End of Week 1** | `fluent-trace`, `fluent-event-api`, `fluent-use-case-discover`, `fluent-feature-plan` | Spec approval + plan review (not yet approved) |
+| **Day 1, Week 2** | `fluent-module-scaffold`, `fluent-rule-scaffold`, `fluent-workflow-builder`, `fluent-settings`, `fluent-pre-deploy-check`, `fluent-build` | Plan approval gate before scaffold begins |
+| **Day 2, Week 2** | `fluent-mystique-assess`, `fluent-mystique-preview`, `fluent-mystique-builder` or `fluent-mystique-scaffold`, `fluent-frontend-build` | Per-manifest confirmation |
+| **End of Week 2** | `fluent-module-deploy`, `fluent-workflow-deploy`, `fluent-test-data`, `fluent-e2e-test`, `fluent-ui-test`, `fluent-ui-record`, `fluent-rfl-assess`, `fluent-session` | Deployment confirmation gate |
+
+---
+
+## Calibration Tips for Senior Developers
+
+- **Read-only skills are always safe.** `explain`, `analyze`, `trace`, `validate`, `audit` — run these without ceremony at any time. They produce no environment changes.
+- **There are two kinds of prompts.** Tool permission prompts come from the IDE sandbox and are about shell/filesystem access. Approval-gate prompts come from the skills and are about whether the AI should proceed with a planned change.
+- **The approval gate is your ally.** The AI always presents a plan and waits. Use this to review intent before execution, not just to rubber-stamp it.
+- **Trust is earned by reading the output.** The Feature Architecture Documents and pre-deploy reports are the AI's reasoning made visible. Read them critically — this is where your domain knowledge adds the most value.
+- **Persist knowledge early.** After Day 2, run `/fluent-knowledge-init` to capture your account's conventions, integration contracts, and test data patterns. This makes every subsequent session more accurate.
+- **Natural language first, slash commands for precision.** Use plain English for intent-driven tasks. Use `/fluent-<skill>` when you know exactly what you want and want to skip routing.
+
+---
+
+## Further Reading
+
+| Document | What it covers |
+|---|---|
+| [Prompt Guide](02-prompt-guide.md) | Which skills exist, what to type, routing, and lifecycle |
+| [Use Cases](03-use-cases.md) | 21 scenario-based prompts with expected outcomes |
+| [Dev Workflow](06-dev-workflow.md) | Full autonomous development protocol and approval gate rules |

package/docs/05-getting-started.md

@@ -0,0 +1,262 @@
+# Setup Reference & Troubleshooting
+
+> [!CAUTION]
+> **EXPERIMENTAL - LABS PROJECT**
+> This package is not production-ready. No stability guarantees, no support, no warranty. See [README](../README.md) for full disclaimer.
+
+Prerequisites, workspace layout, and troubleshooting for `@fluentcommerce/ai-skills`.
+
+**First time?** Start with [Your First Session](01-first-session.md) — a 20-minute guided walkthrough.
+**Which skill for what?** See [Prompt Guide](02-prompt-guide.md) — progressive skill navigator.
+**Reading order:** See [INDEX.md](INDEX.md) for the numbered documentation path.
+
+> **Examples below use Claude Code slash commands.** In Codex or Gemini CLI, use natural-language prompts instead of `/fluent-*` commands.
+
+---
+
+## Table of Contents
+
+- [1. Prerequisites](#1-prerequisites)
+- [2. Install and Connect](#2-install-and-connect)
+- [3. Workspace Layout](#3-workspace-layout)
+- [4. The Approval Gate](#4-the-approval-gate)
+- [5. Resuming Work Across Sessions](#5-resuming-work-across-sessions)
+- [6. Troubleshooting](#6-troubleshooting)
+
+---
+
+## 1. Prerequisites
+
+| Requirement | How to check |
+|-------------|-------------|
+| Node.js 18+ (20+ recommended) | `node --version` |
+| Fluent CLI installed | `fluent --version` (install from [docs.fluentcommerce.com](https://docs.fluentcommerce.com/building-blocks/fluent-cli-package)) |
+| A Fluent Commerce account | Base URL, credentials, and a retailer to work with |
+| A Fluent CLI profile configured | `fluent profile create YOUR_PROFILE --id <id> --username <user> --password <pass> --client-secret <secret> --base-url <url>` |
+| Anthropic account | [console.anthropic.com](https://console.anthropic.com) — Claude Code prompts on first launch |
+| Claude Code, Codex, or Gemini CLI | Claude Code is the primary target; Codex and Gemini CLI support is experimental |
+
+See the [README](../README.md) for full installation details.
+
+---
+
+## 2. Install and Connect
+
+```bash
+npx @fluentcommerce/ai-skills install --profile YOUR_PROFILE
+```
+
+This single command:
+- Installs all Fluent skill groups into your IDE (Claude Code marketplace plugin, or file-copy fallback)
+- Auto-generates `.mcp.json` with three MCP servers: `fluent-mcp` (official CLI), `fluent-mcp-extn` (extension tools), and `chrome-devtools` (browser UI testing)
+- Copies packaged `knowledge/` and `docs/` into the workspace
+- Generates starter `CLAUDE.md` and `AGENTS.md` workspace instruction files when they do not already exist
+- Checks prerequisites and reports any issues
+
+> **First-run permission prompts:** Claude Code runs in a sandboxed mode. During `/fluent-connect`, it will ask permission to run shell commands, read `~/.fluentcommerce/`, and write workspace files under `accounts/`. This is normal — approve each prompt.
+
+**Variations:**
+
+```bash
+# Skills only (no MCP):
+npx @fluentcommerce/ai-skills install
+
+# Add MCP later:
+npx @fluentcommerce/ai-skills mcp-setup --profile YOUR_PROFILE
+
+# Faster MCP startup (pre-install extension locally):
+npx @fluentcommerce/ai-skills install --profile YOUR_PROFILE --install-mcp-extn
+```
+
+If you already know the **retailer ref**, add `--profile-retailer YOUR_RETAILER_REF`.
+
+For the guided first-time walkthrough after install, see [first-session.md](01-first-session.md).
+
+---
+
+## 3. Workspace Layout
+
+After install + `/fluent-connect`:
+
+```
+<project-root>/
+  .mcp.json                        ← workspace MCP wiring
+  CLAUDE.md                        ← starter workspace instructions for Claude Code
+  AGENTS.md                        ← starter workspace instructions for Codex/agentic tooling
+  knowledge/                       ← packaged platform knowledge copied locally
+  docs/                            ← packaged reference docs copied locally
+accounts/<PROFILE>/
+  SOURCE/                          ← All implementation source code
+    backend/                       ← Java Maven plugin repos
+    frontend/                      ← Mystique SDK component projects
+  workflows/<RETAILER>/            ← downloaded workflow JSONs
+    ORDER__HD.json
+    workflow-context.json          ← download metadata
+  features/                        ← Feature lifecycle dirs
+    <slug>/spec.md                 ← requirements (from use-case-discover)
+    <slug>/plan.md                 ← approved plan (from feature-plan)
+    <slug>/architecture.md         ← feature explain output
+    <slug>/status.json             ← lifecycle state tracker
+  tasks/                           ← Operational plans (non-feature work)
+  reports/                         ← Ephemeral: build, pre-deploy, e2e-test outputs
+  analysis/                        ← Persistent: code, modules, topology, settings
+  feedback/                        ← Skill execution feedback
+  sessions/                        ← Audit trail exports
+  settings/backups/                ← Setting backups
+  manifests/backups/               ← Manifest backups
+  knowledge/                       ← Account-specific knowledge overrides
+```
+
+Each directory includes a `README.md` explaining its purpose and which skills populate it.
+
+---
+
+## 4. The Approval Gate
+
+The AI never makes changes without asking first:
+
+1. **Presents a plan** — structured markdown with diagrams, rules, risks, and test plan
+2. **Waits for review** — you can ask questions, request changes, or reject
+3. **You approve** — say `"approved"`, `"yes"`, `"go ahead"`, or `"do it"`
+4. **Implementation begins** — the AI follows the plan step by step
+
+**Triggers the gate:** Any change to code, workflows, settings, or the live environment.
+
+**Skips the gate:** Read-only operations (explain, trace, analyze, audit, diagnose).
+
+**Override:** Say `"just do it"` or `"skip planning"` to bypass the gate entirely (logged as user override).
+
+---
+
+## 5. Resuming Work Across Sessions
+
+The AI persists progress in `status.json` files and reads them to resume where you left off.
+
+**Check what is in progress:**
+
+```
+What features are in progress?
+```
+
+**Resume a feature:**
+
+```
+Continue working on return orders
+```
+
+The AI reads `status.json`, finds the `next` field (e.g., `"/fluent-build"`), and picks up from that step.
+
+---
+
+## 6. Troubleshooting
+
+### MCP tools not working
+
+**Symptom:** The AI cannot reach the Fluent environment, or tool calls return connection errors.
+
+**Diagnostic checklist:**
+
+```bash
+# 1. Verify Fluent CLI
+fluent --version                          # should print version
+
+# 2. Verify profile
+ls ~/.fluentcommerce/YOUR_PROFILE/        # should exist
+fluent profile retailers YOUR_PROFILE     # should list retailers
+
+# 3. Verify .mcp.json
+cat .mcp.json                             # should have fluent-mcp, fluent-mcp-extn, and chrome-devtools entries
+
+# 4. Test MCP extension server (Ctrl+C to exit)
+npx @fluentcommerce/fluent-mcp-extn
+
+# 5. Test official MCP server
+fluent mcp server --stdio                 # should start (Ctrl+C to exit)
+
+# 6. Regenerate MCP config
+npx @fluentcommerce/ai-skills mcp-setup --profile YOUR_PROFILE
+
+# 7. Restart your IDE — MCP servers initialize at startup
+```
+
+**Quick fix:** Re-run the install with `--profile` to regenerate everything:
+```bash
+npx @fluentcommerce/ai-skills install --profile YOUR_PROFILE
+```
+
+### No workflows found
+
+**Symptom:** The AI reports no workflows available for analysis.
+
+**Fix:**
+1. Run `/fluent-connect` to download workflows from the live environment
+2. Or manually: `fluent workflow download -p YOUR_PROFILE -r YOUR_RETAILER -w all -o accounts/YOUR_PROFILE/workflows/YOUR_RETAILER/`
+3. Check `accounts/<PROFILE>/workflows/<RETAILER>/` for `*.json` files
+
+### Workflow changes not taking effect after deploy
+
+**Symptom:** You deployed a workflow but the AI (or the live environment) still shows the old version.
+
+**Fix:** Three caching layers can cause this — check each in order:
+
+1. **MCP cache** — The extension server caches workflow reads. Clear it:
+   ```
+   Clear the MCP workflow cache
+   ```
+
+2. **Local files** — Files in `accounts/<PROFILE>/workflows/` are static snapshots. Re-download:
+   ```
+   /fluent-connect --profile MY_PROFILE --force
+   ```
+
+3. **Workflowlog** — If you deployed via MCP `workflow_upload` or REST API (not CLI), the CLI workflowlog is stale. Fix:
+   ```bash
+   fluent workflowlog delete -p MY_PROFILE
+   ```
+
+**Full reference:** See [Workflow Caching & Staleness](workflow-reference.md#workflow-caching--staleness) for details.
+
+### "Plan required" error
+
+**Symptom:** The AI refuses to scaffold, build, or deploy and says a plan is required.
+
+**Fix:** The approval gate is working as intended. Either:
+- Say `"Plan the <feature-name> feature"` to generate a plan, then `"approved"`
+- Say `"just do it"` to bypass the gate (logged as override)
+
+### Rule not found in workflow
+
+**Symptom:** A workflow references a custom rule the environment does not recognize.
+
+**Fix:** Deploy the module before the workflow:
+1. `"Build the my-returns module"` — compile and package
+2. `"Deploy my-returns to MY_RETAILER"` — install on the account
+3. `"Deploy RETURN_ORDER__DEFAULT to MY_RETAILER"` — now the rules are available
+
+### Skills not loading after install
+
+**Symptom:** The AI does not recognize Fluent commands or slash commands.
+
+**Fix:**
+1. Run diagnostics: `npx @fluentcommerce/ai-skills doctor`
+2. Verify: `npx @fluentcommerce/ai-skills status`
+3. Restart your IDE — skills load at startup
+4. For Claude Code with marketplace: check `~/.claude/plugins/installed_plugins.json`
+5. For Claude Code with file-copy: check that `~/.claude/agents/` and `~/.claude/skills/` have fluent content
+6. Re-install: `npx @fluentcommerce/ai-skills install`
+
+### I keep getting permission prompts
+
+**Symptom:** The IDE keeps asking for access to the CLI, `~/.fluentcommerce/`, `.mcp.json`, `accounts/`, or other workspace files.
+
+**Fix:** This is expected on the first run. `fluent-connect` and `fluent-bootstrap` do real shell and filesystem work. Approve prompts that match the task you asked for, then restart the IDE if the skill updated `.mcp.json`.
+
+### Chrome DevTools MCP not working
+
+**Symptom:** The AI reports "Chrome DevTools MCP not connected" when you try to test a page in the browser.
+
+**Fix:**
+1. Verify `.mcp.json` has a `chrome-devtools` server entry
+2. Restart your IDE — MCP servers initialize at startup
+3. Verify `npx chrome-devtools-mcp@latest` runs without errors
+4. Check that the `FLUENT_UI_BASE_URL` points to the correct account and environment