---
name: fluent-bootstrap
description: Complete Fluent Commerce account bootstrap wizard. Use when setting up a new account from scratch, creating profiles, retailers, and installing reference modules with sample data. Triggers on "bootstrap account", "set up fluent", "new fluent account", "initialize account".
user-invocable: true
allowed-tools: Bash, Read, Write, Edit, Glob, Grep
argument-hint: [profile-name] [retailer-ref]
cursor-tier: auto
planning-gate: advisory
---

# Fluent Account Bootstrap

Complete account setup from profile creation to sample data installation.

## Pre-flight: Feedback Check

Before starting, check for past learnings from this skill:

1. Check if `accounts/<PROFILE>/feedback/fluent-bootstrap.jsonl` exists
2. If yes, read last 20 records
3. Filter to: FAILURE or USER_CORRECTED outcomes, confidence = CONFIRMED or PROMOTED
4. Extract top 3 relevant learnings — use as internal guidance during execution
5. Do NOT show raw feedback to the user — silently adjust approach based on past issues

## Planning Gate

### Pre-flight: Plan Verification

Before proceeding, check for an existing approved plan:

1. **Search** `accounts/<PROFILE>/features/*/status.json` for an entry with `plan: "APPROVED"` that covers this bootstrap, OR check `accounts/<PROFILE>/tasks/` for a task plan with `Status: APPROVED`
2. **If multi-artifact work** (bootstrap + custom rules + workflows): STOP. Invoke `/fluent-feature-plan` first — this skill cannot be used for multi-artifact work without a feature plan
3. **If approved plan found:** Skip to implementation, referencing the plan's relevant sections
4. **If no plan found:** Continue to the Planning Gate below to write a plan for this skill

**Before bootstrapping any account, write a plan using the template from `PLAN_TEMPLATE.md` in the `fluent-feature-plan` skill.** Account bootstrap is a high-impact operation.

**Bootstrap-specific emphasis — ensure these are covered:**

1. **Business Context (Section 1)** — purpose of this account; sandbox/dev/staging/prod
2. **Scope (Section 2)** — profile name, base URL, auth method
3. **Impacted retailers (Section 4.8)** — retailer ref, trading name, type; confirm NOT production
4. **Detailed Design (Section 5)** — reference modules to install (with versions), sample data to load
5. **GraphQL operations (Section 4.7)** — mutations for retailer creation, module installation
6. **Deployment Sequence (Section 9)** — profile → retailer → modules → sample data order
7. **Risks (Section 7)** — high-impact: confirm environment; note what's irreversible

**Write the plan to:** `accounts/<PROFILE>/tasks/<YYYY-MM-DD>-bootstrap-<slug>.md`. Set `Status: PENDING`.

Present the full plan content to the user and wait for approval before proceeding. On approval, update the file to `Status: APPROVED`. If the user says "just do it", proceed directly (still write the file for audit trail).

> **New to Fluent CLI?** Start with `/fluent-cli-index` for a complete command reference and routing guide.

## Handoff Protocol

### Signals emitted by this skill

| Signal | Condition | Example |
|--------|-----------|---------|
| `-> READY: <path>` | Account bootstrapped | `-> READY: Account MY_PROFILE bootstrapped with retailer MY_RETAILER` |
| `-> NEXT: /fluent-<skill>` | Ready for module/workflow deploy | `-> NEXT: /fluent-module-deploy` |
| `-> BLOCKED: <reason>` | Cannot proceed | `-> BLOCKED: ENV_UNREACHABLE — Cannot connect to Fluent environment` |

### Error codes

| Code | Condition | Recovery |
|------|-----------|----------|
| `PLAN_REQUIRED` | Bootstrap attempted without approved plan | Run `/fluent-feature-plan` first |
| `ENV_UNREACHABLE` | Cannot connect to Fluent environment | Check credentials and profile via `/fluent-profile` |

## When to Use

- Setting up a new Fluent Commerce account from scratch
- User asks to "bootstrap", "set up new account", "initialize fluent account"
- Creating a complete B2C or B2B implementation environment

## Prerequisites Checklist

Before starting, gather:
- [ ] Account ID
- [ ] Base URL (e.g., `https://account.sandbox.api.fluentretail.com`)
- [ ] Admin username & password
- [ ] Client secret
- [ ] Retailer reference & admin email

## Cross-Platform Command Notes

- Fluent CLI commands are portable across macOS, Linux, and Windows.
- Use `rg` for placeholder scans because it works consistently in Bash, zsh, and PowerShell.

## Bootstrap Workflow

### Phase 1: Profile & Retailer Setup

```bash
# 1. Create profile
fluent profile create <profile-name> \
  --id <account-id> \
  --base-url <base-url> \
  --username <username> \
  --password <password> \
  --client-secret <client-secret>

# 2. Verify profile
fluent profile list
fluent profile active

# 3. Create retailer
# FINAL CONFIRMATION — Retailer creation is IRREVERSIBLE.
# Before executing, confirm with the user:
#   "You are about to create retailer '<retailer-ref>' on <base-url>.
#    This cannot be undone. Proceed? (yes/no)"
# Only proceed after explicit "yes" confirmation.
fluent retailer create <retailer-ref> \
  --email <retailer-email> \
  --profile <profile-name>

# 4. Set active context
fluent profile use <profile-name> --retailer <retailer-ref>
```

