@caddis/cli 0.4.45 → 0.4.47

package/bundles/antigravity-plugin/skills/flow-studio/references/implement-in-app.md

@@ -0,0 +1,213 @@
+# Implement a flow in an application
+
+Use an approved flow model as input. Validate it against `model.schema.json` before connecting live data. The demo page shows the intended interaction. Keep this guide with the skill when copying files into an application.
+
+In the commands, `<skill>` is the path to the flow-studio skill folder in your checkout. Your app has no copy of the skill's scripts, so commands that run them always name the `<skill>` path.
+
+## 1. Pick the route
+
+| Requirement | Route | Implementation |
+|---|---|---|
+| The app may use the flow engine's own styling and controls | Fast wrapper / library embed | `templates/flow-studio.lib.mjs` provides the full self-contained engine. |
+| The app must use its own design tokens, buttons, and drawer | Native components & hooks | Pure modules (`src/`) supply geometry, layout, and trace logic to app components. |
+
+The files are copyable source, not a published npm package. Both routes need a caller that supplies a valid `Model`; neither fetches app data for you.
+
+---
+
+## 2. Lock the model and data contract
+
+1. Save the approved model as JSON. Run `node --experimental-strip-types <skill>/scripts/validate.mjs <model.json>`. Fix any reported errors.
+2. Define a typed state for the app's data source: `loading`, `ready` with a `Model`, `empty`, or `error` with a user-facing message and retry action.
+3. Map node IDs from immutable business keys (e.g. `order-service-uuid`). Map link IDs from immutable relation keys. Never use array indices or volatile titles.
+4. Keep absent values absent. Do not turn a missing measurement into `0`. Use state words and timestamps (`asOf`) to distinguish measured data from declarations.
+5. On refresh error, keep the last valid model visible and show a notification banner. On a valid refresh, pass the new model with stable IDs so `engine.update(model)` preserves pan, zoom, and active selection.
+6. Render all model strings as plain text. Never use raw `innerHTML` for titles, subtitles, or labels.
+
+---
+
+## 3. Test-first workflow in the target app
+
+1. **Verify skill tests:** Run the test suite:
+   ```bash
+   node --experimental-strip-types --no-warnings --test "src/*.test.ts" "scripts/lib/*.test.mjs"
+   ```
+2. **Author mapping test:** Write an app test verifying the data-to-model mapper produces stable IDs, preserves absent fields, and handles loading/error states. See the test fail before implementing the mapper.
+3. **Author component test:** Write a test verifying component mount, node selection callback, and update behavior.
+4. **Implement iteratively:** Implement mapping and component wiring, re-running the focused test after each step until green.
+
+---
+
+## 4. Integration guides by framework
+
+### A. React
+
+Copy `templates/flow-studio.lib.mjs`, `templates/flow-studio.lib.d.mts`, `templates/flow-studio.css`, `react/`, and `src/` into the app, keeping the relative layout.
+
+```tsx
+import React, { useEffect, useRef } from "react";
+import { FlowStudioView, FlowLoading, FlowError } from "./react/index";
+import type { Model } from "./src/model";
+import "./templates/flow-studio.css";
+
+export function FlowContainer({ model, status, error, onRetry }: { model?: Model; status: string; error?: string; onRetry: () => void }) {
+  const [selectedId, setSelectedId] = React.useState<string | null>(null);
+
+  if (status === "loading") return <FlowLoading />;
+  if (status === "error") return <FlowError message={error!} onRetry={onRetry} />;
+  if (!model || model.nodes.length === 0) return <div>No data available</div>;
+
+  return (
+    <div style={{ height: "80vh", width: "100%" }}>
+      <FlowStudioView
+        model={model}
+        onSelect={(id) => setSelectedId(id)}
+      />
+    </div>
+  );
+}
+```
+
+### B. Vue (Vue 3 / Vite)
+
+Copy `templates/flow-studio.lib.mjs`, `templates/flow-studio.lib.d.mts`, and `templates/flow-studio.css` to your application assets directory.
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted, onBeforeUnmount, watch } from "vue";
+import { mount } from "../assets/flow-studio.lib.mjs";
+import "../assets/flow-studio.css";
+
+const props = defineProps<{ model: any }>();
+const emit = defineEmits(["select"]);
+const containerRef = ref<HTMLDivElement | null>(null);
+let engineInstance: any = null;
+
+onMounted(() => {
+  if (containerRef.value && props.model) {
+    engineInstance = mount(containerRef.value, props.model, {
+      onSelect: (id: string | null) => emit("select", id)
+    });
+  }
+});
+
+watch(() => props.model, (newModel) => {
+  if (engineInstance && newModel) {
+    engineInstance.update(newModel);
+  }
+});
+
+onBeforeUnmount(() => {
+  if (engineInstance) {
+    engineInstance.destroy();
+    engineInstance = null;
+  }
+});
+</script>
+
+<template>
+  <div ref="containerRef" class="flow-container"></div>
+</template>
+
+<style scoped>
+.flow-container { width: 100%; height: 80vh; position: relative; }
+</style>
+```
+
+### C. Svelte (Svelte 4 / 5)
+
+Copy the same library files as for Vue. The import is aliased because Svelte 5 exports its own `mount`.
+
+```svelte
+<script lang="ts">
+  import { onMount, onDestroy } from "svelte";
+  import { mount as mountFlow } from "./flow-studio.lib.mjs";
+  import "./flow-studio.css";
+
+  export let model: any;
+  export let onSelect: (id: string | null) => void = () => {};
+
+  let container: HTMLDivElement;
+  let engine: any;
+
+  onMount(() => {
+    engine = mountFlow(container, model, { onSelect });
+  });
+
+  $: if (engine && model) {
+    engine.update(model);
+  }
+
+  onDestroy(() => {
+    if (engine) engine.destroy();
+  });
+</script>
+
+<div bind:this={container} class="flow-container"></div>
+
+<style>
+  .flow-container { width: 100%; height: 80vh; position: relative; }
+</style>
+```
+
+### D. Vanilla HTML & JavaScript
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <link rel="stylesheet" href="./templates/flow-studio.css">
+  <style>
+    #flowHost { width: 100vw; height: 100vh; }
+  </style>
+</head>
+<body>
+  <div id="flowHost"></div>
+  <script type="module">
+    import { mount } from "./templates/flow-studio.lib.mjs";
+
+    const response = await fetch("/api/lineage-model");
+    const model = await response.json();
+
+    const engine = mount(document.getElementById("flowHost"), model, {
+      onSelect: (selectedId) => {
+        console.log("Selected node:", selectedId);
+      }
+    });
+
+    // Expose for external live event updates
+    window.updateFlow = (newModel) => engine.update(newModel);
+  </script>
+</body>
+</html>
+```
+
+---
+
+## 5. State synchronization and host events
+
+`mount()` returns the engine API, and every mount also publishes the same API object on `window.FlowStudio`. Hold the value that `mount()` returns in a variable named `engine` in the examples below:
+
+1. **Selection listening:** pass `onSelect(nodeId: string | null)` as a mount option to receive updates when a user selects a card or chip, or clears the selection.
+2. **Programmatic selection:** call `engine.select(nodeId)` (or `window.FlowStudio.select(nodeId)`) to focus and inspect a node from outside the canvas, for example from an app table row.
+3. **Reading active state:** call `engine.selected()`, `engine.view()`, or `engine.mode()` to read the current canvas state.
+4. **Live topology updates:** call `engine.update(newModel)` to refresh node metrics, statuses, or structure without losing the user's pan and zoom. A model that fails validation is rejected, the last good graph stays, and the engine shows a banner.
+
+In the React wrapper route the engine instance is private to `FlowStudioView`: use the `onSelect` prop for selection changes and drive new data through the `model` prop (the wrapper calls `update` itself). Use `window.FlowStudio` for a direct call only while exactly one view is mounted.
+
+---
+
+## 6. Verifying the app in browser check harness
+
+Run the skill's check harness against your local dev server:
+
+```bash
+node <skill>/scripts/check.mjs http://127.0.0.1:5173/flow --out shots --channel msedge --skip hostile
+```
+
+The harness is not copied into your app, so the command always names the `<skill>` path. Run it from a folder whose `node_modules` resolves `playwright`.
+
+- When tests fail, inspect the screenshot in `shots/` and read the error detail.
+- Ensure the app container provides at least 540px height for desktop viewports.
+- `--skip` takes a comma-separated list of groups (`notes`, `playback`, `update`, `hostile`). Skip a group only when the app intentionally omits that feature. Record every skipped group in your verification notes. Never treat a skipped check as a pass.

