---
name: fluent-frontend-readme
description: Auto-generate README.md for Mystique SDK component projects. Reads actual source code to produce documentation with component table, build instructions, manifest configuration, settings dependencies, and deployment guide. Triggers on "generate readme", "document component", "frontend readme", "sdk readme", "component docs".
user-invocable: true
allowed-tools: Bash, Read, Write, Edit, Glob, Grep
argument-hint: [project-path]
cursor-tier: auto
planning-gate: none
---

# Frontend README Generator

Auto-generate a comprehensive `README.md` for an SDK component project by reading the actual source code. Not a template — it inspects registrations, hooks, settings, and manifests to produce accurate documentation.

## Pre-flight: Feedback Check

Before starting, check for past learnings from this skill:

1. Check if `accounts/<PROFILE>/feedback/fluent-frontend-readme.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

## Ownership Boundary

| Does | Does NOT |
|---|---|
| Read source to extract component registrations | Modify source code |
| Generate README.md with accurate component table | Build the project (-> `/fluent-frontend-build`) |
| Document manifest configuration examples | Deploy anything |
| List settings dependencies from useSettings() calls | Review code quality (-> `/fluent-frontend-review`) |
| Provide build/test/deploy instructions | |

## When to Use

- After scaffolding a new project (`/fluent-mystique-scaffold`)
- After adding components (`/fluent-mystique-component`)
- When `/fluent-frontend-review` reports README missing
- When preparing a project for handover/documentation

## Required Inputs

Project path: `accounts/<PROFILE>/SOURCE/frontend/<project>/`

## What It Reads

1. **`src/index.tsx`** — All `ComponentRegistry.register()`, `FieldRegistry.register()`, and `TemplateRegistry.register()` calls -> component aliases, field types, helper names
2. **`src/components/*/`** — Component files -> props interfaces, hook usage
3. **`src/fields/*/`** — Field files -> field type names, props
4. **`package.json`** — name, version, description, scripts
5. **`manifests/*.ts`** (if present) — Manifest definitions with gql queries -> configuration examples
6. **`src/**/*.{ts,tsx}`** — All `useSettings()` / `getSettings()` calls -> settings dependencies
7. **`src/**/*.{ts,tsx}`** — All `useQuery()` / `getQuery()` calls -> GraphQL dependencies
8. **`src/**/*.{ts,tsx}`** — All `<Children />`, `descendantsOverride`, `dataOverride`, `useData()`, and `dataSource` usage -> parent/child data flow
9. **`webpack.config.ts`** — Externals config, output config

## Generated README Structure

Generate `README.md` in the project root with these sections:

```markdown
# <Project Title>

<Description from package.json, or generated from component registrations>

## Components

| Alias | Category | Description |
|-------|----------|-------------|
| <namespace>.<category>.<name> | content | <from JSDoc or generated> |

## Fields (if any)

| Field Type | Description |
|------------|-------------|
| <type-name> | <from JSDoc or generated> |

## Template Helpers (if any)

| Helper Name | Description | Usage |
|-------------|-------------|-------|
| <alias> | <from JSDoc or generated> | `{{helperName arg1 arg2}}` |

## Data Access Contract

Describe how runtime data reaches each major component:

- Which components consume `props.data` or `useData()`
- Which manifest `dataSource` paths they expect
- Where `<Children />` or `<Children dataOverride={...} />` is used to scope or transform descendants
- Which page `data` / `dataSources` blocks or `fc.provider.graphql` providers supply shared queries
- Which `useQuery()` calls remain and why page/provider data was insufficient

## Prerequisites

- Node.js 16-18 (not 20+ due to OpenSSL changes)
- Yarn 1.x
- OMX Component SDK types (`@types/mystique/`)

## Development

```bash
yarn install          # Install dependencies
yarn start            # Hot-reload dev server at localhost:3001
yarn test             # Run tests with coverage
yarn storybook        # Launch Storybook for component development
yarn lint             # Check code style
yarn lint:fix         # Auto-fix lint issues
```

## Build

```bash
yarn build            # Production bundle -> dist/bundle.[hash].js + dist/version.json
```

## Local Test Loop (Recommended)

1. Start local dev server: `yarn start` (serves plugin on `http://localhost:3001/`)
2. Point manifest `plugins[]` to `http://localhost:3001/`
3. Verify in UI and iterate: edit code -> auto-rebuild -> hard refresh -> re-test
4. When ready for release: stop dev server, run `yarn build`, upload `dist/`, switch `plugins[]` to CDN URL

## Local Testing (Recommended First)

Test components in the live Fluent UI before deploying to CDN:

1. Start the dev server: `yarn start` (serves at `http://localhost:3001/` with hot-reload)
2. Add localhost to your manifest `plugins[]`:
   ```json
   { "plugins": [{ "type": "url", "src": "http://localhost:3001/" }] }
   ```
3. Deploy manifest setting to Fluent (`valueType: "JSON"`, `context: "ACCOUNT"`, `contextId: 0`)
4. Open the Fluent UI page — your component loads from localhost
5. Edit source code → webpack auto-rebuilds (1-3s) → browser hot-reloads
6. Repeat until satisfied, then switch to production build

> **Important:** Remove the localhost URL from `plugins[]` before deploying to other environments.

## Configure in Manifest

Add this plugin to your Mystique manifest's `plugins` array:

### Development (local)
```json
{ "plugins": [{ "type": "url", "src": "http://localhost:3001/" }] }
```

### Production (CDN)
```json
{ "plugins": [{ "type": "url", "src": "https://your-cdn.com/your-plugin/" }] }
```

> **Trailing `/` is required** — Mystique fetches `<src>/version.json` to discover the bundle hash.

Then reference components in page definitions:
```json
{
  "component": "fc.page",
  "data": {
    "query": "query order($id: ID!) { orderById(id: $id) { id ref status fulfilments { edges { node { id ref status } } } } }",
    "variables": { "id": "{{params.id}}" }
  },
  "descendants": [
    {
      "component": "<alias>",
      "dataSource": "orderById",
      "props": { "...": "..." }
    }
  ]
}
```

## Settings Dependencies (if any)

This plugin reads the following Fluent settings at runtime:

| Setting Key | Used By | Purpose |
|-------------|---------|---------|
| <key> | <component> | <description> |

## Deploy

1. Run `yarn build` to produce `dist/`
2. Upload `dist/` folder to a CDN (Vercel, S3, CloudFront)
3. Set short cache TTL on `version.json` (seconds), long TTL on bundle files (days)
4. Update manifest `plugins[]` with the CDN URL (trailing `/` required for version.json auto-discovery)
5. Deploy manifest as a Fluent setting (`valueType: "JSON"`, `context: "ACCOUNT"`, `contextId: 0`)
6. Verify in browser via `/fluent-ui-test`
7. Confirm no deployed manifest still points to `http://localhost:3001/`

## Architecture

- **Runtime externals:** React 17, ReactDOM, Material-UI 4.12, Mystique — provided by the host app
- **Bundle output:** Single `bundle.[contenthash].js` loaded via `plugins[]`
- **Registration:** Components registered in `src/index.tsx` via `ComponentRegistry.register()`, fields via `FieldRegistry.register()`, and template helpers via `TemplateRegistry.register()`
```

## Execution Flow

```
1. READ package.json -> extract name, version, description, scripts
2. READ src/index.tsx -> parse ComponentRegistry.register(), FieldRegistry.register(), and TemplateRegistry.register() calls
   - Extract: aliases[], categories[], component names
3. FOR EACH component in src/components/*/:
   - Read the main .tsx file
   - Extract props interface (field names + JSDoc)
   - Extract hook usage (useQuery, useSettings, useData, useAuth)
4. FOR EACH field in src/fields/*/ (if any):
   - Read the main .tsx file
   - Extract field type name and props
5. SCAN all .ts/.tsx for useSettings()/getSettings() calls -> extract setting keys
6. SCAN all .ts/.tsx for useQuery()/getQuery() calls -> note GraphQL dependencies
7. TRACE data flow across useData(), props.data, dataSource, Children/dataOverride, and provider queries
8. READ manifests/*.ts (if present) -> extract sample manifest configuration
9. READ webpack.config.ts -> extract externals list
10. GENERATE README.md from collected data
11. WRITE to <project>/README.md
```

If README.md already exists, ask the user before overwriting. Offer to merge or replace.

## Integration with Other Skills

| Artifact | Consumed by |
|---|---|
| README.md | `/fluent-frontend-review` Phase 6 (README check) |
| README.md | User documentation / handover |

## Gotchas

- **Don't parse node_modules/**: Only scan `src/`, `manifests/`, and root config files
- **Register calls may be dynamic**: Some projects use loops or arrays to register multiple components. Handle `['alias1', 'alias2'], Component` syntax
- **Manifests may not exist**: Older SDK projects don't have TypeScript manifests. Skip the manifest section if no `manifests/` directory
- **gql tag**: Manifest files use `gql` tag for GraphQL. Don't try to parse GraphQL -- just note that queries are present
- **Existing README**: If README.md already exists, read it first and ask user whether to replace, merge, or skip

## 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-frontend-readme"`
   - `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-frontend-readme.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 -->
