document360-engine 0.2.9 → 0.2.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "document360-engine",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "description": "Headless documentation agent engine for document360-writer / -desktop. Emits a typed event stream; no UI.",
   "type": "module",
   "main": "./dist/index.js",

package/skills/CLAUDE.md

@@ -112,6 +112,7 @@ The "Capabilities" section below lists specialized skills. Pick the right one ba
 - Any "convert/wrap this into a callout/tabs/FAQ/accordion" request, or authoring with rich components → apply `d360-markdown` (always-on syntax reference).
 - "/publish ..." → `publish-to-d360`.
 - "/screenshot ..." or any time you generate a screenshot placeholder → also call `emit-screenshot-spec`.
+- "/capture-setup" / "what data do I need for screenshots" / after authoring screenshot specs in bulk → `capture-setup-checklist`.
 - Pulling extra context from other MCP sources during write-article → `gather-context-from-mcp`.
 
 If the user's intent is ambiguous, ask before invoking a skill that writes files or publishes.

package/skills/capture-setup-checklist/SKILL.md

@@ -0,0 +1,43 @@
+# Skill: capture-setup-checklist
+
+**Activate when** the user asks how to prepare data for screenshots ("what data do I need for captures", "capture setup", `/capture-setup`), OR right after you've emitted screenshot specs in bulk.
+
+**Goal:** one reviewable "stage this data" checklist, so the user dresses the demo context ONCE before running `d360-capture` — the way a technical writer prepares a demo account before a screenshot session. Screenshots can't show data that isn't there; this tells the user exactly what to create.
+
+## How
+
+1. **Collect.** Find every `<!-- SCREENSHOT ... -->` block across `<docsDir>/**/*.md`. From each, read the `id`, the title, and the `prerequisites:` lines.
+2. **Anchor to the scope.** Read the capture `scope` keys from `.d360-capture.json` (e.g. `project`, or `project`+`workspace`, or `org` — whatever THIS product scopes by; do not assume "project"). If no scope is set yet, recommend the keys you saw the product use and tell the user to set them.
+3. **Synthesize — don't dump.** A raw per-spec list is noise. Instead:
+   - **Group by context** (e.g. "In the demo project «`scope.project`»:").
+   - **Dedupe** overlapping needs — if eight shots each need "≥1 suite", say it once.
+   - **Order foundational → specific**: create the context first, then the records, then per-shot specifics.
+   - **Separate the un-stageable**: shots needing a transient state (a toast, a mid-import modal) go under "Set up by hand at capture time", not the standing-data list.
+4. **Write it** to `<captureDir>/CAPTURE-SETUP.md` (versioned + reviewable). Re-running refreshes it.
+5. **Close** by telling the user the path, to set `scope` in `.d360-capture.json` to point at the prepared context, then `d360-capture auth` (once) and `d360-capture capture`.
+
+## Quality bar
+
+- **Concrete:** real record names and counts ("create a suite named *Smoke*", "import one API spec"), not "have some data".
+- **Generic:** use the product's actual scope keys; never hardcode FlowForge's "project".
+- **Honest:** if a spec's `prerequisites:` are missing or vague, list that spec under "Needs a clearer prerequisite" rather than inventing data. Don't pretend a checklist item exists when the source doesn't say so.
+
+## Shape of the output (illustrative)
+
+```markdown
+# Capture data setup
+
+Prepare this once, then run `d360-capture capture`.
+
+## In the demo project "Docs Demo"
+- [ ] At least 1 **suite** (e.g. "Smoke") — needed by: suites-tab-list, suite-run-dashboard, …
+- [ ] At least 3 **schedules** — needed by: schedules-list-populated, schedule-context-menu
+- [ ] 1 **capture** with a click-gallery + a video — needed by: captures-detail-*
+- [ ] 1 imported **API spec** (with a version folder) — needed by: spec-import-*
+
+## Set up by hand at capture time (transient states)
+- flow-generation-timeout-banner — trigger a generation timeout, then capture.
+
+## Needs a clearer prerequisite
+- <spec-id> — its SCREENSHOT block doesn't say what data it needs; refine it.
+```

package/skills/emit-screenshot-spec/SKILL.md