package/bundles/antigravity-plugin/skills/flow-studio/references/model-schema.md

@@ -0,0 +1,254 @@
+# Model schema reference
+
+This reference documents the structure and properties of the flow-studio model specified in `model.schema.json`. Every property is listed with its type, requirement status, default value, and semantic description.
+
+## 1. Top-level model object
+
+A valid model requires the core structural properties.
+
+| Property | Type | Required? | Default | Description |
+|---|---|---|---|---|
+| `version` | `integer` | Required | `1` | Schema version (must equal 1). |
+| `meta` | `object` | Required | - | Metadata describing the scenario, authorship, and timestamp. |
+| `layout` | `string` | Required | - | Layout mode: `"columns-lanes"`, `"free"`, or `"auto"`. |
+| `columns` | `array` | Required | - | Array of vertical column definitions. |
+| `lanes` | `array` | Required | - | Array of horizontal swimlane definitions. |
+| `states` | `object` | Required | - | Dictionary of visual state definitions keyed by state ID. |
+| `nodes` | `array` | Required | - | Array of node and card elements. |
+| `links` | `array` | Required | - | Array of directional connections between nodes. |
+| `views` | `array` | Optional | - | Optional filtered or perspective views. |
+| `inspector` | `object` | Optional | - | Inspector relationships and what-if simulation actions. |
+| `scenarios` | `array` | Optional | - | Playback scenarios for animated token traces. |
+| `notes` | `array` | Optional | - | Implementation and design callout notes. |
+
+---
+
+## 2. `meta` object
+
+Contains descriptive and provenance metadata for the diagram.
+
+| Property | Type | Required? | Default | Description |
+|---|---|---|---|---|
+| `title` | `string` | Required | - | Header title of the flow. |
+| `help` | `string` | Required | - | Subtitle explaining the scenario purpose and context. |
+| `asOf` | `string` | Required | - | Date or timestamp representing data freshness (e.g. `"2026-10-06"`). |
+| `source` | `string` | Required | - | Provenance, API, database, or owning team. |
+| `labels` | `object` | Optional | - | Key-value dictionary of auxiliary string labels. |
+
+---
+
+## 3. `columns` array items
+
+Columns provide vertical partitioning for time, stages, or architecture tiers.
+
+| Property | Type | Required? | Default | Description |
+|---|---|---|---|---|
+| `id` | `string` | Required | - | Unique column identifier. |
+| `title` | `string` | Required | - | Display title shown in the column header. |
+| `short` | `string` | Optional | - | Compact abbreviated title for tight viewports. |
+| `width` | `number` | Required | - | Column width in pixels (minimum 60). |
+| `phase` | `string` | Optional | - | Super-category phase grouping shown in top banner. |
+
+---
+
+## 4. `lanes` array items
+
+Swimlanes partition the canvas horizontally by owning team, system, or tier.
+
+| Property | Type | Required? | Default | Description |
+|---|---|---|---|---|
+| `id` | `string` | Required | - | Unique lane identifier. |
+| `title` | `string` | Required | - | Display title of the swimlane. |
+| `badge` | `string` | Optional | - | Small uppercase pill badge text (e.g. `"PROD"`). |
+| `badgeTone` | `string` | Optional | `"muted"` | Badge color tone: `"ok"`, `"warn"`, or `"muted"`. |
+| `note` | `string` | Optional | - | Explanatory note rendered beside the lane title. |
+| `gap` | `boolean` | Optional | `false` | When true, renders the lane with an amber dashed border indicating unverified systems. |
+
+---
+
+## 5. `states` dictionary items
+
+States define semantic styling, borders, and animations for nodes and edges.
+
+| Property | Type | Required? | Default | Description |
+|---|---|---|---|---|
+| `word` | `string` | Required | - | Human-readable state badge text (e.g. `"HEALTHY"`, `"FAILED"`). |
+| `tone` | `string` | Required | - | Semantic color: `"ok"`, `"warn"`, `"crit"`, `"info"`, `"muted"`, or `"accent"`. |
+| `border` | `string` | Required | - | Card border style: `"solid"`, `"dashed"`, or `"dotted"`. |
+| `edge` | `string` | Required | - | Link stroke dash pattern: `"flow"`, `"dash"`, `"dash-short"`, or `"dot"`. |
+| `motion` | `string` | Required | - | State animation: `"flow"`, `"flow-slow"`, `"breathe"`, or `"none"`. |
+| `bucket` | `string` | Required | - | Health bucket category: `"good"`, `"neutral"`, or `"gap"`. |
+
+---
+
+## 6. `nodes` array items
+
+Nodes represent processing units, cards, gateways, groups, and milestones.
+
+| Property | Type | Required? | Default | Description |
+|---|---|---|---|---|
+| `id` | `string` | Required | - | Unique node identifier. |
+| `kind` | `string` | Required | - | Node kind: `"card"`, `"group"`, `"chip"`, `"gateway"`, `"start"`, `"end"`, `"event"`, `"placeholder"`, or `"note"`. |
+| `state` | `string` | Required | - | Key referencing a valid state in `states`. |
+| `title` | `string` | Required | - | Primary label or name of the node. |
+| `subtitle` | `string` | Optional | - | Secondary description line. |
+| `lane` | `string` | Required (grid/free) | - | ID of the lane containing this node. |
+| `col` | `integer` | Required (grid) | - | Zero-based column index where the node begins. |
+| `colSpan` | `integer` | Optional | `1` | Number of columns spanned (minimum 1). |
+| `row` | `number` | Required (grid) | - | Vertical slot index within the lane. |
+| `x` | `number` | Required (free) | - | Absolute horizontal coordinate in pixels. |
+| `y` | `number` | Required (free) | - | Absolute vertical coordinate in pixels. |
+| `w` | `number` | Optional | auto | Explicit node width in pixels. |
+| `h` | `number` | Optional | auto | Explicit node height in pixels. |
+| `stateIn` | `object` | Optional | - | View-specific state overrides keyed by view ID. |
+| `visibleIn` | `array` | Optional | all | Array of view IDs where this node appears. |
+| `members` | `array` | Optional | - | Array of member entity names or IDs. |
+| `weight` | `number` | Optional | - | Numerical priority or item count (minimum 0). |
+| `ref` | `string` | Optional | - | Target node ID if this node acts as a portal chip. |
+| `upgrade` | `string` | Optional | - | Recommended action or upgrade path. |
+| `allowIsolated` | `boolean` | Optional | `false` | Explicitly permits node to have zero links without failing validation. |
+| `contains` | `array` | Optional | - | Child node IDs contained in this group. |
+| `collapsed` | `boolean` | Optional | `true` | When true, group starts collapsed hiding child nodes. |
+| `sla` | `number` | Optional | - | Target service level agreement threshold in seconds. |
+| `metrics` | `object` | Optional | - | Telemetry payload (see metrics table). |
+
+---
+
+## 7. `metrics` object (under `nodes`)
+
+Provides numerical telemetry, health bars, and sparklines.
+
+| Property | Type | Required? | Default | Description |
+|---|---|---|---|---|
+| `value` | `number` | Required | - | Primary current numerical metric value. |
+| `max` | `number` or `null` | Optional | `null` | Upper bound for the badge fill bar (null for unbounded). |
+| `unit` | `string` | Optional | - | Display unit (e.g. `"ms"`, `"rps"`, `"MB"`). |
+| `label` | `string` | Optional | - | Descriptive metric label. |
+| `series` | `array` | Optional | - | Historical series array (up to 60 numbers) rendered as sparkline. |
+
+---
+
+## 8. `links` array items
+
+Links represent directional data transit, dependencies, or workflow transitions.
+
+| Property | Type | Required? | Default | Description |
+|---|---|---|---|---|
+| `id` | `string` | Required | - | Unique link identifier. |
+| `from` | `string` | Required | - | Source node ID. |
+| `to` | `string` | Required | - | Target node ID. |
+| `state` | `string` | Required | - | Key referencing a valid state in `states`. |
+| `stateIn` | `object` | Optional | - | View-specific state overrides keyed by view ID. |
+| `visibleIn` | `array` | Optional | all | Array of view IDs where this link appears. |
+| `label` | `string` | Optional | - | Text label displayed on the link path. |
+| `kind` | `string` | Optional | `"forward"` | Link direction: `"forward"` or `"loop-back"`. |
+
+---
+
+## 9. `views` array items
+
+Permit switching between different operational layers or time slices.
+
+| Property | Type | Required? | Default | Description |
+|---|---|---|---|---|
+| `id` | `string` | Required | - | Unique view identifier. |
+| `label` | `string` | Required | - | Button label shown in the mode switch toolbar. |
+| `default` | `boolean` | Optional | `false` | Marks the initial default active view. |
+
+---
+
+## 10. `inspector` object
+
+Configures the drill-down side panel and simulation capabilities.
+
+| Property | Type | Required? | Default | Description |
+|---|---|---|---|---|
+| `relations` | `array` | Optional | - | Array of up to 3 relation queries (see below). |
+| `actions` | `array` | Optional | - | Array of what-if simulation buttons. |
+
+### `relations` array items
+- `id` (`string`, required): Unique relation query identifier.
+- `label` (`string`, required): Button text displayed in the inspector header.
+- `dir` (`string`, required): Traversal direction: `"up"` (upstream) or `"down"` (downstream).
+- `filter` (`object`, optional): Criteria to filter matched nodes:
+  - `col` (`integer`, optional): Restrict matches to a specific column index.
+  - `kind` (`string`, optional): Restrict matches to a specific node kind.
+
+### `actions` array items
+- `id` (`string`, required): Unique action identifier.
+- `label` (`string`, required): Button label (e.g. `"Simulate: DB Failure"`).
+- `dir` (`string`, required): Must be `"down"`.
+- `staleText` (`string`, required): Description of the simulated failure consequence.
+
+---
+
+## 11. `scenarios` array items
+
+Configures interactive playback traces through the diagram.
+
+| Property | Type | Required? | Default | Description |
+|---|---|---|---|---|
+| `id` | `string` | Required | - | Unique scenario identifier. |
+| `label` | `string` | Required | - | Scenario name shown in the playbar dropdown. |
+| `steps` | `array` | Required | - | Ordered sequence of animation steps. |
+
+### `steps` array items
+- `link` (`string`, required): ID of the link traversed during this step.
+- `at` (`number`, optional): Relative elapsed offset from scenario start in seconds.
+- `dur` (`number`, optional): Token travel duration in milliseconds (default: 900).
+- `caption` (`string`, optional): Narrative text displayed in the playbar during this step.
+
+---
+
+## 12. `notes` array items
+
+Callouts anchored to HTML elements or nodes.
+
+| Property | Type | Required? | Default | Description |
+|---|---|---|---|---|
+| `anchor` | `string` | Required | - | CSS selector resolved with `document.querySelector` at runtime. Target a shell element by id (`#viewport`) or a node card by its generated element id (`#n_` + node id). A bare node id is not a selector. A selector that matches nothing shows no marker. |
+| `title` | `string` | Required | - | Short title of the implementation note. |
+| `text` | `string` | Required | - | Guidance text for building this section. |
+
+---
+
+## 13. Minimal valid model example
+
+A complete valid model under 20 lines:
+
+```json
+{
+  "version": 1,
+  "meta": { "title": "Minimal Flow", "help": "Minimal valid model", "asOf": "2026-10-06", "source": "Core API" },
+  "layout": "auto",
+  "columns": [{ "id": "c1", "title": "Step 1", "width": 160 }, { "id": "c2", "title": "Step 2", "width": 160 }],
+  "lanes": [{ "id": "main", "title": "Primary Lane" }],
+  "states": {
+    "ok": { "word": "OK", "tone": "ok", "border": "solid", "edge": "flow", "motion": "flow", "bucket": "good" }
+  },
+  "nodes": [
+    { "id": "n1", "kind": "card", "lane": "main", "state": "ok", "title": "Input Node" },
+    { "id": "n2", "kind": "card", "lane": "main", "state": "ok", "title": "Output Node" }
+  ],
+  "links": [{ "id": "l1", "from": "n1", "to": "n2", "state": "ok" }]
+}
+```
+
+---
+
+## 14. Common validation errors and fixes
+
+### Error 1: Missing required column/lane position in grid layout
+- **Schema error message:** `must have required property 'col'`, `must have required property 'row'`
+- **Cause:** When `layout` is `"columns-lanes"`, all nodes must specify `lane`, `col`, and `row`.
+- **Fix:** Add `"col": 0, "row": 0` to each node, or change `layout` to `"auto"`.
+
+### Error 2: Missing state reference
+- **Validator error message:** `node 'n1' references unknown state 'active'`
+- **Cause:** A node or link sets `state: "active"`, but `"active"` is not defined in the top-level `states` dictionary.
+- **Fix:** Define `"active"` under `states` with valid `word`, `tone`, `border`, `edge`, `motion`, and `bucket`.
+
+### Error 3: Backward link without loop-back marker
+- **Validator warning:** `link 'l2' goes right-to-left from column 2 to column 0; mark as loop-back`
+- **Cause:** A link connects a later column back to an earlier column without declaring `kind: "loop-back"`.
+- **Fix:** Add `"kind": "loop-back"` to the link definition.

