Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

refactor(prompts): tighten verify-charts, template apply, research, preview, review stages

hugohe3a39ccf07c432
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index 8bc2fa61..5f5357d4 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -1084,6 +1084,53 @@ python3 scripts/svg_position_calculator.py analyze <svg_file>
Use this after SVG generation to inspect existing SVG geometry when manual comparison needs more context.
+### Verification recipes
+
+Used by the [`verify-charts`](../../workflows/stages/verify-charts.md) stage for chart objects whose geometry reduces to repeated direct calculations (`decomposable-calc` / `partial-calc`), a closed formula (`formula-verify`), or inspection only (`manual-verify`). Every recipe produces one receipt line; a page that cannot be reduced cleanly is marked `manual-verify` with the reason, never dropped.
+
+**Stacked bar** — for N stacked series on the same categories, run `calc bar` N times. Pass each segment's height as the data value and shift `--area`'s `y_max` down by the sum of all lower segments for that category; compare each segment's `(x, y, width, height)`.
+
+```bash
+# two-series stack at "Q1" with bottom=30, top=20, plot y from 100 to 500
+python3 scripts/svg_position_calculator.py calc bar --data "Q1:30,Q2:..." --area "x_min,100,x_max,500" --bar-width 80 --value-range=0,axis_max
+python3 scripts/svg_position_calculator.py calc bar --data "Q1:20,Q2:..." --area "x_min,100,x_max,<500 - bottom_height_px>" --bar-width 80 --value-range=0,axis_max
+```
+
+**Stacked area** — run `calc line` N times on cumulative y-values (series 1 raw; series 2 = s1+s2; …); each call yields one band's top boundary, and each band's path closes to the previous band's top, not `y_max`. Negative segments or percent-stacked totals other than 100 are `manual-verify`.
+
+**Dumbbell** — the two endpoints are points, not bar ends (`calc bar --horizontal` anchors at `x_min`). Number categories `0.5, 1.5, …, N-0.5` with `--y-range=0,N` (swap axes for vertical dumbbells), set `--x-range` from ticks, run `calc line` once per endpoint series with identical `--area` / ranges; each `(SVG_X, SVG_Y)` is the endpoint circle's `(cx, cy)`, and the connector is `x1=cx_left, x2=cx_right, y1=y2=cy`.
+
+```bash
+python3 scripts/svg_position_calculator.py calc line --data "42:0.5,55:1.5,37:2.5" --area "100,100,700,460" --x-range=0,100 --y-range=0,3
+python3 scripts/svg_position_calculator.py calc line --data "68:0.5,71:1.5,49:2.5" --area "100,100,700,460" --x-range=0,100 --y-range=0,3
+```
+
+**Pareto** — `calc bar` on the descending values with the bar-axis range; precompute cumulative percentages; `calc line` on `0.5:cum1,…,N-0.5:cumN` with `--x-range=0,N`, the right-side percentage axis as `--y-range` (usually `0,100`), and the same `--area` (the `n - 0.5` offset centers each point on its bar). Compare bars, line, and markers separately.
+
+**Dual-axis line** — read each Y-axis tick range independently; run `calc line` once per series with its own `--y-range` and a shared `--x-range` / area; never apply the left scale to the right series.
+
+**Bullet** — bands overlap in one y row, so run `calc bar --horizontal` once per band with a single data point: `--data "<band>:<right_edge_value>" --area "<x_min>,<band_y>,<x_max>,<band_y+band_height>" --bar-width <band_height>` (widest band's right edge = axis max). Run once more for the actual bar with its inset area; the target marker is a `<line>` at `x = x_min + target/axis_max × area_width`.
+
+**Butterfly** — read the value range and center-line `cx`; run `calc bar --horizontal` once per side with `x_min = cx`, `x_max = cx + side_width`; right bars map directly, left bars mirror as `x = cx - width`; verify both sides share `y + height/2` per category.
+
+**Grouped bar** — with N series and group width `W`, each series bar is `W/N` wide at offset `(i - 1) × W/N`; run `calc bar` once per series with the same `--area` / `--value-range` and `--bar-width` set to the inner width; the per-category center is the group center, so `x = group_center - W/2 + (i-1) × W/N`.
+
+**Box plot** — five y-values per category on one axis. Run `calc bar` once treating the box (Q3 − Q1) as a synthetic segment with `y_max` shifted to the Q1 baseline; median and whisker y = `y_axis_top + (axis_max - value) × pixels_per_unit`.
+
+**Gantt** — pixels-per-unit from the header tick positions `(x_unit_n - x_unit_1) / (n - 1)`; run `calc line` over `start_index:row_y` and again over `end_index:row_y` — the two `SVG_X` values are `x` and `x + width`; row y is read directly. A qualitative stage/lane plan not derived from dates is not a chart and never enters verification.
+
+**Waterfall** — compute running totals (`cum[i] = cum[i-1] ± delta[i]`, reset for totals); build `top[i] = max(cum_before, cum_after)` and `bot[i] = min(...)`; run `calc bar` twice with identical parameters — the `top` run's `Y` is `y`, `height = bot.Y - top.Y`; connectors run from `(x + width, Y_i)` to `(x_next, Y_{i+1})` at the shared cumulative value; total bars use `bot = 0`.
+
+**Bubble / plotted 2×2 matrix** — `calc line` verifies `cx/cy` from x/y values and ticks. For `matrix_2x2`, the axis midpoint must match the quadrant split; Low/High-only axes need an explicit numeric mapping from the active §IX decision or an SVG comment, otherwise record `xy=manual (scale missing)`. Verify radius only when a size scale is declared (`radius = sqrt(value) * k` or min/max mapping) — `spec_lock.md` is not a size-scale authority; otherwise record `radius=manual (scale missing)` and inspect ordering by hand.
+
+**Bar-of-pie / pie-of-pie** — replace the expanded tail with one aggregate value and `calc pie` the main pie; `pie_of_pie` runs `calc pie` again on the tail at the secondary center/radius, `bar_of_pie` verifies each detail height as `tail_value / sum(tail) × detail_height` with no gaps or overlap; the aggregate slice equals the sum of expanded values and connectors touch both plot regions.
+
+**Stock** — `calc line` for open, high, low, close on the shared price axis; the wick spans `high_y..low_y`, the body `min(open_y, close_y)..max(...)`; body color follows `close >= open` and stays inside its wick.
+
+**Formula-verify** (no calc call): progress bar `fill_width = value / max × track_width`; gauge `needle_angle = start_angle + value / max × sweep_angle`, compared against `transform="rotate(α …)"` or the endpoint `(cx + L·cos α, cy + L·sin α)`; funnel `top_width = prev.bottom_width`, `bottom_width = top_width × next_value / curr_value`, inset `(top_width - bottom_width) / 2`, first top width from the outer frame; sunburst arc length `node_value / root_total × 2πr` per ring with offsets from cumulative siblings plus any declared gap, children inside the parent span, siblings summing to the parent. The receipt quotes the formula and result (`formula=0.92×700=644px`).
+
+**Manual-verify**: sankey — link widths proportional to flow, node totals in = out; heatmap — grid positions are fixed, verify each cell's color falls in the bin matching its value and extremes use the legend's high/low colors; treemap — `width × height ≈ total_area × value / sum(values)` for top-level cells, nested cells summing to the parent; word cloud — font sizes monotonic with declared weights or bins, then inspect bounds for overlap and clipping; position is layout-driven.
+
## Advanced Standalone Tools
### `flatten_tspan.py`
diff --git a/skills/ppt-master/scripts/docs/svg_editor.md b/skills/ppt-master/scripts/docs/svg_editor.md
new file mode 100644
index 00000000..f5ba4bdd
--- /dev/null
+++ b/skills/ppt-master/scripts/docs/svg_editor.md
@@ -0,0 +1,39 @@
+# `svg_editor/server.py`
+
+Browser SVG editor behind the [`live-preview`](../../workflows/stages/live-preview.md) stage and Generate Step 6's `--live` auto-startup. This page documents editor behavior, lifecycle, and remote access; the stage owns when to launch and how to apply annotations.
+
+## Commands
+
+```bash
+python3 skills/ppt-master/scripts/svg_editor/server.py <project_path> --daemon # plain mode (stage Step 1)
+python3 skills/ppt-master/scripts/svg_editor/server.py <project_path> --live --daemon # Generate Step 6 auto-startup
+python3 skills/ppt-master/scripts/svg_editor/server.py <project_path> --daemon --no-browser # remote host
+python3 skills/ppt-master/scripts/svg_editor/server.py <project_path> --shutdown
+```
+
+The launcher starts the server in the background, waits for `GET /api/health`, records pid + port in `<project_path>/live_preview/lock.json`, opens the browser when possible, and edits `<project_path>/svg_output/` in place.
+
+## Lifecycle
+
+- **Port**: without `--port`, the first free port from `6060`; `--port N` binds strictly and fails if unavailable. Read the actual URL from launch output or `live_preview/lock.json`; never assume `6060`.
+- **Idle timeout**: plain mode `900s`, `--live` `7200s`; `--timeout <seconds>` overrides (`0` disables).
+- **Single instance per project**: `live_preview/lock.json` is the discovery source for project-local consumers (including `visual_review.py`). A second launch reuses the live instance unless a different explicit `--port N` was requested — that mismatch fails and needs `--shutdown` first. Stale locks (dead pid) are overwritten; legacy `<project_path>/.live_preview.lock` root locks are still detected when live.
+- **Stop conditions**: **Exit preview** in the browser (the only UI action that stops Flask), a chat request to stop, the idle timeout, or an external kill.
+- **Transient ids**: each element gets a temporary `_edit_N` id while running; on save only annotated elements keep their id.
+- **Browser preview**: the server inlines `<use data-icon>` placeholders and serves `images/*`; the on-disk SVG is unchanged by preview.
+- **Re-export is chat-driven**: applying changes updates `svg_output/` only; refreshing the PPTX (`finalize_svg.py` + `svg_to_pptx.py`) is a chat step — the editor never runs the export pipeline.
+
+## Editing surface
+
+- **UI**: four languages (中文 / 繁體中文 / English / 日本語), auto-detected from `navigator.language`, persisted in `localStorage`, switchable from the right panel. The right panel separates direct SVG edits from AI-needed annotations, with a pending-status strip for staged edits and pages with unsaved annotations. Slide navigation: first/prev/next/last buttons plus `←` / `→` / `Home` / `End` (suppressed while typing in the annotation textarea).
+- **Buttons**: `Add annotation` stages annotation text in memory; `Apply changes` writes staged direct edits plus annotation markers (`data-edit-target`, `data-edit-annotation`) to disk and keeps the service running; `Exit preview` stops Flask.
+- **Direct edit (no AI)**: single element = full inspector (geometry, safe text content, computed text styles for the selected text node or descendant text, raw attributes except protected fields such as `id`, UI `class`, event handlers, hrefs). `<g>` group = group-level surface, selected via `Alt/Option` + click or **Select parent group**. Multi-select = batch editor over top-level objects only: shared x/y plus `fill` / `stroke` / `opacity`; text style fields appear only when every selected object is `text` / `tspan`. Preview updates immediately; disk writes wait for **Apply changes**.
+- **Drag to move**: press and drag an already-selected element (selection stays a separate click, so the background is never dragged by accident); the whole selection moves together. Pointer delta is mapped through each element's CTM, so moves track the cursor regardless of viewport scale or group transforms. Each release stages one direct edit per moved element; dragging on empty canvas is rubber-band selection; a failed stage rolls the canvas back.
+- **Arrow-key nudge**: `↑ ↓ ← →` moves the selection 1px, `Shift + arrow` 10px (suppressed while typing); arrow keys navigate slides only when nothing is selected. Same staging/coalescing as drag.
+- **Overlap picker**: right-click lists every selectable element under the pointer (top→bottom); hovering highlights, clicking selects, `Esc` or an outside click closes; with one element under the pointer, right-click selects it directly. Left-click selects the topmost.
+- **Undo**: `Ctrl+Z` or **Undo** drops the last staged direct edit on the current slide (per-slide LIFO, this session). Consecutive edits to the same element and field set coalesce into one step keeping the original pre-edit value. Applied old→new history goes to `live_preview/edits.jsonl`; annotation save/update/remove history to `live_preview/annotations.jsonl`; un-applied staged edits are memory only.
+- **Unsaved-work guard**: staged edits and annotation changes live in server memory until **Apply changes**; closing the tab triggers the browser's "leave site?" prompt while any are unapplied.
+
+## Remote access
+
+On a remote Linux host run with `--no-browser`, then with `<P>` from launch output or `live_preview/lock.json`: VS Code / Cursor Remote-SSH — forward `<P>` in the **PORTS** panel; Termius — a Local rule with Binding and Destination both `127.0.0.1:<P>`; plain SSH — `ssh -L <P>:127.0.0.1:<P> <user>@<host>`. Then open `http://localhost:<P>`.
diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.json
index 9ddda1ca..24edb6d0 100644
--- a/skills/ppt-master/scripts/prompt_audit_manifest.json
+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json
@@ -43,7 +43,7 @@
"skills/ppt-master/templates/tables/table-vocabulary.md": 500,
"skills/ppt-master/templates/sounds/sound-vocabulary.md": 6250,
"skills/ppt-master/workflows/generate-pptx.md": 10000,
- "skills/ppt-master/workflows/stages/apply-template-workspace.md": 3500,
+ "skills/ppt-master/workflows/stages/apply-template-workspace.md": 2750,
"skills/ppt-master/references/confirm-surface.md": 3000,
"skills/ppt-master/references/video-design.md": 2500,
"skills/ppt-master/references/native-formula.md": 1500,
@@ -54,7 +54,11 @@
"skills/ppt-master/references/artifact-ownership.md": 4500,
"skills/ppt-master/workflows/governance/failure-recovery.md": 2750,
"skills/ppt-master/workflows/stages/resume-execute.md": 1750,
- "skills/ppt-master/workflows/stages/refine-spec.md": 1000
+ "skills/ppt-master/workflows/stages/refine-spec.md": 1000,
+ "skills/ppt-master/workflows/stages/verify-charts.md": 2500,
+ "skills/ppt-master/workflows/stages/topic-research.md": 2000,
+ "skills/ppt-master/workflows/stages/live-preview.md": 1000,
+ "skills/ppt-master/workflows/stages/web-image-review.md": 750
},
"load_sets": {
"bootstrap.routing": {
@@ -1998,7 +2002,7 @@
{
"path": "skills/ppt-master/workflows/stages/apply-template-workspace.md",
"role": "consumer",
- "fingerprint": "2a2c42538a76",
+ "fingerprint": "8490326d972a",
"reason": "This stage documents how each Generate runtime consumes the prototype mapping."
},
{
@@ -2299,6 +2303,10 @@
{
"glob": "skills/ppt-master/scripts/docs/confirm_ui.md",
"reason": "Confirm UI server/schema reference; the Strategist reads references/confirm-surface.md for the surface decision and authoring payloads."
+ },
+ {
+ "glob": "skills/ppt-master/scripts/docs/svg_editor.md",
+ "reason": "Browser editor behavior and lifecycle reference; the live-preview stage carries the launch and annotation procedure."
}
]
}
diff --git a/skills/ppt-master/workflows/stages/apply-template-workspace.md b/skills/ppt-master/workflows/stages/apply-template-workspace.md
index c2276ce7..a3998189 100644
--- a/skills/ppt-master/workflows/stages/apply-template-workspace.md
+++ b/skills/ppt-master/workflows/stages/apply-template-workspace.md
@@ -4,47 +4,31 @@ description: Generate-PPTX runbook for validating and installing selected Brand,
# Apply Template Workspace Stage
-> Run from [`generate-pptx.md`](../generate-pptx.md) Step 4 only after Stage 1 confirms at least one exact template workspace. [`quick-generate`](../profiles/quick-generate.md) enters only for exact roots or a current Create Template handoff. Never load for free design, bare names, or style descriptions. This stage applies the completed Stage-1 selection; it never chooses a workspace or changes the communication contract.
+> Run from [`generate-pptx.md`](../generate-pptx.md) Step 4 only after Stage 1 confirms at least one exact template workspace; [`quick-generate`](../profiles/quick-generate.md) enters only for exact roots or a current Create Template handoff. Never load for free design, bare names, or style descriptions. This stage applies the completed selection; it never chooses a workspace or changes the communication contract.
## 1. Gate and Normalize Inputs
-🚧 **GATE**: Either Default Stage 1 confirmed a non-free template selection, or
-Quick received exact roots directly from the
-user/current Create Template handoff. In Quick, that explicit input is the complete selection authority: do
-not launch Confirm UI or create `template_options.json`,
-`template_selection.json`, or `template_handoff.json`. Every selected input must
-resolve to one of these current contracts:
+🚧 **GATE**: Default Stage 1 confirmed a non-free selection, or Quick received exact roots directly from the user/current Create Template handoff — in Quick that input is the complete selection authority (no Confirm UI, no `template_options.json` / `template_selection.json` / `template_handoff.json`). Every selected input resolves to one current contract:
| Input shape | Spec and SVG source | Asset source |
|---|---|---|
| Current workspace root | `<root>/templates/design_spec.md`, or one `design_spec.<kind>.<id>.md` per kind, plus `<root>/templates/` | Existing `<root>/images/` and `<root>/icons/` |
-| Current Create Template handoff | Its exact validated library or project workspace root | Existing portable sibling `images/` and `icons/`; already installed only when the root is the target project |
+| Current Create Template handoff | Its exact validated library or project workspace root | Portable sibling `images/` and `icons/`; already installed only when the root is the target project |
-Spec naming and kind declaration follow [`templates/README.md`](../../templates/README.md); a root exposing several kind-qualified specs contributes all of them. Do not accept only another project's inner `templates/` directory because that omits sibling assets.
-
-**Selection-source classification**:
+Spec naming and kind declaration follow [`templates/README.md`](../../templates/README.md); a root exposing several kind-qualified specs contributes all of them. Never accept only another project's inner `templates/` directory — that omits sibling assets.
| Source label | Resolution rule |
|---|---|
| `library` | The normalized root exactly equals `templates/<kind_dir>/<id>/` derived from an entry in that kind's `*_index.json` |
-| `explicit` | The user or Create Template supplied an exact workspace root that is not registered at that canonical index-derived root |
+| `explicit` | The user or Create Template supplied an exact root not registered at that canonical index-derived root |
-Read library choices only from `brands_index.json`, `styles_index.json`,
-`layouts_index.json`, and `decks_index.json`. Never scan kind directories or
-promote an unregistered directory into the UI catalog. An explicit root remains
-valid without index membership; exact equality with a registered root may be
-reported as `library`. The label changes discovery provenance only, never schema
-validation, segment precedence, or installation behavior.
+Read library choices only from the four `*_index.json` files; never scan kind directories or promote an unregistered directory into the catalog. The label changes discovery provenance only, never validation, precedence, or installation.
-**Selection cardinality**: Select at most one root per kind; all four kinds may
-coexist. A multi-kind explicit root contributes all its specs atomically and
-may combine only with non-overlapping kinds. Default permits one explicit root
-beside registered choices; Quick applies the same kind constraint. Reject
-duplicate kinds before validation.
+**Selection cardinality**: at most one root per kind; all four kinds may coexist. A multi-kind explicit root contributes all its specs atomically and combines only with non-overlapping kinds; reject duplicate kinds before validation.
-**Hard rule — raw source boundary**: A raw PPTX is not a template workspace. Raw PPTX plus new content uses [`edit-native-pptx`](../edit-native-pptx.md). When the user wants reusable SVG/template generation, run [`create-template`](../create-template.md) first; its validated workspace-root handoff becomes a Stage-1 candidate and is preselected only when it is the sole supplied root. Never add Master/Layout/placeholder structure directly to an existing PPTX or SVG project.
+**Hard rule — raw source boundary**: a raw PPTX is not a template workspace. Raw PPTX plus new content uses [`edit-native-pptx`](../edit-native-pptx.md); a reusable template request runs [`create-template`](../create-template.md) first, whose validated root becomes a Stage-1 candidate preselected only when it is the sole supplied root. Never add Master/Layout/placeholder structure directly to an existing PPTX or SVG project.
-**Current-contract gate**: Reject flat-root, semantic-legacy, or incomplete structured packages, including old baseline/distillation metadata, incomplete Master identity, or legacy direct atomic placeholders. Create a new current workspace through Create Template; use the original PPTX when native topology must be preserved.
+**Current-contract gate**: reject flat-root, semantic-legacy, or incomplete structured packages (old baseline/distillation metadata, incomplete Master identity, legacy direct atomic placeholders); create a new workspace through Create Template, from the original PPTX when native topology must be preserved.
## 2. Read the Matching Schema
@@ -53,187 +37,72 @@ Read [`templates/README.md`](../../templates/README.md), then only the README fo
| Kind | Schema | Owned segment |
|---|---|---|
| `brand` | [`templates/brands/README.md`](../../templates/brands/README.md) | Identity: color, typography, logo, voice/tone, icon style |
-| `style` | [`templates/styles/README.md`](../../templates/styles/README.md) | Direction/method: reusable communication method, visual language, composition, and information-expression defaults |
+| `style` | [`templates/styles/README.md`](../../templates/styles/README.md) | Direction/method: communication method, visual language, composition, information-expression defaults |
| `layout` | [`templates/layouts/README.md`](../../templates/layouts/README.md) | Structure: canvas, page structure, semantic text roles, page types, SVG roster |
| `deck` | [`templates/decks/README.md`](../../templates/decks/README.md) | Application plus integrated identity and structure |
-A Layout created with `mirror` remains eligible only when its source contract is brand-neutral and application-neutral. Keep a branded or application-bearing source as a Deck, or re-author it as Layout through `standard` / `fidelity`; do not remove those semantics through mirror.
-
-Before mapping any current workspace, run its shared package validator from the
-workspace root. This is the same schema authority used during creation and
-registration: Brand/Style are roster-free, the active structure validates its
-roster, and a shadowed Deck still validates its declared contract:
+A Layout created with `mirror` stays eligible only when its source is brand-neutral and application-neutral; keep a branded or application-bearing source as a Deck or re-author it through `standard` / `fidelity`. Before mapping any workspace, run the shared package validator from its root — Brand/Style are roster-free, the active structure validates its roster, a shadowed Deck still validates its contract; any error blocks installation:
```bash
python3 skills/ppt-master/scripts/svg_quality_checker.py "<workspace_root>/templates" --template-mode --canonical-authoring
```
-Any error blocks installation.
-
## 3. Structured Preflight
-Before copying a Deck or Layout workspace, inspect every SVG root and slot. Brand and Style workspaces are roster-free and skip this structured preflight:
-
-- Every page declares root Master/Layout keys and PowerPoint picker names.
-- Master/Layout visuals are direct atoms, not generic layer `<g>` wrappers.
-- Every non-composite slot is a top-level `<g>` with positive bounds and exactly one compatible carrier.
-- A composite region uses an explicit `object` proxy; a zero-slot Layout is valid.
-- The complete SVG contract is current. Reject a legacy semantic contract instead of repairing it in the target project.
+Before copying a Deck or Layout workspace (Brand and Style skip this), inspect every SVG root and slot: every page declares root Master/Layout keys and picker names; Master/Layout visuals are direct atoms, not layer `<g>` wrappers; every non-composite slot is a top-level `<g>` with positive bounds and exactly one compatible carrier; a composite region uses an explicit `object` proxy; zero-slot Layouts are valid; the contract is current — reject a legacy contract instead of repairing it in the target project.
## 4. Install Each Distinct Root Once
-Validate each normalized root once. Resolve the effective structural owner as
-Layout when selected, otherwise Deck; install only its SVG/non-bitmap
-structural payload, but install every selected spec. A library root contributes
-one bare `templates/design_spec.md`; install it
-as `design_spec.<kind>.<id>.md`, where `<id>` comes from the matching
-frontmatter id field. A current project root may contribute several qualified
-specs; preserve each validated qualified filename. Never merge spec bodies,
-and never copy one multi-kind root's shared SVG or asset pool once per kind.
-
-| Installed file | Meaning |
-|---|---|
-| `templates/design_spec.<kind>.<id>.md` | A template contribution installed into or authored in this project |
-| `templates/design_spec.md` | Library source shape only; never valid beside qualified project specs |
-
-For every copied spec, prepend exactly one provenance line under its H1, then
-leave the rest of the document untouched. An in-place root is not rewritten:
+Validate each normalized root once. The effective structural owner is Layout when selected, otherwise Deck; install only its SVG/non-bitmap structural payload, but install every selected spec. A library root's bare `templates/design_spec.md` installs as `design_spec.<kind>.<id>.md` (`<id>` from its frontmatter); a project root's qualified specs keep their validated filenames. Never merge spec bodies, and never copy one multi-kind root's shared SVG or asset pool once per kind. `templates/design_spec.md` is never valid beside qualified project specs. Prepend exactly one provenance line under each copied spec's H1 and leave the rest untouched (an in-place root is not rewritten):
```markdown
> **Installed from**: `skills/ppt-master/templates/brands/mckinsey/` (library)
```
-**Root mapping**:
-
-- Copy every selected spec from the root to its resolved qualified destination.
-- If the root contributes the effective structural owner, copy its declared
- SVG roster and other non-bitmap structural files once, including mirror
- `source_themes.json` when present. Do not copy a Deck roster when Layout is
- selected; its structure is shadowed by design. Preserve inline
- `<metadata type="application/json">` and
- `data-pptx-native-authority="json"` exactly; semantic Chart/Table JSON never
- moves into a sidecar during installation.
-- Copy the root's real package-owned `images/` and `icons/` files once. A
- Style-only root has none; reject a Style-only library package carrying asset
- or review payloads.
-- Ignore `exports/`; it contains review artifacts, not portable inputs.
-
-After that root-level copy, kinds have these downstream effects:
+**Root mapping**: copy every selected spec to its qualified destination; if the root is the structural owner, copy its declared SVG roster and other non-bitmap structural files once (including mirror `source_themes.json`), never a Deck roster shadowed by a selected Layout, preserving inline `<metadata type="application/json">` and `data-pptx-native-authority="json"` exactly; copy the root's package-owned `images/` and `icons/` once (a Style-only root has none — reject a Style-only library package carrying asset or review payloads); ignore `exports/`.
| Kind | Consumption behavior |
|---|---|
-| `brand` | Identity is constrained; structure remains free unless the selected set also includes Layout or Deck. |
-| `style` | Expose direction/method without identity, prototypes, or structure. Style-only and Style + Brand stay flat; Style + Layout/Deck follows that structure owner. Style never activates visual review. |
-| `layout` | Expose reusable structure and take precedence over Deck; Default plans against its prototypes, while Quick reads the complete roster and authors its Master/Layout/slot contract directly. |
-| `deck` | Expose descriptive application context and identity. It also supplies structure and the actual prototype roster only when no Layout is selected. |
-
-**Atomic install preflight**:
-
-1. Resolve every source and destination path.
-2. Enumerate the union mapping across all distinct roots and across
- `templates/`, `images/`, and `icons/`; map a source file at most once.
-3. Reject every destination collision and every duplicate-kind selection
- before writing. Resolve Layout-over-Deck structural precedence before
- constructing the destination map, so the shadowed Deck roster never enters
- that map.
-4. Write the accepted mapping once; never use recursive copy as an implicit conflict policy.
-
-Consume an input equal to the target project in place, mapping only other
-roots. If a selected Layout supersedes its in-place Deck roster, stage the
-accepted mapping and replace that roster atomically. Never mix rosters or write
-piecemeal. Ignore `exports/`; empty optional roots remain absent.
-
-**Hard rule — project-local consumer boundary**: After installation,
-Default template-aware Strategist work in final Stage 2, Quick's current
-agent before direct authoring, and every later role read only
-`<project_path>/templates/` and the project-local `images/` / `icons/` pools. The original library or external root
-is installation input, not a later prompt source. If source and target are the
-same project root, that in-place root already satisfies this boundary.
-
-Template SVGs are complete Slide authoring prototypes, not export-time overlays. They already resolve Master + Layout context, so `page_layouts` selects one directly. Standalone Master/Layout definition SVGs are invalid; an unselected authored Slide prototype may still back a reusable Layout definition.
-Default records `page_layouts` and the durable structure lock. Quick has no such
-planning artifact: it freezes the natural-language application paragraph in
-active context and writes the selected Master/Layout/slot contract directly
-into the complete output SVG pages. Quick stays flat only without a Layout/Deck
-structure owner or under an explicit visual-only instruction.
-
-For a template-owned Chart/Table carrying
-`data-pptx-native-authority="json"`, the installed inline JSON remains the
-object's data/native authority. A generated page may retain its existing compact
-preview or regenerate an approximate preview from updated JSON, but it must not
-derive replacement JSON from that preview. Keep the authority marker and JSON
-inside the generated SVG so default fallback and explicit native export remain
-two renderings of one object contract.
+| `brand` | Identity constrained; structure free unless Layout or Deck is also selected |
+| `style` | Direction/method without identity, prototypes, or structure; Style-only and Style + Brand stay flat, Style + Layout/Deck follows that owner; Style never activates visual review |
+| `layout` | Reusable structure, precedence over Deck; Default plans against its prototypes, Quick reads the roster and authors its Master/Layout/slot contract directly |
+| `deck` | Descriptive application context and identity; structure and prototype roster only when no Layout is selected |
+**Atomic install preflight**: resolve every source and destination path; enumerate the union mapping across all roots and across `templates/`, `images/`, `icons/`, mapping each source file at most once; resolve Layout-over-Deck precedence before building the map so the shadowed roster never enters it; reject every destination collision and duplicate kind before writing; write the accepted mapping once — never recursive copy as an implicit conflict policy. An input equal to the target project is consumed in place; if a selected Layout supersedes its in-place Deck roster, stage the mapping and replace the roster atomically.
-## 5. Segment Precedence Is Resolved While Reading
+**Hard rule — project-local consumer boundary**: after installation, Default final Stage 2, Quick's agent before authoring, and every later role read only `<project_path>/templates/` and the project-local `images/` / `icons/` pools; the library or external root is installation input only.
-Installation copies specs; it never merges them. The consuming role — Default
-final Stage 2 through [`strategist-template.md`](../../references/strategist-template.md),
-or Quick's current agent before authoring — reads **every** installed
-`design_spec.<kind>.<id>.md` and resolves the segments below in context. Asset
-collisions are still rejected at install time (§4); segment conflicts are a
-reading decision, not a write-time one.
+Template SVGs are complete Slide authoring prototypes (Master + Layout context already resolved), so `page_layouts` selects one directly; standalone Master/Layout definition SVGs are invalid, and an unselected authored prototype may still back a reusable Layout definition. Default records `page_layouts` and the structure lock; Quick freezes the natural-language application paragraph in active context and writes the Master/Layout/slot contract directly into the output SVGs, staying flat only without a structure owner or under an explicit visual-only instruction. For a template-owned Chart/Table carrying `data-pptx-native-authority="json"`, the installed inline JSON remains the object's authority: a page may keep or regenerate the preview from that JSON but never derives replacement JSON from the preview.
-Never reinterpret, predict, or revise the confirmed Stage-1 communication
-contract here. Default obtains any additional material conflict decision
-through the active chat channel after Stage 1; this does not reopen template
-selection. Quick follows explicit conflict instructions; an unresolved material
-compatibility conflict is a hard prerequisite handled in chat, never by
-launching Confirm UI or by using path order.
+## 5. Segment Precedence Is Resolved While Reading
-### 5.1 Different Kinds
+Installation copies specs; it never merges them. The consuming role — Default final Stage 2 through [`strategist-template.md`](../../references/strategist-template.md), or Quick's agent before authoring — reads every installed `design_spec.<kind>.<id>.md` and resolves the segments in context; asset collisions are rejected at install time (§4), segment conflicts are a reading decision. Never reinterpret the confirmed Stage-1 contract here: Default obtains any additional material conflict decision through chat after Stage 1 without reopening selection; Quick follows explicit conflict instructions, and an unresolved material conflict is a hard prerequisite handled in chat, never by Confirm UI or path order.
-Resolve four whole template segments. This table names the starting owner;
-current user instructions and the consuming plan still govern project use:
+### 5.1 Different Kinds
| Segment | Starting owner |
|---|---|
-| Identity | Brand, otherwise Deck, otherwise unresolved until the consuming plan (Default final Stage 2 or Quick active context). Style color/type/icon/image values are direction candidates, never identity truth. |
-| Structure | Layout when present, otherwise Deck, otherwise unresolved/free design until the consuming plan. Style owns no canvas, prototype, Master/Layout, slot, or page mapping. |
-| Reusable application context | Deck only when present. Preserve it for the consuming comparison; it never becomes the current project's application contract. |
-| Direction / method | Style when present, otherwise unresolved until the consuming plan. Actual Deck prototypes and Signature facts may inform compatibility, but Deck does not own the Style-only method segment. |
-
-Apply each selected segment wholesale; do not mix its fields implicitly. Brand or Deck identity overrides any identity-adjacent defaults carried by Style. A Style direction may adapt to that resolved identity, but cannot relabel its candidates as official brand facts.
-
-**Hard rule — an owned segment governs visual weight, not only values**: when a
-segment owner declares how a value should dominate, recede, or stay rare, that
-instruction carries the same authority as the value itself. A Style's
-composition or whitespace tendency never demotes a Brand's declared dominant
-color to an incidental accent.
-
-Before Style overlays Layout or Deck guidance, verify that its method fits the
-selected structure and, for Deck, serves its reusable context. On mismatch,
-require omitting Style or choosing a compatible Style/structure; never silently
-weaken a segment. Default final Stage 2 separately checks the result against the
-confirmed project contract; Quick checks it against the current request/content
-before authoring.
+| Identity | Brand, otherwise Deck, otherwise unresolved until the consuming plan; Style color/type/icon/image values are direction candidates, never identity truth |
+| Structure | Layout when present, otherwise Deck, otherwise free design until the consuming plan; Style owns no canvas, prototype, Master/Layout, slot, or page mapping |
+| Reusable application context | Deck only; preserved for comparison, never the current project's application contract |
+| Direction / method | Style when present, otherwise unresolved; Deck prototypes and Signature facts inform compatibility but do not own this segment |
-Field-level micro-adjustments such as a primary-color override are not a workspace selection. Default carries them into the normal final Stage-2 confirmation fields; Quick treats explicit adjustments as direct active-context authoring constraints.
+Apply each segment wholesale; never mix fields implicitly. Brand or Deck identity overrides Style's identity-adjacent defaults; a Style direction adapts to that identity but cannot relabel its candidates as brand facts. **Hard rule — an owned segment governs visual weight, not only values**: when an owner declares how a value dominates, recedes, or stays rare, that instruction carries the value's authority; a Style's whitespace tendency never demotes a Brand's dominant color to an accent. Before Style overlays Layout or Deck guidance, verify its method fits the structure (and, for Deck, its reusable context); on mismatch require omitting Style or choosing a compatible pair, never silently weakening a segment. Field-level micro-adjustments such as a primary-color override are not a workspace selection: Default carries them into the Stage-2 confirmation fields, Quick treats them as direct authoring constraints.
### 5.2 Selection Conflicts
-Duplicate kinds are selection errors. Layout plus Deck is valid: Layout owns
-structure; Deck keeps its other segments. Default returns duplicates to Stage
-1; Quick asks for narrower roots. Never split a multi-kind root, average
-same-kind specs, or choose by path order.
+Duplicate kinds are selection errors: Default returns them to Stage 1, Quick asks for narrower roots. Layout plus Deck is valid — Layout owns structure, Deck keeps its other segments. Never split a multi-kind root, average same-kind specs, or choose by path order.
### 5.3 Installed Set
-Each installed file keeps its own frontmatter `kind` and `<id>` from its source
-workspace; nothing is relabelled. There is no combined capability label and no
-merged spec: the installed set is exactly what was selected, and the routing
-consequence is derived while reading — structure comes from Layout when
-present, otherwise Deck; identity comes from Brand or Deck; direction comes
-from Style. A project-local Brand + Layout pair does not become a reusable library
-Deck; its application remains current-project context.
+Each installed file keeps its own frontmatter `kind` and `<id>`; nothing is relabelled or merged. Routing is derived while reading — structure from Layout, else Deck; identity from Brand or Deck; direction from Style. A project-local Brand + Layout pair does not become a reusable library Deck.
-**Completion receipt**: Report `roots=<unique normalized roots>; sources=<library|explicit per root>; kinds=<all contributed kinds per root>; segments=identity:<owner>,structure:<owner>,application_context:<owner>,direction:<owner>; active_roster=<layout|deck|none>:<source root>; install=<in-place|copied>; installed_specs=<comma-separated design_spec.<kind>.<id>.md>`.
+**Completion receipt**: `roots=<unique normalized roots>; sources=<library|explicit per root>; kinds=<all contributed kinds per root>; segments=identity:<owner>,structure:<owner>,application_context:<owner>,direction:<owner>; active_roster=<layout|deck|none>:<source root>; install=<in-place|copied>; installed_specs=<comma-separated design_spec.<kind>.<id>.md>`.
## ✅ Template Workspace Applied
-- [x] Every selected input was an index-derived library root or an exact explicit/Create Template root satisfying a listed workspace contract
+- [x] Every selected input was an index-derived library root or an exact explicit/Create Template root satisfying a listed contract
- [x] Every kind schema passed preflight; structured SVG checks ran only for Layout/Deck inputs
-- [x] Duplicate kinds and all destination collisions were rejected before one atomic install; Layout-over-Deck precedence selected exactly one active structural roster
-- [x] `<project_path>/templates/` and any portable sibling assets are complete and are the only downstream template source
+- [x] Duplicate kinds and destination collisions were rejected before one atomic install; Layout-over-Deck precedence selected exactly one active roster
+- [x] `<project_path>/templates/` and portable sibling assets are complete and the only downstream template source
- [ ] **Next**: Default completes the template-selection handoff and continues [`generate-pptx.md`](../generate-pptx.md) Step 4 Stage 2; Quick returns to [`quick-generate`](../profiles/quick-generate.md) §2
diff --git a/skills/ppt-master/workflows/stages/live-preview.md b/skills/ppt-master/workflows/stages/live-preview.md
index 98183fb4..4193a8c2 100644
--- a/skills/ppt-master/workflows/stages/live-preview.md
+++ b/skills/ppt-master/workflows/stages/live-preview.md
@@ -4,103 +4,38 @@ description: Main-pipeline editor stage for starting live preview and applying s
# Live Preview Stage
-> **Purpose**: (1) start/reopen the browser SVG editor when no preview service is currently running, and (2) apply user-submitted annotations after Step 7 export completes.
->
-> **Not in scope**: Executor's mandatory auto-startup — that lives in [`generate-pptx`](../generate-pptx.md) Step 6. Do not re-launch a preview that is already running.
+> (1) Start/reopen the browser SVG editor when no preview service is running; (2) apply user-submitted annotations after Step 7 export. Executor's mandatory auto-startup lives in [`generate-pptx`](../generate-pptx.md) Step 6 — never re-launch a preview that is already running. Editor behavior, lifecycle, ports, and remote access are documented in [`svg_editor.md`](../../scripts/docs/svg_editor.md).
## When to Run
-- **Start (Step 1)** — preview service is not currently running and the user wants to look at the deck or click an element. Typical cases: post-export re-entry in a fresh chat, or the user clicked **Exit preview** earlier and now wants it back.
-- **Apply annotations (Step 2)** — Step 7 has produced at least one PPTX, and the user signals that submitted annotations should now be applied. Triggers include:
- - quoting the browser prompt (`Changes saved to svg_output...` / `修改已保存到 svg_output...`)
- - saying `apply my annotations` / `apply my edits` / `应用注解` / `开始应用` / or equivalent expressions
+- **Step 1** — no preview service is running and the user wants to look at the deck or click an element (post-export re-entry in a fresh chat, or the user clicked **Exit preview** earlier).
+- **Step 2** — Step 7 has produced at least one PPTX and the user signals that annotations should be applied: quoting the browser prompt (`Changes saved to svg_output...` / `修改已保存到 svg_output...`) or saying `apply my annotations` / `apply my edits` / `应用注解` / `开始应用`.
-## When NOT to Run
-
-- The preview service is already running → just give the user the URL; do not restart.
-- The user gave a precise chat edit ("change page 3 title to X") → edit the SVG directly.
-- The user wants a full regeneration → use the main workflow.
-- Step 7 has never run for this project → annotations cannot be applied yet; finish the main pipeline first.
+**When not to run**: the service is already running → give the URL; a precise chat edit ("change page 3 title to X") → edit the SVG directly; a full regeneration → main workflow; Step 7 has never run → finish the main pipeline first.
---
## Step 1: Start / reopen the editor
-**Precondition**: no preview service running on this project.
-
```bash
python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --daemon
```
-(Plain mode — no `--live`. The `--live` flag is reserved for Step 6's auto-startup.)
-
-The launcher starts the server in the background on its selected port, waits for `GET /api/health`, records the actual pid + port in `<project_path>/live_preview/lock.json`, opens the browser when possible, and edits `<project_path>/svg_output/` in place. After it prints the running URL, tell the user in their language, in one short message:
+Plain mode, no `--live` (reserved for Step 6). Launch immediately — the user already asked. Report the actual URL from the launch output or `<project_path>/live_preview/lock.json`, never an inferred `6060`; on a remote host add `--no-browser` and forward the port. Then tell the user, in their language, in one short message:
-- editor is at the URL reported by the launcher, e.g. `http://127.0.0.1:6060`
-- **Direct edit** (deterministic tweaks — wording, color, coordinates, SVG attributes): select an element → change the controls in the right panel → preview updates immediately, but nothing is written to `svg_output/` until **Apply changes**. `Ctrl+Z` or the **Undo** button drops staged edits step by step; applied changes are logged to `<project>/live_preview/edits.jsonl`. Re-export stays chat-driven and separate: say "re-export" / "重新导出" to refresh the PPTX.
-- **Annotate** (changes that need AI judgement / re-layout): select an element → write the instruction, optionally starting from a quick type such as move / resize / replace image / copy / relayout → click **Add annotation** to stage it → click **Apply changes** to write annotation markers → return to the chat and say `apply my annotations` (or quote the browser prompt)
-- to skip the editor, just describe the change in chat
-
-Launch immediately — the user already asked for preview. Report the actual URL from the output or project lock; never infer it from `6060`. Remote access → see the appendix.
+- the editor URL;
+- **Direct edit** for deterministic tweaks (wording, color, coordinates, attributes): select an element → change the right-panel controls → preview updates immediately, nothing is written until **Apply changes**; `Ctrl+Z` / **Undo** drops staged edits; re-export stays chat-driven ("re-export" / "重新导出");
+- **Annotate** for changes needing AI judgement or re-layout: select an element → write the instruction (optionally from a quick type such as move / resize / replace image / copy / relayout) → **Add annotation** → **Apply changes** → return to chat and say `apply my annotations`;
+- to skip the editor, describe the change in chat.
---
## Step 2: Apply submitted annotations
-🚧 **GATE**: `<project_path>/exports/` contains at least one `*.pptx` (Step 7 has completed). If not, do not apply annotations — tell the user to finish the main pipeline first.
-
-Triggered by the user signals listed in "When to Run".
-
-1. Discover annotations:
- ```bash
- python3 ${SKILL_DIR}/scripts/check_annotations.py <project_path>
- ```
- The output already lists each pending change as `file → element_id → annotation text → content preview`. Use it directly as the to-do list; no need to re-parse SVG attributes yourself.
-2. If the output says no annotations: tell the user, stop.
-3. For each listed annotation:
- - Edit the targeted element in `<project_path>/svg_output/<file>` per the annotation text.
- - Remove `data-edit-target` and `data-edit-annotation` from that element.
- - Append one `annotation_applied` JSONL record to `<project_path>/live_preview/annotations.jsonl` with `ts`, `file`, `element_id`, and the original annotation text.
-4. Re-enter [`generate-pptx`](../generate-pptx.md) Step 7.2, wait for its success criterion, then run Step 7.3. Do not rerun Step 7.1 unless speaker notes changed.
-5. Tell the user (in their language): annotations applied, new PPTX exported, preview is still running. If the browser still shows the old slide, refresh or reselect the page.
-6. Loop: more annotations submitted → repeat from step 1. User signals done or "stop preview" → end.
-
----
-
-## Notes (editor invariants — referenced from Generate Step 6)
-
-- **UI**: four-language (中文 / 繁體中文 / English / 日本語); auto-detects from `navigator.language`, persists in `localStorage`, switched via the language dropdown on the right panel. The right panel is an **Edit / Annotate** surface: direct SVG edits and AI-needed annotations are visually separated, with a pending-status strip showing staged direct edits and pages with unsaved annotations. Slide navigation: first/prev/next/last buttons at the top of the center panel, plus `←` / `→` / `Home` / `End` (suppressed while typing in the annotation textarea).
-- **Buttons**: `Add annotation` stages annotation text in memory; `Apply changes` writes staged direct edits plus annotation markers to disk and keeps the service running; `Exit preview` is the only UI action that stops Flask.
-- **Direct edit (no AI)**: selection mode determines the right-panel surface. Single element = full object inspector (geometry, safe text content, computed text styles for the selected text node or descendant text inside a selected textbox/group, raw SVG attributes except protected fields like `id`, UI `class`, event handlers, and hrefs). SVG `<g>` group = group-level edit surface; select via `Alt/Option` + click or **Select parent group** from a child element. Multi-select = limited batch editor over top-level selected objects only: shared x/y plus `fill` / `stroke` / `opacity`; text style fields (`font-size` / `font-family` / `font-weight` / `text-anchor`) appear only when every selected object is `text`/`tspan`. Preview updates immediately; disk writes wait for **Apply changes**.
-- **Drag to move**: press and drag an already-selected element on the canvas to reposition it (selection stays a separate click, so the background is never dragged by accident); the whole selection moves together under multi-select. The pointer delta is mapped through each element's own CTM, so moves track the cursor regardless of viewport scale or group transforms. Each release stages one direct edit per moved element (the same `x`/`y`-or-`transform` write the geometry inputs produce), previewed live and written only on **Apply changes**; dragging on empty canvas is still rubber-band selection. A failed stage rolls the canvas back to the pre-drag position.
-- **Arrow-key nudge**: with one or more elements selected, `↑ ↓ ← →` moves the selection 1px and `Shift + arrow` moves 10px (suppressed while typing in the annotation box). Arrow keys navigate slides only when nothing is selected. Same staging/coalescing path as drag, so a burst of nudges collapses to one undo step.
-- **Overlap picker**: right-click anywhere on the canvas to list every selectable element under the pointer (top→bottom), so stacked shapes can be reached without blind cycling. Left-click is unchanged (selects the topmost). Hovering a row highlights that element; clicking it selects it; `Esc` or an outside click closes the list. With exactly one element under the pointer, right-click selects it directly.
-- **Undo**: `Ctrl+Z` or the **Undo** button drops the last staged direct edit on the current slide (per-slide LIFO, this session). Consecutive edits to the *same element and same field set* (e.g. nudging one color or coordinate several times) coalesce into a single undo step, keeping the original pre-edit value; switching element or field starts a new step. Applied old→new history is appended to `<project>/live_preview/edits.jsonl`; annotation save/update/remove history is appended to `<project>/live_preview/annotations.jsonl`; un-applied staged edits are in-memory only.
-- **Unsaved-work guard**: staged direct edits and annotation changes (added or removed) live in server memory until **Apply changes**; closing the tab triggers the browser's native "leave site?" prompt while any are unapplied, since an idle timeout or process kill would drop them.
-- **Re-export is chat-driven**: applying changes updates `svg_output/` only. Refreshing the PPTX (finalize + svg_to_pptx) stays a chat step — the editor never runs the export pipeline or presents browser-side export as part of applying edits.
-- **Stop conditions**: the service stops when the user clicks **Exit preview** in the browser, asks in chat to stop it, the idle timeout fires, or the process is killed externally.
-- **Port**: without `--port`, use the first free port from `6060`; `--port N` binds `N` strictly and fails if unavailable. Read the actual URL from launch output or `<project_path>/live_preview/lock.json`.
-- **Idle timeout**: plain mode `900s`, `--live` mode `7200s`; override with `--timeout <seconds>` (`0` disables).
-- **Single instance per project**: `<project_path>/live_preview/lock.json` records the running pid + actual port and is the discovery source for project-local consumers. A second launch reuses the live instance unless an explicit, different `--port N` was requested; that mismatch fails and requires `--shutdown` before restart. Stale locks (dead pid) are overwritten on the next launch. Legacy root locks at `<project_path>/.live_preview.lock` are still detected when they point to a live process.
-- **Transient ids**: each element gets a temporary `_edit_N` id while the editor is running. On save, only annotated elements keep their id; unannotated `_edit_N` ids are stripped before write-back.
-- **Browser preview**: the server inlines `<use data-icon>` placeholders and serves `images/*` so SVG renders correctly; the on-disk SVG is unchanged by this preview.
-
----
-
-## Appendix: Remote access
-
-If the project lives on a remote Linux server, run with `--no-browser`:
-
-```bash
-python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --daemon --no-browser
-# or for Step 6's auto-startup on a remote host:
-python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live --daemon --no-browser
-```
-
-Let `<P>` be the port in launch output or `<project_path>/live_preview/lock.json`:
-
-- **VS Code / Cursor Remote-SSH**: in the **PORTS** panel, forward `<P>`.
-- **Termius**: add a Local rule with Binding and Destination both `127.0.0.1:<P>`, then start it.
-- **Plain SSH**: `ssh -L <P>:127.0.0.1:<P> <user>@<host>`.
+🚧 **GATE**: `<project_path>/exports/` contains at least one `*.pptx`; otherwise tell the user to finish the main pipeline first.
-Then open `http://localhost:<P>` locally.
+1. `python3 ${SKILL_DIR}/scripts/check_annotations.py <project_path>` — its output lists each pending change as `file → element_id → annotation text → content preview`; use it directly as the to-do list. If it reports none, tell the user and stop.
+2. For each annotation: edit the targeted element in `<project_path>/svg_output/<file>` per the text; remove `data-edit-target` and `data-edit-annotation` from it; append one `annotation_applied` JSONL record (`ts`, `file`, `element_id`, original text) to `<project_path>/live_preview/annotations.jsonl`.
+3. Re-enter [`generate-pptx`](../generate-pptx.md) Step 7.2, wait for its success criterion, then run Step 7.3; rerun Step 7.1 only when speaker notes changed.
+4. Tell the user, in their language: annotations applied, new PPTX exported, preview still running (refresh or reselect the page if the browser shows the old slide).
+5. More annotations → repeat from 1; "done" or "stop preview" → end.
diff --git a/skills/ppt-master/workflows/stages/topic-research.md b/skills/ppt-master/workflows/stages/topic-research.md
index 937f98ad..307cdaca 100644
--- a/skills/ppt-master/workflows/stages/topic-research.md
+++ b/skills/ppt-master/workflows/stages/topic-research.md
@@ -4,130 +4,64 @@ description: Generate source-intake stage that fills factual gaps and records ad
# Topic Research Stage
-> Factual preparation inside the active Generate profile's source intake.
-> Default Generate hands its output to Strategist; Quick Generate's main agent
-> consumes the same output. Run immediately for topic-only input, or after
-> supplied material is converted and read when it leaves planning-critical
-> factual gaps. Output is exactly a research supplement plus stable fact
-> provenance for project import. Adopted webpage URLs remain in the provenance
-> file and are not expanded during the project-initialization handoff.
-
-This stage supplies facts needed to build the requested deck and records the
-webpages actually adopted during that research. It makes no deck image
-selection and performs no independent image search or generation. The facts
-JSON is provenance, not a page-download queue: `project_manager.py
-import-sources` imports the research pair without fetching its `source_url`
-values. A page may be fetched later only for the bounded image fallback below.
+> Factual preparation inside the active Generate profile's source intake: Default hands its output to Strategist, Quick's main agent consumes it. Run immediately for topic-only input, or after supplied material is converted and read when it leaves planning-critical factual gaps. Output is exactly a research supplement plus stable fact provenance for project import. The facts JSON is provenance, not a page-download queue: `import-sources` imports the pair without fetching `source_url` values; a page may be fetched later only through the bounded image fallback below. This stage makes no deck image selection and performs no image search or generation.
## When to Run
| Material state | Action |
|---|---|
-| Topic or requirements with no supporting facts | Research the factual baseline needed for the requested outcome |
-| Supplied files or chat content cover only part of the requested outcome | After conversion and reading, research only the identified externally verifiable gaps |
-| Supplied material already supports the requested outcome | Skip this stage and continue the active Generate profile's source preparation |
-| User requires a closed corpus, source-only transformation, or no external enrichment | Skip this stage and keep planning within supplied material |
+| Topic or requirements with no supporting facts | Research the factual baseline for the requested outcome |
+| Supplied material covers only part of the outcome | After conversion and reading, research only the identified externally verifiable gaps |
+| Supplied material already supports the outcome | Skip; continue the profile's source preparation |
+| User requires a closed corpus, source-only transformation, or no external enrichment | Skip; plan within supplied material |
-**Sufficiency test**: a gap exists when the active content owner would otherwise need to invent, omit, or leave unsupported an externally verifiable claim required by the user's requested outcome. File presence, source length, and a generic topic taxonomy do not decide sufficiency.
+**Sufficiency test**: a gap exists when the content owner would otherwise have to invent, omit, or leave unsupported an externally verifiable claim the requested outcome needs; file presence, source length, and topic taxonomy do not decide it.
-**Hard rule — preserve supplied facts**: supplement the user's material; never
-silently replace it. Record a material source conflict in the research output
-for the active content owner instead of choosing a different claim without
-disclosure. Do not research omissions outside the requested scope.
+**Hard rule — preserve supplied facts**: supplement the user's material, never silently replace it; record a material source conflict in the research output instead of choosing a different claim without disclosure. Do not research omissions outside the requested scope.
---
## Step 1: Define the gap brief
-**Clarification boundary**: Default Generate bundles only genuinely missing
-scope or research-boundary decisions into one clarifier. Quick Generate applies
-the defaults below and continues without interaction; stop only when a required
-permission or safety boundary cannot be inferred responsibly. Skip clarification
-when the request and supplied material are already clear.
-
| Item | Default if unspecified |
|---|---|
-| Topic | From the user request |
-| Requested scope / outcome | From the user request; otherwise broad overview |
+| Topic / scope / outcome | From the request; otherwise broad overview |
| Supplied-material baseline | Facts and claims already available |
-| Research gaps | Only facts needed to support the requested outcome |
-| External-source boundary | External factual enrichment allowed; supplied facts remain authoritative inputs |
+| Research gaps | Only facts needed to support the outcome |
+| External-source boundary | External enrichment allowed; supplied facts remain authoritative |
| Output language | Match user input |
-| Target audience / communication intent | Use what is explicit; Default leaves final confirmation to Strategist, while Quick resolves routine gaps in active context |
-| Research stem (`<research_slug>`) | `<topic_slug>_research`; choose another unused snake_case stem rather than overwrite an existing file |
+| Audience / communication intent | Use what is explicit; Default leaves confirmation to Strategist, Quick resolves routine gaps in context |
+| Research stem `<research_slug>` | `<topic_slug>_research`, or another unused snake_case stem rather than overwriting |
-Do not repeat the full default-pipeline confirmation here. Default Generate
-confirms the complete communication contract in Step 4; Quick Generate adds no
-confirmation stage.
+Default bundles only genuinely missing scope or research-boundary decisions into one clarifier; Quick applies the defaults and continues, stopping only when a required permission or safety boundary cannot be inferred responsibly. Do not repeat the full-pipeline confirmation here.
---
## Execution Context
-**Default — isolated research when available**: The main agent owns the sufficiency decision and gap brief. When the current AI editor supports and permits an isolated subagent with web/fetch access and write access to the declared outputs, dispatch exactly one research worker. Otherwise the main agent runs Steps 2–3 locally.
-
-| Actor | Contract |
-|---|---|
-| Main agent | Supply the topic/outcome, baseline or relevant source paths, declared gaps, output language, two exact unused output paths, and this stage's absolute path as execution authority; use paths instead of pasting source bodies when possible |
-| Research worker | Read the supplied stage file completely, then follow Steps 2–3 using the brief and declared source paths as its baseline; limit project writes to the two output artifacts; perform no independent image search/generation and make no deck-planning, image-selection, or design decisions |
+**Default — isolated research when available**: the main agent owns the sufficiency decision and brief. When the host supports an isolated subagent with web/fetch access and write access to the declared outputs, dispatch exactly one research worker with the topic/outcome, baseline or source paths, declared gaps, output language, two exact unused output paths, and this stage's absolute path as execution authority (paths, not pasted source bodies). The worker reads this file completely, follows Steps 2–3, limits project writes to the two artifacts, and makes no image, deck-planning, or design decisions. Otherwise the main agent runs Steps 2–3 locally.
-**Hard rule — isolate retrieval, not research**: Raw page content and fetch transcripts stay in the worker context. The 250-word limit applies only to its chat receipt: return `status`, exact artifact paths, covered/unresolved gap counts, external-fact count, and material conflicts. It does not cap or replace the two artifacts. After validation and import, the active content owner reads the complete imported research supplement and fact-provenance JSON into the main context before planning or direct SVG authoring; never use the receipt or validation summary as content.
+**Hard rule — isolate retrieval, not research**: raw page content stays in the worker context. The 250-word limit applies only to its chat receipt (`status`, artifact paths, covered/unresolved gap counts, external-fact count, material conflicts), never to the artifacts. After validation and import, the content owner reads the complete imported pair into the main context; never use the receipt as content.
-**Validation**: Before import, the main agent verifies both exact files exist, the Markdown contains `## Research Brief` and no source list or URL, the JSON parses with schema `ppt-master.fact-provenance.v1` and unique sequential IDs, and the two files agree. Return an invalid pair to the research worker for owning-artifact repair; use main-context web research only when isolated execution is unavailable.
+**Validation**: before import, verify both files exist, the Markdown contains `## Research Brief` and no source list or URL, the JSON parses with schema `ppt-master.fact-provenance.v1` and unique sequential IDs, and the two agree. Return an invalid pair to the worker for repair; use main-context research only when isolation is unavailable.
---
## Step 2: Gather factual sources
-Use the web search and fetch tools available in the active research context. An isolated worker without them returns `blocked: web-tools-unavailable`. If no usable research context has search/fetch tools, the main agent pauses and asks the user for authoritative URLs covering the declared gaps, then fetches each with:
-
-```bash
-python3 ${SKILL_DIR}/scripts/source_to_md/web_to_md.py <URL> \
- -o projects/<research_slug>_web_sources/<source_slug>.md --no-images
-```
-
-Preserve the resulting Markdown and conversion profile for research. Remote
-inline-image links remain in the Markdown; no image files are downloaded.
-
-| Phase | Action |
-|---|---|
-| Orient | Search only far enough to map authoritative sources to the declared gaps |
-| Deep fetch | Read the highest-signal primary or authoritative pages in full |
-| Targeted fill | Search only for gaps still unsupported after those reads |
-
-| Priority | Source |
-|---|---|
-| 1 | Primary sources, official sites, institutional releases, standards, or original research |
-| 2 | Authoritative reference works and reputable academic sources |
-| 3 | Reputable reporting or analysis when primary evidence is unavailable |
-| Avoid | Unsourced reposts, unverifiable summaries, and stock-aggregator pages |
+Use the search and fetch tools available in the research context; an isolated worker without them returns `blocked: web-tools-unavailable`. With no usable search/fetch context, pause and ask the user for authoritative URLs covering the gaps, then fetch each with `web_to_md.py <URL> -o projects/<research_slug>_web_sources/<source_slug>.md --no-images` (remote image links stay in the Markdown; nothing is downloaded).
-**Adopted webpage boundary**: Record a page URL only in the matching fact's
-`source_url`, and only when it materially supports that retained fact. Do not
-retain a page merely because its images may be useful, and do not add unopened
-search results or pages found through a separate image-search pass.
+Orient (map authoritative sources to the gaps) → deep fetch (read the highest-signal primary pages in full) → targeted fill (search only for gaps still unsupported). Prefer primary sources, official sites, institutional releases, standards, and original research; then authoritative reference works and academic sources; then reputable reporting; avoid unsourced reposts, unverifiable summaries, and stock-aggregator pages.
-**Stop condition**: stop when every declared gap has enough sourced evidence for
-the active content owner to decide whether and how to include it. Do not expand
-into unrelated overview / history / outlook sections merely to make the
-research look complete.
+**Adopted webpage boundary**: record a URL only in the matching fact's `source_url`, and only when it materially supports that fact — never because its images may be useful, and never from unopened search results or a separate image-search pass. Stop when every declared gap has enough sourced evidence for the content owner to decide inclusion; do not add overview/history/outlook sections to look complete.
---
## Step 3: Save the factual supplement
-Write two artifacts under `projects/`:
-
-| Artifact | Path |
-|---|---|
-| Research supplement | `projects/<research_slug>.md` |
-| Fact provenance | `projects/<research_slug>.facts.json` |
-
-**Hard rule — location and preservation**: write both files under `projects/`, never the repository root. Do not overwrite an existing user file; choose a new research stem instead. Do not create a research-image manifest or download embedded images.
-
-Begin the research Markdown with a compact `## Research Brief` containing the supplied-material baseline, declared gaps, audience / intent already known, and requested outcome. Organize the body by gap, include concrete facts only, flag material conflicts, and cite claims by `fact_id`. Do not add `## Sources` or URLs; the facts JSON is the only URL authority.
+Write `projects/<research_slug>.md` and `projects/<research_slug>.facts.json` — under `projects/`, never the repository root; never overwrite an existing user file; no research-image manifest or downloaded images.
-Write every externally sourced claim that may enter the deck to `<research_slug>.facts.json` with a stable sequential ID, especially quantitative, date, ranking, attribution, and named-entity claims. Do not include user-supplied claims or invented scenario values. When no external claim is retained, write the schema with an empty `facts` array.
+The Markdown begins with a compact `## Research Brief` (baseline, declared gaps, known audience/intent, requested outcome), then organizes the body by gap with concrete facts only, flags material conflicts, and cites claims by `fact_id`; no `## Sources` or URLs — the JSON is the only URL authority. The JSON records every externally sourced claim that may enter the deck (especially quantitative, date, ranking, attribution, and named-entity claims) with immutable sequential IDs — correct a claim under the same ID, never reuse a removed ID; no user-supplied claims or invented scenario values; an empty `facts` array when nothing external is retained.
```json
{
@@ -146,58 +80,26 @@ Write every externally sourced claim that may enter the deck to `<research_slug>
}
```
-IDs are immutable within the file. Correct a claim under the same ID; never reuse a removed ID for a different fact. The research Markdown and provenance file must agree.
-
---
## Hand-off
-After project initialization, import the research pair and user-supplied
-sources. The facts JSON is imported as an ordinary source file; its `source_url`
-values are never expanded, so this command performs no webpage retrieval.
+After project initialization, import the pair with the user sources; the facts JSON is an ordinary source file and no webpage is retrieved:
```bash
-python3 ${SKILL_DIR}/scripts/project_manager.py import-sources \
- projects/<project_name> [<source_paths...>] \
- projects/<research_slug>.md projects/<research_slug>.facts.json
+python3 ${SKILL_DIR}/scripts/project_manager.py import-sources projects/<project_name> [<source_paths...>] projects/<research_slug>.md projects/<research_slug>.facts.json
```
-If planning later exposes a required factual gap, return to this stage and
-repair the research supplement plus facts JSON before continuing. Do not let
-Strategist or Quick consume a newly fetched claim without updating that pair.
-
-Only after normal web-image providers, ranked thumbnail pages, and materially
-different queries fail may an image owner with visual capability select one
-relevant `source_url` from the facts JSON and fetch that one webpage package:
-
-```bash
-python3 ${SKILL_DIR}/scripts/source_to_md/web_to_md.py "<source_url>" \
- -o <project_path>/sources/<source_slug>.md
-```
+If planning later exposes a required gap, return here and repair the pair before continuing; Strategist or Quick never consumes a newly fetched claim without updating it. The imported pair is the compact evidence-facing content authority, not a locked contract: Default's Strategist reads both files completely before confirmation; Quick's agent does the same before its content, design, and resource decisions.
-This writes the page Markdown, conversion profile, and companion
-`<source_slug>_files/` image package with `image_manifest.json`. Review that
-package, then copy only accepted image files into `<project_path>/images/`;
-leave every rejected or unused file in the source package. Fetch another page
-only after the current package has no usable image. Do not pass the URL to
-`project_manager.py import-sources`, which would promote every companion image
-into the runtime pool. Without vision, skip this fallback and retain
-`Needs-Manual`.
-
-The imported research pair remains the compact evidence-facing content
-authority, not a locked presentation contract. Default Generate has Strategist
-read both files completely before confirmation and use them with the imported
-source inventory to select the content, page roster, and image resource plan.
-Quick Generate has the current agent do the same before its active-context
-content, design, and resource decisions. A webpage Markdown enters the project
-only through the post-exhaustion single-page image fallback above.
+**Single-page image fallback**: only after normal web-image providers, ranked thumbnail pages, and materially different queries fail may an image owner with visual capability select one relevant `source_url` from the facts JSON and fetch that one page package with `web_to_md.py "<source_url>" -o <project_path>/sources/<source_slug>.md`, review the companion `<source_slug>_files/` package, and copy only accepted images into `<project_path>/images/` — never pass the URL to `import-sources`, which would promote every companion image into the pool. Fetch another page only after the current package has no usable image; without vision, retain `Needs-Manual`.
```markdown
## ✅ Topic Research Complete
- [x] Research execution: <isolated worker | main-context fallback>
- [x] Research supplement: `projects/<research_slug>.md` (N declared gaps covered)
- [x] Fact provenance: `projects/<research_slug>.facts.json` (N external facts)
-- [x] Artifact contract validated: `## Research Brief`, no Markdown source list, `ppt-master.fact-provenance.v1`, unique sequential IDs, and Markdown/JSON agreement
-- [x] Adopted webpage URLs: N unique `source_url` values in the facts JSON; no webpage automatically imported and no image copied into the runtime pool
-- [ ] **Next**: Default returns to [`generate-pptx`](../generate-pptx.md) Step 2; Quick returns to [`quick-generate`](../profiles/quick-generate.md) §2. Import the source artifacts plus research pair, then fully read the imported pair before planning or direct SVG authoring
+- [x] Artifact contract validated: `## Research Brief`, no Markdown source list, `ppt-master.fact-provenance.v1`, unique sequential IDs, Markdown/JSON agreement
+- [x] Adopted webpage URLs: N unique `source_url` values; no webpage auto-imported, no image copied into the runtime pool
+- [ ] **Next**: Default returns to [`generate-pptx`](../generate-pptx.md) Step 2; Quick returns to [`quick-generate`](../profiles/quick-generate.md) §2. Import the sources plus research pair, then fully read the imported pair before planning or direct SVG authoring
```
diff --git a/skills/ppt-master/workflows/stages/verify-charts.md b/skills/ppt-master/workflows/stages/verify-charts.md
index fd8feaaf..4ec1ca41 100644
--- a/skills/ppt-master/workflows/stages/verify-charts.md
+++ b/skills/ppt-master/workflows/stages/verify-charts.md
@@ -4,21 +4,14 @@ description: Conditional quality-gate stage for data-chart geometry and encoding
# Verify Charts Stage
-> Conditional Generate-PPTX quality stage. Run after a deck containing data charts has finished SVG generation, before post-processing & export. Catches coordinate and visual-encoding errors introduced while mapping source values into SVG marks.
-
-In Default Generate this stage is **context-independent**: it reads
-`design_spec.md` and the generated SVGs, then runs the calculator script. The
-lockless Quick branch is deliberately context-dependent: run it in the same
-active session from the page decisions just authored. If that context is lost,
-restart Quick rather than inventing a page plan from finished files.
+> Conditional Generate-PPTX quality stage. Run after a deck containing data charts has finished SVG generation and before post-processing/export; it catches coordinate and encoding errors introduced while mapping source values into SVG marks. Default runs it context-independently from `design_spec.md` plus the SVGs; the lockless Quick branch runs in the same active session from the page decisions just authored — if that context is lost, restart Quick rather than inventing a page plan from finished files.
## When to Run
-- The deck contains one or more data visualization charts where source values determine SVG geometry or visual encoding: bar lengths/heights, point positions, arc angles, polygon vertices, connector endpoints, bubble centers/radii, flow widths/paths, cell colors, or word sizes.
-- SVGs are generated to `<project_path>/svg_output/`. Default enters from its declared quality-gate order; Quick runs this stage before its one lockless final checker.
-- Post-processing (`finalize_svg.py`, `svg_to_pptx.py`) has **not yet** run.
+- The deck contains at least one chart where source values determine SVG geometry or encoding (bar lengths, point positions, arc angles, polygon vertices, connector endpoints, bubble centers/radii, flow widths, cell colors, word sizes).
+- SVGs exist in `<project_path>/svg_output/` and `finalize_svg.py` / `svg_to_pptx.py` have not run. Default enters from its quality-gate order; Quick runs it before its one lockless final checker.
-The calculator has direct CLI models for simple bars, lines/scatter, pie/donut, radar, and grid layouts. Composite/derived charts are **not automatically out of scope**: if their geometry reduces to repeated direct calculations, include them as `decomposable-calc`; if the calculator has no layout model but the SVG geometry is still data-driven, include them as `manual-verify` so they are not silently skipped.
+The calculator has direct models for bars, lines/scatter, pie/donut, radar, and grids. Composite charts are not out of scope: geometry that reduces to repeated direct calculations is `decomposable-calc`; data-driven geometry with no layout model is `manual-verify`, never silently skipped.
---
@@ -26,280 +19,60 @@ The calculator has direct CLI models for simple bars, lines/scatter, pie/donut,
| Active profile | Object-list authority |
|---|---|
-| Default Generate | `design_spec.md §IX` plus the legacy §VII fallback below |
-| Quick Generate | The still-active semantic object keys and page decisions that produced the SVGs, cross-checked against every `chart-plot-area` marker; no Design Spec, lock, or substitute planning artifact is created |
-
-For Default, read `<project_path>/design_spec.md` §IX Content Outline as the
-authoritative roster and include every semantic object key whose
-`Visualization` entry declares SVG geometry driven by data values. Cross-check
-§VII only to resolve a selected catalog reference; absence means no reusable
-reference was selected. For a legacy spec whose §IX predates object keys, one
-real §VII data-chart row may supply one legacy chart object for that page.
-
-For Quick, enumerate every promoted chart object's semantic key and page, then
-search `svg_output/` once for `chart-plot-area`. Compare objects and marker
-wrappers one-for-one. Add a missing scoped marker before continuing;
-investigate an unexpected marker instead of silently adding or dropping an
-object. Keep the list in active context only.
-
-Classify each included chart object into exactly one mode:
+| Default Generate | `design_spec.md §IX` — every semantic object key whose `Visualization` entry declares value-driven SVG geometry; §VII only resolves a selected catalog reference, and one real §VII data-chart row may supply one legacy object for a page whose §IX predates object keys |
+| Quick Generate | The still-active semantic object keys and page decisions, cross-checked one-for-one against every `chart-plot-area` marker found by one search of `svg_output/`; add a missing scoped marker, investigate an unexpected one, keep the list in active context only |
-Incidental microvisuals not promoted under the active profile authority are not
-inferred into this list. Default repairs that object's §IX `Visualization` first;
-Quick makes the promotion decision immediately in active context and updates
-the SVG marker before verification.
+Incidental microvisuals not promoted by the profile authority are not inferred into the list: Default repairs §IX first; Quick decides promotion in active context and updates the marker before verification. Never guess from SVG content when §IX declares no data-driven object.
| Mode | `charts_index.json` keys | Notes |
|------|--------------------------|-------|
-| `direct-calc` | `column_chart`, `horizontal_bar_chart`, `histogram_chart` | Use `calc bar`; add `--horizontal` for horizontal bars. Histogram bins use contiguous bars on the numeric x-axis. |
-| `direct-calc` | `line_chart`, `area_chart`, `scatter_chart` | Use `calc line`; area uses line output as the top boundary, then closes to `y_max`. |
-| `direct-calc` | `pie_chart`, `donut_chart` | Use `calc pie`; donut passes `--inner-radius`. |
-| `direct-calc` | `radar_chart` | Use `calc radar`; separate subcommand, not under `calc pie`. |
-| `decomposable-calc` | `stacked_bar_chart`, `stacked_area_chart`, `grouped_bar_chart`, `dumbbell_chart`, `pareto_chart`, `dual_axis_line_chart`, `bullet_chart`, `butterfly_chart`, `waterfall_chart`, `box_plot_chart`, `gantt_chart`, `bar_of_pie_chart`, `pie_of_pie_chart`, `stock_chart` | Verify by repeated direct calculations; see recipes below. |
-| `partial-calc` | `bubble_chart`, `matrix_2x2` | Use `calc line` for x/y-driven `cx/cy`; verify radius only when a size scale is explicit. |
-| `formula-verify` | `progress_bar_chart`, `gauge_chart`, `funnel_chart`, `sunburst_chart` | Record the formula and resulting length/angle/width in the receipt; sunburst verifies each ring's value-derived arc lengths and offsets. |
-| `manual-verify` | `sankey_chart`, `heatmap_chart`, `treemap_chart`, `word_cloud` | Data-driven geometry or encoding exists, but the current calculator has no complete layout model. Inspect and report; do not silently skip. |
+| `direct-calc` | `column_chart`, `horizontal_bar_chart`, `histogram_chart` | `calc bar`; `--horizontal` for horizontal bars; histogram bins are contiguous bars on the numeric x-axis |
+| `direct-calc` | `line_chart`, `area_chart`, `scatter_chart` | `calc line`; area uses the line output as the top boundary, then closes to `y_max` |
+| `direct-calc` | `pie_chart`, `donut_chart` | `calc pie`; donut passes `--inner-radius` |
+| `direct-calc` | `radar_chart` | `calc radar` (separate subcommand) |
+| `decomposable-calc` | `stacked_bar_chart`, `stacked_area_chart`, `grouped_bar_chart`, `dumbbell_chart`, `pareto_chart`, `dual_axis_line_chart`, `bullet_chart`, `butterfly_chart`, `waterfall_chart`, `box_plot_chart`, `gantt_chart`, `bar_of_pie_chart`, `pie_of_pie_chart`, `stock_chart` | Repeated direct calculations per the [verification recipes](../../scripts/docs/svg-pipeline.md#verification-recipes) |
+| `partial-calc` | `bubble_chart`, `matrix_2x2` | `calc line` for x/y-driven `cx/cy`; radius only with an explicit size scale |
+| `formula-verify` | `progress_bar_chart`, `gauge_chart`, `funnel_chart`, `sunburst_chart` | Quote the formula and resulting length/angle/width in the receipt |
+| `manual-verify` | `sankey_chart`, `heatmap_chart`, `treemap_chart`, `word_cloud` | Data-driven, but no layout model; inspect and report |
-**Family boundary**: this table covers every canonical key in
-`templates/charts/charts_index.json` exactly once. Do not put qualitative shape
-composition or a Table reference in the receipt merely because it contains
-shapes or numbers. Named quadrants are composed through
-[`executor-structure.md`](../../references/executor-structure.md);
-`chart/matrix_2x2` is reserved for plotted x/y and optional radius data. Every
-embedded data chart is its own keyed §IX `Visualization` object.
-
-Resulting list:
+**Family boundary**: this table covers every canonical `charts_index.json` key exactly once. Qualitative shape composition and Table references never enter the receipt merely because they contain shapes or numbers; named quadrants are composed through [`executor-structure.md`](../../references/executor-structure.md), and `chart/matrix_2x2` is reserved for plotted x/y data. Every embedded data chart is its own keyed §IX object.
```
P03 market-share 03_market_share.svg type=bar mode=direct-calc
-P03 margin-trend 03_market_share.svg type=line mode=direct-calc
-P11 share-split 11_share_split.svg type=pie mode=direct-calc
P15 pareto-causes 15_pareto.svg type=pareto mode=decomposable-calc
```
-In Default, if §VII is absent, continue from §IX; this is the normal state when
-all chart objects use custom structures. Do not guess from SVG content when §IX
-declares no data-driven object. In Quick, marker search is only the required
-cross-check, never a replacement for active authoring decisions.
-
-If the filtered list is empty, output `verify-charts: active profile declares no data-driven chart objects, nothing to verify` and stop.
+If the list is empty, output `verify-charts: active profile declares no data-driven chart objects, nothing to verify` and stop.
---
## Step 2: Per object — read its SVG scope, calculate, compare, update
-For each object in the Step 1 list:
-
-1. Read `<project_path>/svg_output/<page>.svg`.
-2. Locate `<g id="<object-key>">` and its one plot-area marker. The marker
- payload starts `chart-plot-area: object=<object-key> |` and belongs inside
- `<g id="<object-key>-chartArea">`. Accept a legacy unscoped marker and
- `id="chartArea"` only when the page has exactly one verified chart. A
- multi-chart page may not mix scoped and unscoped markers. If a marker is
- missing, derive it from that object's axes or center/radius and add the
- scoped marker before continuing.
-3. Read only that object's data series and label/value elements.
-4. **Read axis tick labels for every axis-based chart inside the same object scope.** Locate the `<text>` elements along the value axis — X-axis labels for horizontal bars, Y-axis labels for vertical bars, and Y-axis labels for line-like charts. Extract the first and last tick values to determine the axis range (e.g. `0%` to `120%` → range `0,120`). Pass this range as `--value-range`, `--y-range`, or `--x-range` as appropriate. Use the attached `--*-range=min,max` form, which also keeps a negative minimum from being parsed as another option. Radar uses `--max-value` instead of a range: read the outermost ring's tick value and pass it as `--max-value`. If the SVG has no explicit tick labels (data labels only, no grid), omit the range and let the calculator auto-normalize — but flag the receipt as `scale=auto (no ticks)`.
-
- **Local vs absolute coordinates.** Many chart templates wrap chart content in `<g transform="translate(cx, cy)">` or similar, so child `<circle>`/`<polygon>`/`<rect>` coords are relative to that origin (e.g. radar polygon at `0,-198`, donut paths starting from `0,0` inside a translated `<g>`, dumbbell circles at `cy="0"` inside a per-row translated `<g>`). The calculator outputs **absolute** SVG coordinates. Before comparing, either add the wrapping translate's offset to the SVG coords or subtract it from the calculator's output — pick one direction and apply it consistently.
-5. Run the matching calculator command:
+1. Read `<project_path>/svg_output/<page>.svg`; locate `<g id="<object-key>">` and its one plot-area marker (`chart-plot-area: object=<object-key> | …` inside `<g id="<object-key>-chartArea">`). A legacy unscoped marker with `id="chartArea"` is accepted only when the page has exactly one verified chart; a multi-chart page never mixes scoped and unscoped markers. Derive and add a missing scoped marker from the axes or center/radius before continuing.
+2. Read only that object's data series and label/value elements.
+3. **Read axis tick labels for every axis-based chart** — X-axis labels for horizontal bars, Y-axis labels for vertical bars and line-like charts. The first and last tick values give the axis range; pass it as attached `--value-range=min,max` / `--y-range=…` / `--x-range=…` (the attached form also protects a negative minimum). Radar takes `--max-value` from the outermost ring. With no tick labels, omit the range, let the calculator auto-normalize, and flag the receipt `scale=auto (no ticks)`.
+4. **Local vs absolute**: content inside `<g transform="translate(cx, cy)">` has relative coordinates; the calculator outputs absolute ones. Add the translate to the SVG values or subtract it from the calculator output — one direction, consistently.
+5. Run the matching command (see the [calculator documentation](../../scripts/docs/svg-pipeline.md#svg_position_calculatorpy) and recipes for decomposable, partial, formula, and manual modes):
```bash
- # column_chart / horizontal_bar_chart (add --horizontal for the latter)
- # IMPORTANT: always pass --value-range from axis tick labels (step 4)
- python3 skills/ppt-master/scripts/svg_position_calculator.py calc bar \
- --data "Label1:Value1,Label2:Value2" --area "x_min,y_min,x_max,y_max" \
- --bar-width 120 --value-range=0,axis_max
-
- # line_chart / area_chart / scatter_chart — area uses line output as the top boundary, then closes to y_max
- python3 skills/ppt-master/scripts/svg_position_calculator.py calc line \
- --data "x1:y1,x2:y2,..." --area "x_min,y_min,x_max,y_max" --y-range=0,max
-
- # pie_chart — default start angle is -90 (12 o'clock); pass --start-angle only if the SVG starts elsewhere
- python3 skills/ppt-master/scripts/svg_position_calculator.py calc pie \
- --data "Slice1:Value1,Slice2:Value2" --center "cx,cy" --radius 200 --start-angle -90
-
- # donut_chart (pie with inner-radius)
- python3 skills/ppt-master/scripts/svg_position_calculator.py calc pie \
- --data "Slice1:Value1,Slice2:Value2" --center "cx,cy" --radius 200 --inner-radius 120 --start-angle -90
-
- # radar_chart (separate subcommand) — pass --max-value from the outermost ring tick
- python3 skills/ppt-master/scripts/svg_position_calculator.py calc radar \
- --data "Dim1:Value1,Dim2:Value2,Dim3:Value3" --center "cx,cy" --radius 200 --max-value 100
+ python3 skills/ppt-master/scripts/svg_position_calculator.py calc bar --data "L1:V1,L2:V2" --area "x_min,y_min,x_max,y_max" --bar-width 120 --value-range=0,axis_max
+ python3 skills/ppt-master/scripts/svg_position_calculator.py calc line --data "x1:y1,x2:y2" --area "x_min,y_min,x_max,y_max" --y-range=0,max
+ python3 skills/ppt-master/scripts/svg_position_calculator.py calc pie --data "S1:V1,S2:V2" --center "cx,cy" --radius 200 [--inner-radius 120] --start-angle -90
+ python3 skills/ppt-master/scripts/svg_position_calculator.py calc radar --data "D1:V1,D2:V2,D3:V3" --center "cx,cy" --radius 200 --max-value 100
```
- Area chart fill path closes to the bottom edge of the plot area:
-
- ```svg
- M first_x,first_y ... L last_x,last_y L last_x,y_max L first_x,y_max Z
- ```
-
-6. **Scale-aware comparison.** Compare calculator output against the SVG's existing coordinates. Before declaring a mismatch, verify that every calculator invocation used the same axis range, plot area, center/radius, start angle, or size scale that the SVG visually declares. For `calc bar`, the output header must show `Value scale: axis ticks (...)` when the SVG has explicit ticks; if it shows `auto (max*1.1)`, go back to step 4 and re-run with the correct `--value-range`. **Do NOT update the SVG with mismatched-scale output.** Only update SVG attributes when the scale is confirmed to match and coordinates genuinely differ. Update by hand (do NOT use regex / bulk replacement — coordinates are positional and easy to swap incorrectly).
-
-After updating any page, follow the active profile's checker order. Default
-reruns its quality checker to confirm nothing broke:
-
-```bash
-python3 skills/ppt-master/scripts/svg_quality_checker.py <project_path> --canonical-authoring --stage final --json
-```
-
-This rerun writes the current `final` report required by Step 7.3.
-
-Quick completes every chart comparison/repair first, then returns to
-`quick-generate.md` §4 and runs its one lockless final checker. Do not insert a
-checker call between Quick chart pages.
-
----
-
-## Stacked recipe
-
-`stacked_bar_chart` and `stacked_area_chart` are not single-call but reduce cleanly to repeated calls on existing primitives. The operator already had to compute cumulative values to draw the SVG — verify-charts reuses them.
-
-**Stacked bar** — for N stacked series on the same x categories, run `calc bar` N times. Pass each segment's **height** as the data value, and shift `--area`'s `y_max` down by the sum of all lower segments for that category. Compare each segment's `(x, y, width, height)` against the SVG.
-
-```bash
-# Example: two-series stack at category "Q1" with bottom=30, top=20, plot area y from 100 to 500
-# Run 1 — bottom segment (origin = baseline)
-python3 skills/ppt-master/scripts/svg_position_calculator.py calc bar \
- --data "Q1:30,Q2:..." --area "x_min,100,x_max,500" \
- --bar-width 80 --value-range=0,axis_max
-# Run 2 — top segment (origin shifted up by bottom segment's height in pixels)
-python3 skills/ppt-master/scripts/svg_position_calculator.py calc bar \
- --data "Q1:20,Q2:..." --area "x_min,100,x_max,<500 - bottom_height_px>" \
- --bar-width 80 --value-range=0,axis_max
-```
-
-**Stacked area** — for N stacked series, run `calc line` N times on **cumulative** y-values (series 1 raw; series 2 = series1+series2; …). Each call yields the top boundary of one band. Each band's SVG path closes to the **previous** band's top boundary (not to `y_max`).
-
-If a stack page's segment positions don't reduce to this recipe (e.g., negative segments, percent-stacked with non-100 totals), mark it `manual-verify` in the receipt and inspect by hand — do not silently pass.
-
----
-
-## Decomposable recipes
-
-Use these recipes for `decomposable-calc` and `partial-calc` pages. Each recipe must produce a receipt line; if a page cannot be reduced cleanly, mark `manual-verify` with the reason instead of dropping it.
-
-**Dumbbell chart** — for before/after or two-state values across categories. The two endpoints are **points**, not bar ends — `calc bar --horizontal` always anchors at `x_min`, which only matches the right endpoint. Use `calc line` × 2 instead, treating category index as the y axis:
-
-1. Number categories `0.5, 1.5, …, N-0.5` so each row's y lands on its band center; set `--y-range=0,N`. The same convention applies to vertical dumbbells with the axes swapped.
-2. Set `--x-range` to the shared value-axis range read from ticks.
-3. Run `calc line` once per endpoint series with identical `--area`, `--x-range`, `--y-range`. Each output `(SVG_X, SVG_Y)` is the matching endpoint circle's `(cx, cy)`.
-4. Compare both endpoint circles and the connector line (`x1=cx_left, x2=cx_right, y1=y2=cy`) against the two calculated point sets.
-
-```bash
-# Horizontal dumbbell, 3 categories, value axis 0–100, plot area (100,100)–(700,460).
-# Encode category index as the y value: row 1 → 0.5, row 2 → 1.5, row 3 → 2.5.
-python3 skills/ppt-master/scripts/svg_position_calculator.py calc line \
- --data "42:0.5,55:1.5,37:2.5" --area "100,100,700,460" \
- --x-range=0,100 --y-range=0,3
-python3 skills/ppt-master/scripts/svg_position_calculator.py calc line \
- --data "68:0.5,71:1.5,49:2.5" --area "100,100,700,460" \
- --x-range=0,100 --y-range=0,3
-```
-
-**Pareto chart** — split into descending bars plus cumulative line:
-
-1. Run `calc bar` on the descending category values with the bar axis range from ticks.
-2. Precompute cumulative percentages in category order.
-3. Run `calc line` on `0.5:cum1,1.5:cum2,...,N-0.5:cumN` with `--x-range=0,N`, the right-side percentage axis as `--y-range` (usually `--y-range=0,100`), and the same `--area` as the bars. The `n - 0.5` offset puts each cumulative point on the matching bar's center; using `1,2,…,N` shifts the polyline left by half a bar width.
-4. Compare bar rects, cumulative line path, and cumulative markers separately.
-
-**Dual-axis line chart** — split by axis:
-
-1. Read the left and right Y-axis tick ranges independently.
-2. Run `calc line` once per series using its own `--y-range`; use the same `--x-range` and plot area for both.
-3. Compare each series' polyline/path points against the matching axis scale. Never use the left-axis scale for the right-axis series or vice versa.
-
-**Bullet chart** — performance bands + actual bar + target marker, all anchored at the same `x_min`. The bands occupy the **same** y row (they stack visually by overlapping, not by category), so run `calc bar --horizontal` once **per band** with a single data point — multi-category calls would spread y across rows:
-
-1. Read the value-axis range from the band edges (the widest band's right edge = axis max).
-2. For each band, run `calc bar --horizontal --data "<band_name>:<right_edge_value>" --area "<x_min>,<band_y>,<x_max>,<band_y+band_height>" --bar-width <band_height>`. Each call returns one rect at the shared `(x_min, band_y)` with the value-mapped width. Compare against the band rect.
-3. Run `calc bar --horizontal` with a single data point for the actual value, using the actual bar's inset area (`y` and `bar-width` shrunk so the bands are visible). Compare against the actual rect.
-4. The target marker is a `<line>` at `x = x_min + target/axis_max × area_width`, spanning the full band height. Compute by hand and compare.
-
-**Butterfly chart** — mirrored horizontal bars around a vertical center line at `cx`:
-
-1. Read the value-axis range and the center-line `cx` from the SVG.
-2. Run `calc bar --horizontal` once per side using a plot area whose `x_min = cx` and `x_max = cx + side_width`. The right-side bars' `x` and `width` map directly.
-3. For the left side, reuse the same calc output and mirror: each left bar's `x = cx - width`, `width` unchanged. Compare against the left rects.
-4. Category `y` is shared across both sides — verify left and right rows align on the same `y + height/2`.
-
-**Grouped bar chart** — N series sharing the same x categories, side-by-side instead of stacked:
-
-1. Read the value-axis range and the plot area.
-2. Compute the inner-group spacing: if there are `N` series and the visual group spans width `W` per category, each series-bar's width is `W/N` and its x offset within the group is `(i - 1) × W/N`. Read these from the SVG (the first category's bars give you both).
-3. Run `calc bar` once per series with the **same** `--area` and `--value-range` but with each call's `--bar-width` set to the inner width. The calc's per-category center X gives the **group** center; each series-bar's actual `x = group_center - W/2 + (i-1) × W/N`. Compare against the SVG.
-
-**Box plot chart** — Q1/Q3 box + median line + whiskers. All five quantities are y-values on the same axis:
-
-1. Read the y-axis range and plot area. For each category, the five values are min / Q1 / median / Q3 / max.
-2. Run `calc bar` once treating each category's box (Q3 − Q1) as a synthetic "stacked" segment with the area's `y_max` shifted to `y_axis_top - Q1 × pixels_per_unit` (the Q1 baseline). The output's `y, height` should match the box rect.
-3. Median y = `y_axis_top + (axis_max - median) × pixels_per_unit`. Whisker endpoints (min, max) follow the same formula. Compare each against the SVG's `<line>` y1/y2 and `<rect>` y/height.
-
-**Gantt chart** — task bars where each bar's `x` and `x + width` are the start and end positions on a timeline axis:
-
-This remains a Chart even when the source used a physical PowerPoint table for
-the row grid. A qualitative stage/lane plan whose positions are not derived
-from dates or durations uses [`executor-structure.md`](../../references/executor-structure.md)
-and does not enter this verification stage.
-
-1. Read the timeline tick positions (the header row's x coordinates per date unit). Pixels-per-unit = `(x_unit_n - x_unit_1) / (n - 1)`.
-2. Run `calc line` once over `start_index:row_y` per task — output `SVG_X` gives the bar's `x`. Run it again over `end_index:row_y` — output `SVG_X` gives `x + width`. Subtract for width.
-3. Compare each task rect's `(x, width)` against the calculated start and end. Row y can be read directly (categories are not value-driven).
-
-**Waterfall chart** — floating bars connected by running totals. Each bar's top and bottom edge correspond to two points on the same value axis (`cum_before`, `cum_after`):
-
-1. Read the y-axis tick range and the plot area; compute running totals in category order (start with `cum[0] = base_value`, then `cum[i] = cum[i-1] + delta[i]` for increase, `cum[i-1] - delta[i]` for decrease, reset to delta for totals).
-2. Build two virtual series: `top[i] = max(cum_before, cum_after)`, `bot[i] = min(cum_before, cum_after)`. Run `calc bar` twice on these with identical `--area`, `--bar-width`, `--value-range`. The `top` run's `Y` is the bar's `y`; `height = bot.Y - top.Y` for that index.
-3. Compare each waterfall rect's `(x, y, width, height)` against the calculated pair. Connector lines should run from `(x + width, top_or_bot[i].Y)` to `(x_next, top_or_bot[i+1].Y)` at the matching shared cumulative value.
-4. Total bars (full-height start/end) use `bot = 0` and the calc reduces to the standard `calc bar` recipe.
-
-**Bubble chart / plotted 2×2 matrix** — partial calculator support:
-
-1. Use `calc line` to verify bubble centers (`cx/cy`) from the X/Y values and axis ticks.
-2. For `matrix_2x2`, verify that the axis midpoint matches the quadrant split. If the visible axes say only Low/High, read the explicit numeric mapping from the active §IX decision or SVG comment; without one, record `xy=manual (scale missing)` instead of inventing a range.
-3. Verify radius only if `design_spec.md`, the Quick active-context decision, or SVG comments declare a size scale such as `radius = sqrt(value) * k` or explicit min/max radius mapping. `spec_lock.md` carries only the primary family/key reference and is not a size-scale authority.
-4. If the size scale is missing, record `radius=manual (scale missing)` and inspect relative ordering by hand.
-
-**Bar-of-pie / pie-of-pie** — decompose the primary and expanded views:
-
-1. Replace the expanded tail in the primary data with one aggregate tail value, then run `calc pie` for the main pie.
-2. For `pie_of_pie_chart`, run `calc pie` again on the tail values at the secondary center/radius. For `bar_of_pie_chart`, verify each stacked detail height as `tail_value / sum(tail_values) × detail_height` and confirm the segments fill the declared detail bar without gaps or overlap.
-3. Verify that the aggregate tail slice equals the sum of the expanded values and that connector endpoints touch the two declared plot regions.
-
-**Stock chart** — decompose each OHLC observation into four y-values:
-
-1. Read the shared price-axis range and ordered date positions.
-2. Run `calc line` for open, high, low, and close using the same plot area and ranges. For each date, the wick spans `high_y` to `low_y`; the body spans `min(open_y, close_y)` to `max(open_y, close_y)`.
-3. Verify the body color/direction against `close >= open`, and verify that every body stays within its wick.
-
-**Progress bar / gauge / funnel / sunburst — formula-verify** (no calc call needed):
-
-- Progress bar: `fill_width = value / max × track_width`. Read `value`, `max`, and `track_width` from the SVG; compute and compare against the fill rect's `width`.
-- Gauge: `needle_angle = start_angle + value / max × sweep_angle`. Read `start_angle` and `sweep_angle` from the SVG's arc path (e.g. half-circle `start_angle=-180`, `sweep_angle=180`). Compare against the needle's `transform="rotate(α ...)"` value (the most common form), or against endpoint `(cx + L·cos α, cy + L·sin α)` when the needle is drawn as an explicit line/path.
-- Funnel: each trapezoid's `top_width = prev.bottom_width`, `bottom_width = top_width × next_value / curr_value`. Verify by walking the segments: for segment `i`, `(top_left_x, top_right_x) → bottom_x_inset = (top_width - bottom_width) / 2`. The first segment's top width comes from the design's outer frame.
-- Sunburst: for each ring, `circumference = 2πr` and each node's arc length is `node_value / root_total × circumference`; offsets follow cumulative sibling values plus any explicitly declared separator gap. Verify that child arcs remain inside their parent span and that sibling values sum to the parent.
-- Receipt should quote the formula and resulting value (e.g. `formula=value/max×track_width=0.92×700=644px`, or `formula=600×850/1000=510 bottom width`).
-
-**Sankey / heatmap / treemap / word cloud — manual verification:**
+6. **Scale-aware comparison**: before declaring a mismatch, confirm every invocation used the axis range, plot area, center/radius, start angle, or size scale the SVG visually declares — for `calc bar` the header must show `Value scale: axis ticks (...)` when the SVG has ticks; `auto (max*1.1)` means go back to step 3. Never update the SVG with mismatched-scale output. When the scale matches and coordinates genuinely differ, update by hand — no regex or bulk replacement.
-- Sankey: no layout model for node stacking, link routing, or flow-width normalization. Verify that link widths are proportional to flow values and that node-side totals match (in = out).
-- Heatmap: cell positions are a fixed grid (not value-driven); the value-to-color binning is what's data-driven. Verify that the color of each cell falls in the bin matching the cell's number, and that high/low extremes use the legend's high/low colors.
-- Treemap: rectangle areas reflect value proportions but the recursive squarify layout has no calculator equivalent. Verify each rect's `width × height ≈ total_area × value / sum(values)` for top-level cells, and that nested cells sum to their parent.
-- Word cloud: verify that keyword font sizes are monotonic with their declared weights (or match the declared weight bins), then inspect the final text bounds for overlap and clipping. Position is layout-driven; do not invent a coordinate formula.
+After updating any page, follow the profile's checker order. Default reruns `svg_quality_checker.py <project_path> --canonical-authoring --stage final --json`, which writes the current `final` report Step 7.3 requires. Quick completes every chart comparison/repair first, then returns to `quick-generate.md` §4 for its one lockless final checker — no checker call between chart pages.
---
## Step 3: Per-object receipt
-Output one line per chart object from the Step 1 list. Include its semantic key;
-receipt count MUST equal Step 1
-list length — that is the gate-closing evidence. Quick does not persist these
-lines as a generation plan or resume record.
+One line per Step 1 object, including its semantic key; receipt count MUST equal the list length — that is the gate-closing evidence. Quick does not persist these lines.
```
verify-charts: 03_market_share.svg | object=market-share | type=bar | mode=direct-calc | scale=0-100 (from ticks) | calc=ran | svg=updated
-verify-charts: 03_market_share.svg | object=margin-trend | type=line | mode=direct-calc | scale=0-120 (from ticks) | calc=ran | svg=unchanged
verify-charts: 11_share_split.svg | object=share-split | type=pie | mode=direct-calc | scale=N/A | calc=ran | svg=updated | marker=added
verify-charts: 14_revenue_mix.svg | object=revenue-mix | type=stacked-bar | mode=decomposable-calc | scale=0-200 (from ticks) | calc=ran×3 | svg=updated
verify-charts: 18_market_bubbles.svg | object=market-bubbles | type=bubble | mode=partial-calc | xy=ran | radius=manual (scale missing) | svg=unchanged
@@ -311,7 +84,4 @@ verify-charts: 19_flow.svg | object=flow | type=sankey | mode=manual-verify | li
## After verification
-Default continues with [`generate-pptx`](../generate-pptx.md) Step 7. Quick
-returns to [`quick-generate`](../profiles/quick-generate.md) §4 for its one final
-checker and direct export. Those authorities own the remaining serial commands,
-gates, and success criteria.
+Default continues with [`generate-pptx`](../generate-pptx.md) Step 7; Quick returns to [`quick-generate`](../profiles/quick-generate.md) §4 for its final checker and direct export.
diff --git a/skills/ppt-master/workflows/stages/web-image-review.md b/skills/ppt-master/workflows/stages/web-image-review.md
index de9a6616..f00261f6 100644
--- a/skills/ppt-master/workflows/stages/web-image-review.md
+++ b/skills/ppt-master/workflows/stages/web-image-review.md
@@ -4,71 +4,45 @@ description: Conditional isolated multimodal review of bounded web-image thumbna
# Web Image Review Stage
-> Supporting Generate stage for choosing from thumbnail pages already prepared
-> by the web-image acquisition path. It reviews pixels only: it never searches,
-> downloads, changes the locked image intent, or writes project artifacts.
+> Supporting Generate stage for choosing from thumbnail pages already prepared by the web-image acquisition path. It reviews pixels only: it never searches, downloads, changes the locked image intent, or writes project artifacts.
## When to Run
+After `--save-candidates` has produced `Needs-Selection` rows and before any `--promote` command.
+
| Review capability | Action |
|---|---|
-| An isolated worker can inspect the declared local images | Dispatch exactly one reviewer for all pending sheets in the current acquisition batch |
+| An isolated worker can inspect the declared local images | Dispatch exactly one reviewer for all pending sheets in the current batch; reuse it for later candidate pages of the same run when the host supports follow-up messages — never one reviewer per row |
| Only the active image owner can inspect images | Read this stage and review the same batch locally |
-| No available context can inspect images | Skip this stage and use the strict metadata-only acquisition path |
-
-Run after `--save-candidates` has produced `Needs-Selection` rows and before any
-`--promote` command. When the host supports follow-up messages, reuse the same
-reviewer for later candidate pages in that acquisition run; never dispatch one
-reviewer per resource row.
+| No available context can inspect images | Skip; use the strict metadata-only acquisition path |
---
## Execution Context
-**Default — isolate thumbnail pixels when available**: The active image owner
-retains query, search, pagination, promotion, status, and provenance ownership.
-Supply the reviewer only this stage's absolute path and these per-row records:
-
-| Input | Required value |
-|---|---|
-| Row identity | Resource filename or stable batch-row identifier |
-| Acceptance intent | Exact locked `Reference` and `Crop Policy` |
-| Candidate state | Current page, `has_more_candidates`, and `next_candidate_page` when present |
-| Local evidence | Absolute `review_sheet.jpg` and `candidates.json` paths |
-
-The isolated reviewer reads this file completely, then inspects only the
-declared sidecars and review images. It does not read `image-base.md`,
-`image-searcher.md`, the Design Spec, the lock, or source files. It runs no
-network request, command, or project write. If any declared path is unreadable
-or image inspection is unavailable, return `blocked` with the exact reason.
+The active image owner keeps query, search, pagination, promotion, status, and provenance ownership and supplies the reviewer only this stage's absolute path plus, per row: the resource filename or stable row identifier; the exact locked `Reference` and `Crop Policy`; current page, `has_more_candidates`, and `next_candidate_page`; absolute `review_sheet.jpg` and `candidates.json` paths. The reviewer reads this file completely, inspects only the declared sidecars and images, reads no other project or prompt files, runs no network request, command, or write, and returns `blocked` with the exact reason when a path is unreadable or image inspection is unavailable.
---
## Review Contract
-Apply the gates in order for every row:
-
| Order | Gate |
|---:|---|
-| 1 | Reject a candidate unless its `license_tier` is `no-attribution` or `attribution-required`; also reject unreadable previews or known dimensions that cannot serve the planned placement |
-| 2 | Confirm the exact subject or identity; `visual-verification-required` passes only when the pixels establish the missing identity evidence |
+| 1 | Reject unless `license_tier` is `no-attribution` or `attribution-required`; reject unreadable previews or known dimensions that cannot serve the placement |
+| 2 | Confirm the exact subject or identity; `visual-verification-required` passes only when the pixels establish the missing evidence |
| 3 | Check orientation, focal placement, crop safety, and usable quiet region against the locked intent |
| 4 | Check the requested view, action, and mood |
| 5 | Among passing candidates, prefer lower expected crop loss and higher usable resolution, then no-attribution |
-**Mandatory — bounded detail inspection**: Triage with `review_sheet.jpg`.
-Open an individual `review/candidate_NN.jpg` only when exact identity or a fine
-detail cannot be resolved from the sheet; never bulk-open every candidate.
+**Mandatory — bounded detail inspection**: triage with `review_sheet.jpg`; open an individual `review/candidate_NN.jpg` only when exact identity or a fine detail cannot be resolved from the sheet, never bulk-open every candidate.
-**Hard rule — no least-bad promotion**: Select only a candidate that passes all
-applicable gates. When none passes, return `no-pass`; do not weaken the locked
-Reference or Crop Policy.
+**Hard rule — no least-bad promotion**: select only a candidate that passes every gate; otherwise return `no-pass` without weakening the locked Reference or Crop Policy.
---
## Receipt and Hand-off
-Return one compact table and no embedded images:
+Return one compact table, no embedded images, under 200 words:
```markdown
| row | decision | candidate | reason | next |
@@ -76,12 +50,4 @@ Return one compact table and no embedded images:
| <id> | selected / no-pass / blocked | candidate_NN.jpg / — | <short evidence> | promote / next-page / pool-exhausted / repair-input |
```
-For `selected`, name exactly one candidate from that row's current page. For
-`no-pass`, use `next-page` when `has_more_candidates` is true; otherwise use
-`pool-exhausted`. Keep the entire chat receipt under 200 words.
-
-The active image owner validates every selected filename against
-`candidates.json`, runs `--promote`, and verifies the downloaded original's
-readable dimensions and provenance. A no-pass row advances to the next ranked
-page before query replacement. An invalid receipt returns to the same reviewer
-for correction; it never authorizes an arbitrary promotion.
+`selected` names exactly one candidate from the row's current page; `no-pass` uses `next-page` when `has_more_candidates` is true, otherwise `pool-exhausted`. The image owner validates every selected filename against `candidates.json`, runs `--promote`, and verifies the downloaded original's dimensions and provenance; a no-pass row advances to the next ranked page before query replacement; an invalid receipt returns to the same reviewer and never authorizes an arbitrary promotion.