docs(rules): add 815-reactflow-diagrams rule and skill

- Add rules/815-reactflow-diagrams.mdc for interactive architecture
  canvases with @xyflow/react
- Add skills/reactflow-architecture-diagrams/ with SKILL.md and
  static-vs-interactive reference
- Cross-reference from 810-documentation.mdc and the
  documentation-standards skill so static (Mermaid/Markdown) and
  interactive (React Flow) diagram guidance coexist cleanly

Separates "static diagrams in Markdown" from "live React Flow
canvases in a SPA" so each has a dedicated playbook and reviewers
can pick the right medium per page.

Author: d-padmanabhan

rules/810-documentation.mdc

@@ -631,6 +631,12 @@ Include in PR checklist:
 -  Skip the basics
 -  Use unclear language
 
+## Interactive canvases (@xyflow/react)
+
+For **live** architecture diagrams in a React SPA (custom nodes, animated edges, optional Cloudflare orange shell grouping), use **[815-reactflow-diagrams.mdc](815-reactflow-diagrams.mdc)** and the **`reactflow-architecture-diagrams`** skill under `skills/reactflow-architecture-diagrams/`.
+
+Static diagrams in Markdown still use **[800-markdown.mdc](800-markdown.mdc)** (Mermaid). Pick one primary medium per page and cross-link when both exist.
+
 ## Review Checklist
 
 When reviewing documentation, check:

rules/815-reactflow-diagrams.mdc