package/bundles/antigravity-plugin/skills/flow-studio/references/notes-and-spec.md

@@ -0,0 +1,74 @@
+# Implementation notes and model specification
+
+This document explains how implementation notes and the model reference specification work in flow-studio.
+
+## 1. How implementation notes work
+
+Implementation notes provide inline architectural, design, and engineering guidance for someone building the production page in an app.
+- Notes are defined as an array of objects: `{ "anchor": "<css-selector>", "title": "...", "text": "..." }`.
+- In `scripts/build.mjs`, all active notes are collected, assigned sequential numeric IDs (`1..n`), and embedded into the HTML via `/*__NOTES__*/[]`.
+- In the browser, `src/notes.ts` renders a slide-out drawer on the left (`#drawer`) and creates circular purple numbered markers (`.marker`) positioned over the anchored target elements.
+- Notes mode toggles via the "Implementation notes (N)" header button (`#notesBtn`) or by pressing the `N` key.
+
+---
+
+## 2. Shell anchors and valid IDs
+
+A note can anchor to any node card (for example `#n_crm-db`: the engine gives each node element the id `n_` followed by the node id) or to any of the 13 canonical shell elements defined in `templates/shell-body.html`:
+
+| Anchor ID | Shell element | Description |
+|---|---|---|
+| `#title` | Main title | Scenario headline and timestamp metadata |
+| `#layerstrip` | Completeness strip | Column completeness health indicators |
+| `#kpis` | Summary tiles | Summary metrics and gap count indicators |
+| `#modeSwitch` | View switch | Perspective and layer selector buttons |
+| `#q` | Search input | Text search and N-hop filter controls |
+| `#viewport` | Canvas viewport | Pan, zoom, and interactive graph container |
+| `#tools` | Toolbar | Zoom in/out, fit, and pan hand tool buttons |
+| `#inspector` | Side inspector | Slide-in panel for relations, telemetry, and actions |
+| `#legend` | Legend | State color keyline and evidence definitions |
+| `#ledger` | Change ledger | Historical changes or audit log entries |
+| `#tbl` | Table view | Accessible tabular rendering of all graph nodes |
+| `#playbar` | Playback bar | Scenario controls, step scrubber, and branch options |
+| `#notesBtn` | Notes toggle button | Header button to toggle the implementation notes drawer |
+
+---
+
+## 3. The demo pack mechanism
+
+The `--demo-pack` option provides comprehensive out-of-the-box guidance:
+- When running `scripts/build.mjs` with `--demo-pack`:
+  1. Default shell notes are loaded from `scripts/default-notes.json`.
+  2. Conditional shell notes are filtered based on the model:
+     - `#playbar` note is dropped if the model has no scenarios (`!model.scenarios?.length`).
+     - `#modeSwitch` note is dropped if the model has fewer than two views (`(model.views?.length ?? 0) < 2`).
+     - A default note whose anchor starts with `#` is dropped when no element with that id exists in the generated shell. Class and attribute selectors are not checked at build time.
+  3. Per-model notes from `model.notes` are appended.
+  4. Additional external notes from `--notes <file.json>` are appended.
+  5. The combined list is re-indexed from 1 to `N`.
+
+  Model and extra notes are never filtered at build time. At runtime, a note whose selector matches nothing simply gets no marker (see section 4).
+
+---
+
+## 4. Notes panel interaction
+
+`src/notes.ts` manages bidirectional interaction between cards and markers:
+- **Marker placement:** Markers calculate bounding client rectangles and hover beside anchored elements.
+- **Hovering a card:** Adds `.anchored` outline to the target element on the canvas and highlights the card in the drawer.
+- **Hovering a marker:** Highlights the target element and scrolls the corresponding card into view in the drawer.
+- **Clicking a marker:** Focuses and scrolls directly to the note text.
+- **Safety:** Hostile selectors in notes (e.g. malformed CSS or script strings) are safely evaluated inside a `try ... catch` block using `document.querySelector`, returning null without throwing errors.
+
+---
+
+## 5. Model reference and specification tab
+
+At the bottom of the page, the collapsible `<details class="spec" id="spec">` element renders the complete scenario model specification:
+- **Summary information:** Model title, description, provenance source, and generation date.
+- **States list:** Every state with its word, tone, border style, and edge animation.
+- **Columns & Lanes:** Ordered sequence of columns with phases, and lanes with ownership badges.
+- **Graph size:** Total node count and link count.
+- **Copy buttons:**
+  - `Copy as Markdown`: Copies a clean markdown summary formatted with tables and lists.
+  - `Copy model JSON`: Copies the formatted JSON payload directly to the clipboard for reuse in an app.