**Retailer creation gotchas:**
- **Always use `fluent retailer create` CLI** — do NOT use the `createRetailer` GraphQL mutation. The mutation returns null and creates REST-only entities invisible to GraphQL. The CLI uses batch jobs to create fully-initialized retailers.
- After creating a retailer, add a retailer-scoped admin user via `fluent profile update` so you have credentials for REST API calls and retailer-scoped events.
- Account-level users generate CREATE events with `retailerId=0`, which causes workflow routing mismatches. Use retailer-scoped users for operations that trigger workflows.

### Phase 2: Module Configuration

```bash
# Generate config templates for each module
fluent module config core --retailer <retailer-ref> --profile <profile-name>
fluent module config fulfilment --retailer <retailer-ref> --profile <profile-name>
fluent module config order --retailer <retailer-ref> --profile <profile-name>
fluent module config inventory --retailer <retailer-ref> --profile <profile-name>
```

**Generated files:** `module.config.<retailer>.<module>.json`

**Common config tokens (placeholder -> example value):**

| Token | Example Value | Used By |
|-------|---------------|---------|
| `[[retailer.id]]` | `1` | order, fulfilment, inventory |
| `[[productCatalogue.ref]]` | `PC:MASTER:1` | order |
| `[[network.ref.hd]]` | `B2C_HD_1` | order (home delivery routing) |
| `[[network.ref.cc]]` | `B2C_CC_1` | order (click & collect routing) |
| `[[virtualCatalogue.ref]]` | `BASE:1` | order (availability checks) |
| `[[inventoryCatalogue.ref]]` | `DEFAULT:1` | inventory |
| `[[order.validation.gracePeriodSeconds]]` | `3600` | order (cancel timeout) |

**Check for unreplaced tokens:**
```bash
rg '\[\[.*\]\]' module.config.*.json
```

```powershell
# PowerShell
Select-String -Path "module.config.*.json" -Pattern '\[\[.*\]\]'
```

**WAIT for user to confirm configs are populated before continuing.**

### Phase 3: Module Installation

```bash
# Install in dependency order
fluent module install core --retailer <retailer-ref> --profile <profile-name>

fluent module install fulfilment --retailer <retailer-ref> --profile <profile-name>

fluent module install order \
  --config module.config.<retailer>.order.json \
  --retailer <retailer-ref> --profile <profile-name>

fluent module install inventory \
  --config module.config.<retailer>.inventory.json \
  --retailer <retailer-ref> --profile <profile-name>
```

**Optional: Sample Data**
```bash
# Generate sample data config
fluent module config https://downloads.fluentcommerce.com/v1.0.0/modules/fcx/b2c-sample-data/latest \
  --retailer <retailer-ref> --profile <profile-name>

# Install sample data (after populating config)
fluent module install https://downloads.fluentcommerce.com/v1.0.0/modules/fcx/b2c-sample-data/latest \
  --config module.config.<retailer>.b2c-sample-data.json \
  --retailer <retailer-ref> --profile <profile-name>
```

### Phase 4: Verification

```bash
# Verify installed modules
fluent module list -p <profile-name>

# Verify workflows deployed
fluent workflow list -p <profile-name> -r <retailer-ref>

# Export for API testing
fluent profile export <profile-name> --format postman --retailer <retailer-ref>
```

## Success Criteria

- [ ] Profile created and active
- [ ] Retailer created
- [ ] All reference modules installed
- [ ] Sample data installed (if requested)
- [ ] Workflows visible in list
- [ ] Postman environment exported

## Common Errors

| Error | Solution |
|-------|----------|
| Profile already exists | Use different name or `fluent profile update` |
| Authentication failed | Verify credentials |
| Module dependencies not met | Install `core` first, then others in order |
| Config missing keys | Re-run `fluent module config` |

## Output Artifacts

- `module.config.<retailer>.*.json` - Configuration files
- `postman.<profile>.<retailer>.environment.json` - Postman export

## Post-Execution: Feedback Capture

After completing this skill (whether success or failure), write a feedback record:

1. **Classify outcome:** `SUCCESS` (completed cleanly), `PARTIAL_SUCCESS` (completed after fixing issues), `FAILURE` (could not complete), `BLOCKED` (prereq missing), `USER_CORRECTED` (user overrode approach)
2. **Build record:** Create a `feedback-record-v1` JSON object with:
   - `skill`: `"fluent-bootstrap"`
   - `feature`: feature slug if applicable, null otherwise
   - `phases`: trace of each phase with PASS/FAIL/SKIP
   - `learnings`: any gotchas discovered during execution
   - `userCorrections`: any corrections the user provided
3. **Redact secrets:** Strip tokens, passwords, API keys. Keep business identifiers.
4. **Append** one JSON line to `accounts/<PROFILE>/feedback/fluent-bootstrap.jsonl`
5. **Update** `accounts/<PROFILE>/feedback/index.json` counters (create with `mkdir -p` if missing)

**Skip capture if:** The execution was trivially simple (e.g., user asked a question, no actual write operation happened).

## Known Pitfalls
<!-- feedback-promoted: managed section, updated by feedback loop -->

_(No promoted learnings yet.)_

<!-- end feedback-promoted -->
