docs: add write-feature-docs skill for documenting abs features

.claude/skills/write-feature-docs/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: write-feature-docs
+description: Use when writing or updating ABsmartly Product Documentation pages for a feature - creates or extends Docusaurus pages that match the existing docs conventions, with accurate content and screenshots. Orchestrates the whole flow - researches the feature from the abs codebase, confirms the framing with you, writes the .mdx pages, captures screenshots, and validates the build. Triggers on "document this feature", "write docs for X", "add a docs page for the new Y feature", "/write-feature-docs". Focuses on content + validation; leave worktree/JIRA/PR to start-feature.
+---
+
+# Write Feature Docs
+
+## Overview
+
+Turns an ABsmartly feature into Product Documentation pages on this Docusaurus site, matching how the existing pages look and read. It orchestrates five phases and delegates the abs-specific work (research, screenshots) to the abs repo's **`document-feature-capture`** skill.
+
+This skill owns **content + validation**. It does **not** create worktrees, JIRA tickets, or PRs — that's `start-feature`, which can call this skill as its implementation step.
+
+**Announce at start:** "Using the write-feature-docs skill to document `<feature>`."
+
+## What you need
+
+- A feature to document (name + ideally a pointer: the area of the app, a ticket, or the abs subsystem).
+- The abs checkout at `~/git_tree/abs` **if** you want live research and screenshots. Without it, the skill still writes pages but leaves screenshots as TODOs.
+
+## The five phases
+
+Create a task per phase and work them in order.
+
+```
+Research → Confirm framing → Write pages → Screenshots → Validate
+```
+
+### Phase 1 — Research (delegate)
+
+Invoke **`document-feature-capture`** (research mode) with the specific feature. It returns a structured report describing how the feature actually works — with a **"Confirm before writing"** section listing anything the code can't settle (marketing terms not in code, product-judgment calls, low-confidence claims).
+
+Read the report. It is your source of truth for the content; its cited file paths let you verify specifics.
+
+### Phase 2 — Confirm framing (soft gate)
+
+If the report flagged anything in "Confirm before writing", surface it to the user with **`AskUserQuestion`** before writing: state your understanding of the feature and ask them to confirm or correct the flagged items (e.g. "Are 'Fully' and 'Hybrid' the right names, and is my Hybrid-vs-Fully distinction correct?").
+
+- **Strongly recommended, not hard-blocking.** If the user says "proceed as-is," continue.
+- This is the step that prevents shipping a confidently-wrong framing. Don't skip it when the report flags real product judgment.
+
+### Phase 3 — Write pages
+
+**First, study 2–3 sibling pages** in the same section (`docs/web-console-docs/<area>/`) so your new page matches them. Then write. See `references/docusaurus-conventions.md` for the details: frontmatter (`sidebar_position`, `title`, `description`), the `<Image>` component and its relative import path, `_category_.json`, admonitions (`:::note`, `:::tip`, `:::info`), and internal links/anchors.
+
+Rules that matter:
+
+- **Extend, don't duplicate.** If pages for the area already exist, add to them and insert a new page only for a genuinely new concept. Renumber `sidebar_position` as needed.
+- **Mirror the product's own words** (from the research report's UI strings) for labels and options.
+- **Lead the reader:** overview → concept → step-by-step, with cross-links between the new page and siblings.
+- **Anchor discipline:** when you link to a heading (same-page `#slug` or cross-page `./page#slug`), the slug is the kebab-cased heading. If you rename a heading later, update every link to it.
+
+### Phase 4 — Screenshots (delegate, best-effort)
+
+Decide which screens illustrate the feature (the research report tells you where they live). Invoke **`document-feature-capture`** (capture mode) with a brief: which screens, what state/data, and **save PNGs into `static/img/<feature>/`** in this repo. It will bring the app up screenshot-ready and drive the UI (via `absmartly-tester`).
+
+Then wire the images into the pages with the `<Image>` component. Reuse existing screenshots when they still match the current UI — only (re)capture what's missing or stale.
+
+**Graceful degradation:** if the app can't be brought up (or you're in a docs-only session), write the pages referencing the intended `img` paths, and clearly list the screenshots still owed. Don't block the whole doc on screenshots.
+
+### Phase 5 — Validate
+
+Run the checks in `references/validation.md`:
+
+- Start the dev server; confirm the new/edited pages **compile** (no MDX errors).
+- **Anchors resolve**, no **broken internal links**, and every `<Image>` **loads** (no missing-file / broken-image).
+- Recognize and **ignore the known `cytoscape`/mermaid production-build error** — it's pre-existing and unrelated to feature pages (it comes from a mermaid diagram elsewhere in the docs). Validate via the dev server, which serves pages despite it.
+
+## Done
+
+When pages compile, links/anchors/images check out, and the framing is confirmed, the content is ready. Hand back to the caller (or to `start-feature` / `full-review` / PR flow) for review and merge — those are out of this skill's scope.
+
+## Guardrails
+
+- **Accuracy over completeness.** A flagged-but-honest gap beats a confident wrong statement. Respect the Phase 2 gate.
+- **Match the neighbors.** New pages should be indistinguishable in style from existing Product Documentation pages.
+- **No internal implementation leakage.** Describe what the user configures and sees, not internal mechanisms, unless the product intends them to be public. (This session we removed a Parquet export/import detail at the product owner's request.)
+- **Screenshots must be honest** — real, schema-valid data (the capture skill handles fixtures).
+
+## Integration
+
+- **Invokes:** `document-feature-capture` (abs repo) — research + screenshots.
+- **Invoked by / pairs with:** `start-feature` (owns worktree/JIRA/plan/PR; can call this as its implementation step), `full-review` (closing review).
+
+## References
+
+- `references/docusaurus-conventions.md` — frontmatter, `<Image>`, `_category_.json`, admonitions, links/anchors, the mimic-siblings rule.
+- `references/validation.md` — the dev-server validation loop and the known cytoscape/mermaid build quirk.

.claude/skills/write-feature-docs/references/docusaurus-conventions.md

@@ -0,0 +1,96 @@
+# Docusaurus Conventions
+
+How Product Documentation pages are structured on this site, so new pages are indistinguishable from existing ones. This is a **Docusaurus** site (not Mintlify). Pages live under `docs/`; the sidebar is auto-generated from the folder tree.
+
+**Always study 2–3 sibling pages in the same folder before writing.** These conventions are the pattern; the neighbors are the ground truth.
+
+## Page frontmatter
+
+Every `.mdx` page starts with YAML frontmatter:
+
+```markdown
+---
+sidebar_position: 2
+title: "Warehouse Native Modes"
+description: "One-sentence summary used for SEO and previews."
+---
+```
+
+- `sidebar_position` orders the page within its folder. When inserting a page between existing ones, renumber siblings so the order reads right (e.g. new page at position 1 pushes get-started to 2).
+- `title` and `description` are user-facing.
+
+## The `<Image>` component
+
+Screenshots use a custom component (`src/components/Image`, wrapping IdealImage), **not** raw markdown images.
+
+```markdown
+import Image from "../../../src/components/Image";
+
+<Image maxWidth="40rem" centered img="warehouse-native/exposure-mapping-complete.png" alt="Completed exposure table mapping" />
+```
+
+- **The import path is relative and depth-sensitive.** From `docs/web-console-docs/<area>/page.mdx` it's `../../../src/components/Image`; from one level deeper (`docs/web-console-docs/<area>/<sub>/page.mdx`) it's `../../../../src/components/Image`. Count the directories up to repo root, then into `src/`. Copy the import line from a sibling at the **same depth**.
+- `img` is relative to `static/img/`. So `img="warehouse-native/foo.png"` → `static/img/warehouse-native/foo.png`.
+- `maxWidth` (e.g. `"40rem"`, `"48rem"`) keeps large screenshots readable; `centered` centers the figure. Always include meaningful `alt`.
+
+Put PNGs in `static/img/<feature>/`. Reuse existing images when they still match the UI; only add new ones.
+
+## `_category_.json`
+
+Each folder that appears as a sidebar section has a `_category_.json`:
+
+```json
+{
+  "position": 8,
+  "collapsible": true,
+  "collapsed": true,
+  "label": "Warehouse Native"
+}
+```
+
+`position` orders the section among its siblings; `label` is the sidebar heading. Add one when you create a new section folder.
+
+## Admonitions
+
+Use Docusaurus admonitions for asides — they render as colored callouts:
+
+```markdown
+:::note
+Neutral clarification.
+:::
+
+:::tip
+Best-practice advice.
+:::
+
+:::info Custom title
+Important context; the text after ::: becomes the title.
+:::
+```
+
+Match the neighbors' usage — `:::tip` for guidance, `:::note` for caveats, `:::info` for a highlighted concept.
+
+## Internal links and anchors
+
+- **Cross-page:** relative path without extension — `[Get Started](./get-started)` or `[Modes](./modes)`.
+- **Anchor on another page:** `./get-started#step-4-configure-exposures-import-hybrid-only`.
+- **Same-page anchor:** `#the-default-data-source`.
+- The anchor **slug is the kebab-cased heading text** (lowercased, spaces→hyphens, punctuation dropped, `_italics_` markers dropped). So `## Step 4: Configure exposures import _(Hybrid only)_` → `step-4-configure-exposures-import-hybrid-only`.
+- **If you rename a heading, update every link that targets its old slug.** Validation (Phase 5) catches broken anchors, but grep for the old slug proactively:
+  ```bash
+  grep -rn "old-anchor-slug" docs/
+  ```
+
+## Tables
+
+Standard GitHub-flavored markdown tables are used heavily for field/option references (field | description | accepted types). Mirror the columns the neighbors use.
+
+## Structure of a good page
+
+Overview → concept → step-by-step, with cross-links. For a multi-page feature: an `overview.mdx` (why + what), a concept/`modes` page if there's a fork to explain, a `get-started` walkthrough, and per-variant pages in a subfolder (e.g. `connect/<warehouse>.mdx`). Keep each page focused; link between them rather than repeating.
+
+## Content rules
+
+- **Mirror the product's own labels** (from the research report's UI strings) for buttons, fields, and options.
+- **Don't leak internal implementation** the product doesn't intend to expose (this session we removed a Parquet export/import mechanism at the product owner's request — describe what the user configures and sees instead).
+- **Say "can", not "must",** when the product allows a choice (a goal *can* live in an external warehouse; it isn't required).

.claude/skills/write-feature-docs/references/validation.md

@@ -0,0 +1,82 @@
+# Validation
+
+How to confirm new/edited doc pages are correct before handing off. Validate via the **dev server**, not the production build (see the cytoscape note below).
+
+All commands run from the repo root (`~/git_tree/docs`, or a worktree of it).
+
+## Prerequisite: node_modules
+
+A fresh worktree has no `node_modules` (worktrees don't share them). Either `yarn install`, or for a quick check symlink the main checkout's:
+
+```bash
+ln -s /Users/<you>/git_tree/docs/node_modules node_modules   # from inside the worktree
+```
+
+Remove the symlink before committing (it's not tracked, but keep the tree clean).
+
+## Start the dev server
+
+```bash
+yarn start --port 3111 --no-open > /tmp/docs-dev.log 2>&1 &
+# wait for readiness:
+for i in $(seq 1 15); do
+  curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3111/docs/web-console-docs/<area>/<page> | grep -q 200 && { echo READY; break; }
+  sleep 5
+done
+```
+
+## What to check
+
+### 1. Pages compile (no MDX errors)
+If an `.mdx` page has a syntax error, the dev server logs it and the page won't load. A clean start + HTTP 200 on your pages = compiled.
+
+### 2. No broken internal links / anchors
+Docusaurus logs broken links. Filter the dev log for real problems (excluding the known cytoscape/mermaid noise):
+
+```bash
+grep -iE "broken|anchor" /tmp/docs-dev.log | grep -iv "cytoscape\|mermaid"
+```
+
+To positively confirm an anchor exists (client-rendered, so use a JS-capable check rather than curl+grep):
+
+```js
+// via a standalone Playwright script (see the abs skill's app-bring-up.md for resolving playwright)
+await page.goto('http://localhost:3111/docs/web-console-docs/<area>/<page>', { waitUntil: 'networkidle' });
+const ok = await page.evaluate(() => !!document.getElementById('<expected-anchor-slug>'));
+```
+
+### 3. Images load
+Confirm every `<Image>` resolves (no missing file / `naturalWidth === 0`):
+
+```js
+const broken = await page.evaluate(() =>
+  Array.from(document.querySelectorAll('article img')).filter(i => i.complete && i.naturalWidth === 0).length);
+console.log('broken images:', broken);   // expect 0
+```
+
+A broken image usually means a wrong `img=` path (check it's relative to `static/img/`) or the PNG wasn't written.
+
+## The known cytoscape / mermaid build error — ignore it
+
+`yarn build` (the production build) currently fails with:
+
+```
+Module not found: Error: Package path ./dist/cytoscape.umd.js is not exported from package .../node_modules/cytoscape
+```
+
+This is **pre-existing and unrelated** to feature pages — it comes from a mermaid diagram used elsewhere in the docs (e.g. the GCP-BigQuery integration page) and a `cytoscape` package-exports incompatibility in the shared `node_modules`. It is **not** caused by your changes and does **not** affect the warehouse-native / feature pages.
+
+- **Don't try to fix it** as part of documenting a feature — it's out of scope and an environment/dependency issue.
+- **Validate with the dev server**, which compiles and serves pages despite it. (CI's own "Yarn Build" check has passed for merged docs PRs, confirming it's a local-environment quirk.)
+- The dev server shows the same error as a red overlay in dev mode — recognize it and move on; your pages still render underneath.
+
+## Clean up
+
+```bash
+# stop the dev server
+pkill -f "docusaurus start --port 3111"
+# remove the node_modules symlink if you made one
+rm -f node_modules
+```
+
+Then confirm `git status` shows only the intended files (pages, `static/img/<feature>/*.png`, any `_category_.json`) — no stray scratch files. Keep research reports and screenshot scratch under gitignored paths.