@@ -0,0 +1,78 @@
+---
+title: Interactive architecture diagrams (React Flow)
+description: >-
+  Conventions for narrative @xyflow/react canvases: custom nodes and edges,
+  semantic stroke colors, Cloudflare orange shell grouping, readability inside
+  tinted frames, handles, and verification before merge.
+priority: 815
+alwaysApply: false
+files:
+  include:
+    - "**/*Diagram.tsx"
+    - "**/components/diagrams/**/*.tsx"
+---
+
+# Interactive architecture diagrams (React Flow)
+
+**Goal:** Ship readable, consistent **narrative** diagrams in a React SPA using [`@xyflow/react`](https://reactflow.dev/) (React Flow): fixed layout, animated edges where they help, and prose on a sibling page that explains scope (what is in-band vs out-of-band).
+
+This rule complements **[800-markdown.mdc](800-markdown.mdc)** (Mermaid in Markdown). Use **800** for static docs diagrams; use **815** when the diagram is **TypeScript + React Flow**.
+
+## When this rule applies
+
+Use for **interactive** canvases (not image-only figures). Typical stack: React, TypeScript, Vite, Tailwind, optional React Router. Package manager may be Bun or npm per project.
+
+## File and route layout (SPA)
+
+Adapt paths to your repo, but keep separation of concerns:
+
+- **Diagram**: `**/components/diagrams/<Name>Diagram.tsx` (or your agreed folder) exporting `<Name>Diagram`.
+- **Page**: route-level view that wraps copy + `<Name />` (figure, legend, diagram).
+- **Router and index**: register the path and add a card or link from the app home so deep links are discoverable.
+- **README**: document new routes and any `public/` reference assets.
+
+## React Flow defaults (narrative mode)
+
+- Outer container: bordered, dark background, bounded height (for example `min(88dvh, …)`).
+- `fitView` with tuned `fitViewOptions` (`padding`, `maxZoom`) and sensible `minZoom` / `maxZoom` for the graph size.
+- `proOptions={{ hideAttribution: true }}` where license allows.
+- Read-only story: `nodesDraggable={false}`, `nodesConnectable={false}` unless the product is an editor.
+- Canvas chrome: `react-flow dark` base, `!bg-slate-950`, `[&_.react-flow__node]:overflow-visible` when handles or labels extend past node boxes.
+- **Dots** `Background` and **Controls** styled to match the app (slate theme is common).
+- Wrap custom node and edge components in **`memo()`**; pass stable **`nodeTypes`** / **`edgeTypes`** objects (module scope), not new literals each render.
+- Prefer **`buildNodesAndEdges()`** returning `{ nodes, edges }` at module scope for static graphs so types and data stay stable.
+
+## Cloudflare orange shell (optional)
+
+When the story includes **traffic inside Cloudflare**:
+
+- Reuse a shared **shell** node component (rounded orange border, subtle inner glow, optional header row with logo + title).
+- Parent node: explicit `style.width` / `style.height`, `overflow: 'visible'`, explicit `zIndex`. Insert the **parent before children** in the `nodes` array.
+- Children: `parentId`, `extent: 'parent'`, positions **relative to the parent** (subtract parent world position).
+- **`showHeader: false`** on the shell when an inner banner or grid already titles the zone (avoids double headers).
+
+## Readability inside tinted frames
+
+- Avoid **orange-on-orange** (or any tint-on-same-tint) for primary labels.
+- Prefer an **opaque inner card** (slate background, strong border, light ring) for nodes that must stay legible on an orange or warm shell.
+
+## Edges and meaning
+
+- **Semantic colors**: assign meaning (for example sky = client request path, orange = Cloudflare-internal hop, violet = IdP/JWKS, slate = cache return).
+- Match **arrow head** color to the edge stroke.
+- **Dashed** `strokeDasharray` for secondary, cached, or **out-of-band** flows (for example OIDC token issuance vs JWKS fetch) so readers do not merge stories.
+- Short **edge labels** with `labelStyle` / `labelBgStyle` / `labelBgPadding` for legibility on dark backgrounds.
+- Multiple edges from one side: use **`sourceHandle` / `targetHandle`** and stable **`id`s** on each `Handle`.
+
+## Assets
+
+- Icons: keep under **`public/`** and reference with absolute web paths (for example `/logos/cloudflare.svg`).
+- Large reference PNGs: same; document ownership and usage in README.
+
+## Verification
+
+Run the project's **lint** and **production build** (or typecheck) for the SPA before merge. For Bun-first apps: `bun run lint` and `bun run build` from the app root.
+
+## Agent skill
+
+For a step-by-step playbook (new diagram page, shell, legend copy), use the **`reactflow-architecture-diagrams`** skill under `skills/reactflow-architecture-diagrams/`.

skills/documentation-standards/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: documentation-standards
-description: Documentation best practices including Markdown formatting, Mermaid diagrams, technical writing, ADRs, and open source standards. Use when writing documentation, README files, markdown content, creating diagrams, or when asking about documentation structure, technical writing, or open source project setup.
+description: >-
+  Documentation best practices including Markdown formatting, Mermaid diagrams,
+  technical writing, ADRs, and open source standards. Use when writing
+  documentation, README files, markdown content, creating static diagrams in
+  Markdown, or when asking about documentation structure, technical writing, or
+  open source project setup. For interactive React Flow canvases in a SPA, use
+  the reactflow-architecture-diagrams skill instead.
 ---
 
 # Documentation Standards
@@ -113,6 +119,11 @@ def hello():
 | Cell 1   | Cell 2   |
 ```
 
+## Interactive vs static diagrams
+
+- **Static (Markdown):** Mermaid in this skill and in `rules/800-markdown.mdc`.
+- **Interactive (React SPA):** `@xyflow/react` patterns, playbook, and rule **`rules/815-reactflow-diagrams.mdc`** - use skill **`skills/reactflow-architecture-diagrams/`**. See [references/static-vs-interactive.md](../reactflow-architecture-diagrams/references/static-vs-interactive.md) for a short comparison table.
+
 ## Mermaid Diagrams
 
 ### Flowchart
@@ -167,6 +178,7 @@ graph LR
 
 ## Detailed References
 
+- **React Flow (interactive canvases)**: See `skills/reactflow-architecture-diagrams/SKILL.md` and `rules/815-reactflow-diagrams.mdc`
 - **Markdown & Mermaid**: See [references/markdown-mermaid.md](references/markdown-mermaid.md)
 - **Technical Writing**: See [references/technical-writing.md](references/technical-writing.md)
 - **Open Source**: See [references/open-source.md](references/open-source.md)

skills/reactflow-architecture-diagrams/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: reactflow-architecture-diagrams
+description: >-
+  Delivers narrative interactive architecture diagrams using React, TypeScript,
+  Tailwind, and @xyflow/react (React Flow): node and edge patterns, optional
+  Cloudflare orange shell grouping, routing, and verification. Use when adding
+  or editing React Flow diagram components (Diagram.tsx suffix convention),
+  files under components/diagrams, xyflow
+  edges, animated canvas traffic, or when the user asks for a React Flow
+  architecture diagram alongside documentation.
+---
+
+# React Flow architecture diagrams
+
+## Canonical rule
+
+Follow **`rules/815-reactflow-diagrams.mdc`** for do/don't lists, file globs, and edge semantics. This skill is the **playbook**; the rule is the **contract**.
+
+## When to use Mermaid vs React Flow
+
+- **Mermaid** (see `rules/800-markdown.mdc` and `skills/documentation-standards`): static diagrams in Markdown, ADRs, GitHub-rendered docs.
+- **React Flow**: interactive or animated canvases, custom nodes (logos, multi-line cards), and **legend + diagram** product pages.
+
+## Playbook: add a new diagram to an existing SPA
+
+1. **Pick a reference** diagram in the same app (or copy patterns from `815`) and reduce scope; keep one story per canvas.
+2. **Implement** `buildNodesAndEdges()` (or equivalent) returning `{ nodes, edges }`. Keep `nodeTypes` and `edgeTypes` at **module scope** with `memo()`-wrapped components.
+3. **Add** a route page: title, scope (what one request or one flow shows), optional static reference image, **How to read** bullets that map **colors and line styles** to meaning, then `<YourDiagram />`.
+4. **Wire** the router and home or index links; update **README** routes and assets tables when paths or figures change.
+5. **Run** lint and production build from the app directory.
+
+## Playbook: Cloudflare-scoped traffic
+
+1. Add a **parent** shell node (`cfShell` or your name) with fixed width/height and `overflow: 'visible'`.
+2. Nest **child** nodes with `parentId` + `extent: 'parent'`; convert world coordinates to **parent-relative** positions.
+3. Use **opaque inner cards** for text-heavy nodes sitting on the orange frame (see `815`).
+
+## Playbook: identity and edge cases
+
+- **JWKS / metadata fetch** is not the same as **OIDC login**. If both appear, use **dashed** edges and distinct colors for issuance vs verification, and say so in page copy.
+
+## Verification
+
+Do not skip **lint** and **build** (or `tsc -b`) after graph or handle changes; broken `Handle` ids fail at runtime.

skills/reactflow-architecture-diagrams/references/static-vs-interactive.md

@@ -0,0 +1,10 @@
+# Static vs interactive architecture diagrams
+
+| Aspect | Mermaid (Markdown) | React Flow (SPA) |
+| --- | --- | --- |
+| Where | `*.md`, ADRs, wiki | `*Diagram.tsx`, routed pages |
+| Rule | `800-markdown.mdc` | `815-reactflow-diagrams.mdc` |
+| Strength | Versioned text, easy review diff | Animation, logos, complex layout |
+| Tradeoff | Less precision for icons | More code to maintain |
+
+Pick one primary medium per deliverable; cross-link from docs to the SPA route when both exist.