@@ -2,43 +2,69 @@
 
 **Activate when** you've just emitted a `<!-- SCREENSHOT ... -->` placeholder block in an article, OR the user runs `/screenshot <id>`.
 
-**Goal:** generate a Playwright `.spec.ts` file in the configured `captureDir` that the `document360-capture` (alias `d360-capture`) CLI can execute end-to-end against the user's running product.
+**Goal:** generate a Playwright `.spec.ts` in the configured `captureDir` that the `document360-capture` (alias `d360-capture`) CLI runs against the user's live product.
 
-## Where the spec lands
+## Read the product FIRST — never guess (non-negotiable)
 
-`<captureDir>/<placeholder.id>.spec.ts` — read `captureDir` from `.d360-writer.json` (default: `user-docs/_capture`).
+Every recurring capture failure has traced back to guessing. Before you write a single line, READ the source and ground each of these in it:
+
+1. **Routes** — find the router (e.g. the app's route table) and use the EXACT path. Do not assume `/spec` vs `/spec-files`, `/tests` vs `/test`. If you can't find it, say so and ask.
+2. **Selectors** — open the component and use a stable `data-testid` you actually see. Never invent one, and never fall back to `li`, `ul.divide-y li`, or other structural CSS.
+3. **Context selection** — find how the app enters the context the shot needs (selecting a project / workspace / org / etc.). You'll drive it with the capture *scope* (below), not by clicking "the first one".
+4. **Data prerequisites** — determine what state the screen needs to look real (≥1 of something, a specific record, an open modal). This becomes both the placeholder's `prerequisites:` and a runtime guard (below).
+
+If a fact isn't in the source, do not fabricate it.
+
+## Capture scope — enter a KNOWN context, deterministically
+
+The capture profile declares a generic `scope` (key→value) for the prepared demo context — e.g. `{project: "Docs Demo"}`, or `{project, workspace, language}`, or `{org}` — whatever THIS product scopes by (you learned that by reading the source; it is not always "project"). The CLI injects it; read it with the `captureScope()` / `scopeValue(key)` helpers.
+
+- Select the context using the scope value (e.g. the project whose name === `scope.project`), via the selection mechanism you read from the source — **not** `.first()`.
+- Fall back to `.first()` ONLY when the relevant scope key is unset, so single-context setups still work.
+
+## Data prerequisites — skip clearly, don't time out
+
+If the data the shot needs is absent, a 15s selector timeout is a terrible error. Instead, guard it and skip with a reason that tells the user exactly what to stage:
+
+```typescript
+if ((await rows.count()) === 0) {
+  test.skip(true, 'Prerequisite not met: needs ≥1 suite in project "' + (scopeValue('project') ?? '<scope>') + '". Stage it, then re-run.');
+}
+```
+
+The skip reason MUST match what you wrote in the placeholder's `prerequisites:` line — they're the same fact, surfaced two ways.
 
 ## Spec template
 
 ```typescript
 import { test } from '@playwright/test';
-import { waitPastLogin, dumpAnnotations, type Placeholder } from 'document360-capture/helpers';
+import { waitPastLogin, dumpAnnotations, captureScope, scopeValue, type Placeholder } from 'document360-capture/helpers';
 
 const PLACEHOLDER: Placeholder = {
   id: '<placeholder.id>',
   saveTo: '<placeholder.save-to>',
-  highlight: [
-    // one stable selector per placeholder.highlight entry
-  ],
-  annotations: [
-    // { target: '<stable selector>', label: '1', text: '<short text>' }
-  ],
-  redact: [
-    // one stable selector per placeholder.redact entry
-  ],
+  highlight: [ /* one stable selector per placeholder.highlight entry */ ],
+  annotations: [ /* { target: '<stable selector>', label: '1', text: '<short text>' } */ ],
+  redact: [ /* one stable selector per placeholder.redact entry */ ],
 };
 
 test('<placeholder.id>', async ({ page }) => {
   await page.goto(process.env.CAPTURE_START_URL!);
   await waitPastLogin(page, new RegExp(process.env.CAPTURE_AUTH_BOUNDARY!));
 
-  // Translated from placeholder.steps — one Playwright action per step.
-  // Use STABLE selectors only.
-  // ...
+  // 1. Enter the prepared context using the scope (selection mechanism read from source).
+  const scope = captureScope();
+  // …select the context by scope.<key>; fall back to first only when that key is unset…
+
+  // 2. Navigate using the EXACT route read from the router (never a guessed path).
+  // …
+
+  // 3. Prerequisite guard — skip with a clear reason instead of timing out.
+  // if ((await <rows>.count()) === 0) test.skip(true, 'Prerequisite not met: …');
 
+  // 4. Reach the target state, settle, capture.
   await page.waitForSelector('<target state selector>', { state: 'visible' });
   await page.waitForTimeout(500);
-
   await page.locator('<capture target selector>').screenshot({ path: PLACEHOLDER.saveTo });
   await dumpAnnotations(page, PLACEHOLDER);
 });
@@ -46,31 +72,27 @@ test('<placeholder.id>', async ({ page }) => {
 
 ## Selector quality rule (non-negotiable)
 
-Use stable selectors in this priority order:
-
+Stable selectors in priority order:
 1. `[data-testid="..."]` — best.
 2. `[aria-label="..."]` — good.
-3. `<role>:has-text("...")` / `role=button[name="..."]` — acceptable when unique.
-4. Visible text (`text=...`, `:has-text(...)`) — acceptable for top-level nav and unique buttons.
+3. `role=button[name="..."]` / `<role>:has-text("...")` — acceptable when unique.
+4. Visible text (`text=...`) — acceptable for top-level nav and unique buttons.
 
-**Never** use CSS classes, `nth-child`, deep DOM paths, or auto-generated IDs (`#mui-12345`).
+**Never** CSS classes, `nth-child`, structural `li`/`div.x`, deep DOM paths, or auto-generated IDs (`#mui-12345`).
 
-## TODO escape hatch (when stable selectors don't exist)
-
-If a required interaction has no stable selector, do NOT write a fragile one. Instead:
+## TODO escape hatch (when a stable selector truly doesn't exist)
 
+Don't write a fragile selector. Instead:
 1. Use `test.skip(...)` instead of `test(...)`.
-2. Add a top-of-file comment: `// TODO: add data-testid="<suggested-name>" to <ComponentName> at <src/.../File.tsx>. Capture spec disabled until then.`
-3. Tell the user which file + component to fix, plus the `data-testid` value you'd recommend.
-
-The manual intern path in the placeholder still works — only the automated capture is blocked.
+2. Top-of-file comment: `// TODO: add data-testid="<name>" to <Component> at <src/.../File.tsx>. Capture disabled until then.`
+3. Tell the user which file + component to fix and the `data-testid` to add.
 
 ## Capture region (the placeholder's `capture` field)
 
 | `capture` value | Spec uses |
 |---|---|
 | `full-page` | `await page.screenshot({ path, fullPage: true })` |
-| `main-panel` | a stable container selector (read it from the project's main layout source) |
+| `main-panel` | a stable container selector (read it from the layout source) |
 | `modal-only` | `page.locator('[role="dialog"]').first().screenshot(...)` |
 | `panel-left` / `panel-right` | the project's named-panel selector |
 | `sidebar` | the project's sidebar selector |
@@ -78,8 +100,10 @@ The manual intern path in the placeholder still works — only the automated cap
 ## After writing the spec
 
 - Report the spec's path.
-- If you used the TODO escape hatch, surface the blocking selectors so the dev can fix them in one pass.
-- Remind the user how to capture it (screenshots are a separate tool — `document360-capture` is not bundled with the writer):
+- List anything that needs the user: the `data-testid`s a dev must add (TODO hatch), and the **data prerequisites** to stage (project/workspace + the records each shot needs).
+- After authoring several specs, run `capture-setup-checklist` to refresh the consolidated `CAPTURE-SETUP.md` staging guide.
+- Remind how to capture (screenshots are a separate tool — not bundled with the writer):
   1. First time only: `npm i -g document360-capture`
-  2. Once per machine: `d360-capture auth --profile <name>`
-  3. `d360-capture capture <id>` to take the screenshot.
+  2. Set the capture `scope` for the prepared demo context in `.d360-capture.json`.
+  3. Once per machine: `d360-capture auth --profile <name>`
+  4. `d360-capture capture <id>`.