@event4u/agent-config 16.4.0 → 16.5.0

package/dist/agent-src/skills/iconography/SKILL.md

@@ -1,7 +1,7 @@
 ---
 model_tier: inherit
 name: iconography
-description: "Resolve an icon request to a concrete Iconify name and emit the embedding for the project's stack. Use when adding icons, picking an icon set, or wiring Lucide/Heroicons/Phosphor/Tabler."
+description: "Resolve an icon request to an Iconify name and emit the stack's embedding. Use when adding icons, picking an icon set, or wiring Lucide/Heroicons/Phosphor/Tabler."
 domain: product
 personas: []
 workspaces:
@@ -102,7 +102,9 @@ Inspect stage of the
 - **No hand-rolled icons when a set exists.** If the project has an icon library
   or brand mark, use it — do not hand-author a one-off SVG that drifts from the
   system. Hand-rolling is for a genuinely missing glyph, and then it matches the
-  set's grid + stroke.
+  set's grid + stroke — read the grid, stroke and padding off the set's OWN
+  SVGs and author it under [`svg-authoring`](../svg-authoring/SKILL.md), which
+  checks the result instead of trusting that it matched.
 - **Flag substitutions when the exact asset is absent.** When the needed icon or
   brand mark does not exist in the set, pick the nearest and **state the
   substitution** ("no exact 'sync' glyph in Heroicons; used `arrow-path`") rather

package/dist/agent-src/skills/image-provider-routing/SKILL.md

@@ -1,7 +1,7 @@
 ---
 model_tier: inherit
 name: image-provider-routing
-description: "Select the right image-generation provider from job shape — text-in-image to Ideogram, photoreal to Flux, vector/logo to Recraft, general to Gemini/GPT."
+description: "Pick the image provider from job shape — text-in-image to Ideogram, photoreal to Flux, illustrative vector to Recraft, general to Gemini/GPT."
 domain: product
 personas: []
 workspaces:
@@ -37,13 +37,24 @@ promotion per `provider-lifecycle-discipline`.
 |---|---|---|
 | Text-in-image (logo, banner, typographic art) | **Ideogram** | Best glyph rendering; raster models garble text |
 | Photoreal (product shot, portrait, scene) | **Flux** | Photorealism specialist; routed via fal/Replicate |
-| Vector / SVG logo or icon | **Recraft** | Produces genuine `<path>` SVG; raster cannot |
+| Icon the set lacks | `iconography` first, then [`svg-authoring`](../svg-authoring/SKILL.md) | The incumbent set wins; a missing glyph is hand-authored against its grid and checked — no provider involved |
+| Simple geometric mark | [`svg-authoring`](../svg-authoring/SKILL.md) | A `rect`/`circle`/`path` mark is cheaper and more editable hand-authored than generated, and it ends in a file rather than a plan |
+| Complex illustrative vector art | **Recraft** | The only job shape left for a vector provider. State the adapter's lifecycle in the answer: `experimental — scaffold tier, dry-run plumbing only`, so the caller knows no asset is produced |
 | General art / edit / multimodal | **Gemini-image** or **GPT Image 2** | Broad capability; natural-language prompts |
 | Budget-conscious 4K upscale | Flux via Replicate | Cost-competitive at high resolution |
 
-Decision order: text-in-image → Ideogram; must-be-vector → Recraft; photoreal → Flux;
-everything else → Gemini-image (default) or GPT Image 2 (when OpenAI key available
-and editing an existing image).
+Decision order: an icon → the incumbent set, then `svg-authoring` for a missing
+glyph; a simple geometric mark → `svg-authoring`; text-in-image → Ideogram;
+complex illustrative vector art → Recraft, with its scaffold-tier lifecycle
+stated; photoreal → Flux; everything else → Gemini-image (default) or GPT
+Image 2 (when an OpenAI key is available and an existing image is being edited).
+
+The split exists because the single "Vector / SVG logo or icon" row sent every
+icon and every geometric mark to an adapter whose header reads `experimental —
+scaffold tier. dry-run plumbing only` and whose live calls exit at
+the adapter's own live-call guard. The routed path ended in a plan;
+the icon floor meanwhile sent icons to the set. Neither produced an asset for
+the one case that needs one — a glyph the set does not have.
 
 ## Procedure
 

package/dist/agent-src/skills/logo-generation/SKILL.md

@@ -1,7 +1,7 @@
 ---
 model_tier: inherit
 name: logo-generation
-description: "Generate a logo or brand mark — structured prompt + provider routing, with a true-vector path (vector-native provider or LLM-authored SVG). Use for logo or brand mark generation."
+description: "Generate a logo or brand mark — structured prompt, provider routing, and a true-vector path. Use for logo or brand mark generation."
 domain: product
 personas:
   - design-director
@@ -40,9 +40,10 @@ governance. All adapters are scaffold-tier (dry-run) until promoted to `stable`.
    icon mark / combination), colour palette, do/don't constraints (e.g. "no gradients",
    "must be legible at 16 px").
 2. **Choose the path** — raster concept (text-in-mark → Ideogram for legible type)
-   vs. **true vector** (vector-native provider emitting `<path>` SVG for editable
-   marks, or LLM-authored SVG for simple geometric marks). Raster output is a
-   concept only — not a shippable logo asset.
+   vs. **true vector** (a vector-native provider for editable marks, or a
+   hand-authored one for simple geometric marks — authored under
+   [`svg-authoring`](../svg-authoring/SKILL.md), never free-hand). Raster output
+   is a concept only — not a shippable logo asset.
 3. **Inject brand tokens when a brand layer is present** (`pack-brand`) — pull the
    registered palette, typeface, and spacing tokens. When no brand layer exists,
    use the brief's palette and type choices directly.
@@ -51,8 +52,11 @@ governance. All adapters are scaffold-tier (dry-run) until promoted to `stable`.
    provider-specific grammar (text-literal first for Ideogram, `style: vector` param
    for a vector-native provider, direct SVG authoring for simple geometric shapes).
 5. **Dry-run + validate** — invoke the adapter (scaffold-tier; returns a dry-run
-   plan). If the vector path is taken, validate that the output contains `<path>`
-   elements before treating it as an editable mark.
+   plan). If the vector path is taken, the vector verdict comes from
+   `lint_svg_asset`'s vector-honesty family plus the render witness, not from
+   counting `<path>` elements: a raster embedded beside one dummy path passes
+   that count and is not a vector, and a mark built from `rect`/`circle` fails
+   it and is one. See [`svg-authoring`](../svg-authoring/SKILL.md).
 6. **Rights check** — never reproduce a mark that resembles an existing trademarked
    logo. Run [`image-likeness-and-rights`](../../rules/image-likeness-and-rights.md)
    when the brief names a brand, references a known mark style, or targets a
@@ -78,8 +82,8 @@ governance. All adapters are scaffold-tier (dry-run) until promoted to `stable`.
   is `stable` misleads the caller.
 
 **Good example:** Brief for a wordmark → route to a vector-native provider with
-`style: vector`, validate `<path>` elements in output, note "experimental —
-dry-run plan only."
+`style: vector`, run `lint_svg_asset` over the output and confirm it carries no
+embedded raster, note "experimental — dry-run plan only."
 
 **Bad example:** Routing a logo brief to a photoreal raster model and delivering the
 PNG as the final logo file.

package/dist/agent-src/skills/svg-authoring/SKILL.md

@@ -0,0 +1,318 @@
+---
+model_tier: inherit
+name: svg-authoring
+description: "Hand-author or edit an SVG — icon, mark, illustration, diagram, animation, raster-to-vector — checked and rendered."
+domain: product
+personas:
+  - design-director
+workspaces:
+  - engineering
+packs:
+  - frontend-design
+  - ai-image
+  - ai-video
+  - engineering-base
+trust:
+  level: professional
+install:
+  removable: true
+scope:
+  write: []
+  verification_reason: "execution declares no handler, so this skill runs nothing of its own — every write is the calling agent's, under the rules that govern it. No command can prove a scope the skill never executes."
+execution:
+  type: manual
+---
+
+# svg-authoring
+
+> The one owner for SVG an agent writes by hand. Six lanes produce one — a
+> missing icon glyph, a geometric mark, an illustration, a diagram, an animated
+> asset, a wireframe canvas — and until this skill existed none of them had a
+> procedure or a check beyond the agent's own belief that the file looked right.
+
+## When to use
+
+- A glyph the incumbent icon set does not have (`iconography` first — the set wins).
+- A simple geometric mark, when `logo-generation` takes the true-vector path.
+- An illustration or a diagram authored as SVG rather than generated.
+- An animated asset: SMIL, CSS or WAAPI inside an `.svg` or an inline graphic.
+- A **surgical edit** to an existing SVG — "change only the hat", "remove the face".
+- A **raster converted to a vector** — "turn the logo in this PNG into a real vector".
+
+## When NOT to use
+
+- The icon exists in the set → `iconography`, and stop there.
+- A photoreal or illustrative raster → `image-generation`.
+- A full brand pipeline → `logo-generation` (which routes back here for the mark).
+- Motion design for video → `motion-choreographer`.
+
+## Procedure
+
+1. **Read the delivery mode first — it decides everything after it.** `inline`
+   in a host page, a standalone `document` opened directly, `img`, a CSS
+   background, or a deck. It decides what can animate, what can execute, and how
+   the graphic gets its accessible name. An **undeclared** mode is treated as
+   `inline`, the strictest.
+2. **Classify the asset** — `icon`, `mark`, `illustration`, `diagram`,
+   `animated`. The class picks the fill-ratio threshold and the geometry
+   tolerance; there is no global threshold, because a 24-grid icon's designed
+   padding reads as an under-filled viewBox against one.
+3. **Plan before attributes** — concept, then layout, then attributes.
+   Primitives before detail: a mark built from `rect`/`circle`/`polygon` is a
+   true vector and is often the right answer, not a lesser one.
+4. **Write with the invariants.**
+   - ids namespaced to the graphic — a bare `id="title"` names the second
+     inline graphic on the page after the first.
+   - the accessible name comes from the ARIA corpus, not from here: ground
+     `meaningful standalone svg chart graphic accessible name` against
+     `accessibility-auditor`'s `aria-patterns.csv` and follow the
+     **Meaningful standalone graphic** or **Decorative graphic** row.
+   - colour from the project's tokens or `currentColor`, never a loose hex.
+   - an explicit `font-family` with a fallback the target actually ships; a
+     `<text>` with none resolves to the platform serif.
+   - no `<script>`, no `on*`, no `javascript:`, no `foreignObject`, no external
+     `href` or `url()`, no internal DTD subset or `<!ENTITY` (a bare public
+     DOCTYPE is fine).
+5. **Run the static check** — `lint_svg_asset`, with the delivery mode declared:
+   ```bash
+   npx tsx node_modules/@event4u/agent-config/src/scripts/lint_svg_asset.ts \
+     --file path/to/asset.svg --delivery inline
+   ```
+6. **Run the witness** — the asset profile, which opens the file in a real engine:
+   ```bash
+   agent-config ui:render path/to/asset.svg --profile asset --class icon
+   ```
+7. **Look at the render.** Looking stays mandatory for *meaning*; it is never the
+   pass for *geometry*. Fix what both the checks and the look found.
+8. **Stop** at a clean witness or after three render passes, whichever comes
+   first. A stop **at the cap with error findings still open** reports
+   `unverified` with the reason `pass-cap-reached` and lists what is open —
+   never `verified`, and never done. That reason is yours to report: the render
+   manifest never carries it, because one invocation of `ui:render` cannot see
+   how many passes you have made.
+9. **Report** the renderer and the checks that actually ran — `verified`,
+   `static-only` or `unverified` — plus `goal: unassessed`, and name only
+   output files read back from disk. Where the renderer is **absent**, run the
+   static witness, report `static-only`, and name the missing capability in one
+   line; opening the file in a browser is never a step of this procedure or of
+   the user's.
+
+## Status — what each word is allowed to mean
+
+| Status | Allowed only when |
+|---|---|
+| `verified` | a render manifest from the asset profile exists **whose recorded file digest equals the delivered file's digest on disk**. A manifest from an earlier pass does not count. |
+| `static-only` | the static check ran and no render did. A parser pass (`xmllint --noout`) is this, never `verified` — a file can parse and still be the wrong picture. |
+| `unverified` | no browser resolved, or the pass cap was reached with error findings open (`pass-cap-reached`). Never a pass; never silently upgraded. |
+
+**A second axis, and it is not this table's.** Every status above is about
+whether a CHECK ran and what it found. Whether the graphic is *right* is a
+different question, and `verified` was being read as an answer to it. So every
+report carries `goal:` beside the status, and this skill writes exactly one
+value into it:
+
+| Goal | Written by |
+|---|---|
+| `unassessed` | **always, by this skill and by the renderer.** The default, and the only value either may write. |
+| `accepted` / `rejected` | an owner statement, or a pre-registered scenario witness. Never derived from a digest match, a clean witness, or a score. |
+
+## Editing an existing SVG — the baseline replaces the look
+
+Declare the ids the edit is allowed to touch, then let the readout decide:
+
+```bash
+npx tsx node_modules/@event4u/agent-config/src/scripts/lint_svg_asset.ts \
+  --file after.svg --baseline before.svg --allow hat,hat-band
+```
+
+Every element outside the allowed set that changed is reported with the attribute
+that changed, after number and whitespace canonicalisation. **No pixel diff
+decides this** — anti-aliasing and font metrics would make it a per-machine
+verdict.
+
+This applies **between the owner's own passes** too. A part the user already
+accepted joins the baseline and may not move by hand. A conversion pass that
+re-derives that part from the source instead **re-measures** it and re-checks
+the accepted property — a hole that was accepted as a hole stays a hole through
+a full re-trace.
+
+## Converting a raster to a vector — its own branch
+
+Drawing it from a look fails, and it fails the same way every time: the outlines
+"coincide within a few pixels" by eye and read 0.883 silhouette IoU when
+measured. The procedure below reached 0.984 with the same tools.
+
+### Trace to measure, construct to deliver
+
+**The trace is the underlay by default, not the deliverable.** Trace the source
+to measure and to align; then construct the deliverable over that underlay from
+few points, palette colours and named shapes. Keep a trace AS the deliverable
+only when the owner asks for maximum fidelity over editability, and say that is
+what they are getting.
+
+The reason is measured, not stylistic. In one session the traced mark scored
+0.989 region IoU against the constructed one's 0.935 — and the trace was sent
+back fifteen minutes after it was accepted, on criteria no score sees: a crown
+cut at the crop edge, hairlines between segments, an off-palette spot, jagged
+edges, 49 KB of edit-hostile points, and a face unreadable at 32 px. The
+rebuild was 4.5 KB with 14 shapes and about 180 points. **The score is the
+alignment check. It is never the acceptance.**
+
+**When the score stops applying.** Once the owner's goal becomes a redesign
+rather than a reproduction — different fingers, depth taken from a style
+reference — the source-fidelity number measures agreement with something
+nobody is still trying to match. Stop reporting it as progress and say why.
+
+1. **Crop the source region with a margin, and make that crop the coordinate
+   system.** Write every vector coordinate in the crop's pixel units; fit the
+   viewBox to the content at the end, not at the start. **Widen the crop
+   whenever source content touches its edge** — a trace takes the crop border
+   for a contour, and a comparison against that same crop cannot see the cut.
+   One session lost a crown that way: the crop started five pixels below it.
+   The engine's `geometry/source-cut-by-frame` reading is the check.
+2. **Derive geometry from the pixels, never by eye — then build over it.** One
+   traced silhouette that clips everything, then named regions split along an
+   edge map; smooth, resample and simplify each contour. The outer edge comes
+   from one contour and the holes come from the source. That trace is the
+   underlay; the shapes you ship are constructed on top of it.
+3. **Fit colour, do not pick it.** Least-squares per region against that region's
+   own pixels; swap a linear gradient for a radial one only when the residual
+   actually drops.
+4. **Classify near-white inside the mark as hole or paint from the source**, and
+   check it on a dark background **before** the first report. Near-white paint
+   where the source shows a hole is invisible on white and obvious on black.
+5. **Keep text, wordmark and slogan out** unless they were asked for.
+6. **Score every pass and every candidate change**, and keep a change only when
+   the score improves — a tried-and-worse idea is dropped by the number, not by
+   taste. Use the two readings the geometry comparison produces: silhouette IoU
+   over saturated regions, and mean colour error plus the share of pixels off by
+   more than 40/255 — broken down per region, so the worst region is named. The
+   score ranks passes against the source; it does not decide acceptance, and it
+   stops meaning anything once the goal becomes a redesign.
+7. **Stop** at the declared tolerance, at the user's pass budget, or **on a
+   plateau** — whichever comes first. A plateau is two consecutive passes each
+   improving the score by less than 5 % relative: stop, report the residual's
+   cause, and offer the construct-or-redesign option instead of starting
+   another pass. An explicit pass budget from the user still wins when it is
+   smaller. Measured: twelve further scored passes took mean error 16.78 to
+   6.12 and the share off by 40 from 9.1 % to 1.5 %, and the owner said "still
+   unclean" twice; the plateau was named only after they brought a reference.
+8. **Snapshot every delivered pass** as `<name>.pass-<n>.svg`, and diff the next
+   pass against the last accepted snapshot with `lint_svg_asset --baseline`.
+   Report which accepted properties carried forward. Restoring "version 4" is
+   then a copy, not a reconstruction — one session lost the same accepted
+   detail twice between hand edits, and the owner had to supply the file back
+   from their own downloads.
+9. **Report the per-pass numbers, the cause of the remaining residual, and the
+   file size.** Fidelity costs bytes — one accepted conversion went 5.3 KB →
+   49.5 KB and nothing measured it. Each number carries the **registration**
+   it was taken against as `x,y,w,h` in the source's pixel frame, the
+   **scorer** that produced it (`ui:render`, or a named script) and the sample
+   resolution. Two scorers disagreed on one file by a factor of four and
+   neither number could be told from the other afterwards; a wordmark's frame
+   could not be recovered at all, and three plausible ones moved its IoU from
+   0.56 to 0.81.
+
+Any tracing tool the host has may do the deriving, and a host with none can
+write one. **The measurement is the procedure, not the tool.**
+
+## Deliver, re-open, re-render
+
+The last step reads every delivered file back **from its final path** in a fresh
+browser context (`file://`, every other request aborted) and re-renders it from
+there — not from the source text the agent wrote. Report path, byte size and
+digest. An `img` delivery is additionally loaded through a host `<img>` and must
+report a non-zero natural width.
+
+**A file that does not re-open is not delivered.**
+
+## Output format
+
+1. **Delivery mode and asset class** — declared, not assumed.
+2. **The file** — path, byte size, digest.
+3. **Checks that ran** — the static check's finding count, the witness's
+   readings, and the status word from the table above.
+4. **For a conversion** — the per-pass score table and the residual's cause,
+   each number carrying its **registration** (`x,y,w,h` in the source's pixel
+   frame), the scorer that produced it and the sample resolution, so a later
+   run can repeat the reading and no second scorer's number is quoted as the
+   first's.
+5. **Variants** — for a `mark`, the small-size variant when the 16 and 32 px
+   captures lose the detail, and a light-on-dark variant when the contrast
+   reading is low on a capture's ground. Built, or named as missing. Never
+   silent: one wordmark shipped in a dark violet that is unreadable on a dark
+   ground, and the dark variant was simply not mentioned.
+6. **Outlined lettering** — a word set from an installed font and converted to
+   outlines is reported with the font's name and whether its license allows
+   outlining into a distributed asset. An unknown license is reported as
+   unknown, never as permitted.
+7. **Cost** — the reading the manifest carries (`bytes`, `elements`, `paths`,
+   `gradients`, `coordinates`), beside the fidelity numbers. No threshold: none
+   was measured, and a gate on bytes would have refused a 195 KB trace and a
+   59 KB accepted figure alike.
+8. **What was looked at** — honestly, or nothing.
+
+## Gotcha
+
+- **A `<path>` is not evidence of a vector.** A raster embedded beside one dummy
+  path passes a presence-of-`<path>` check and is not a vector; a mark built
+  from `rect`/`circle` fails that check and is one.
+- **CSS cannot stop SMIL.** `svg * { animation: none !important }` under an
+  emulated `reduce` leaves an `<animate>` running. Route the animation itself.
+- **An `<img>`-delivered SVG never sees the OS motion preference.** The host
+  needs a `<picture>` with a `media="(prefers-reduced-motion: reduce)"` source
+  pointing at a static file.
+- **`screenshot({ animations: 'disabled' })` does not freeze SMIL.** Use
+  `pauseAnimations()` + `setCurrentTime()`.
+- **`transform-origin` without `transform-box` pivots against the view box**, not
+  the element — per element, so a correct sibling proves nothing about it.
+- **`keySplines` outside [0,1] stops the animation outright** rather than
+  clamping it.
+
+## Do NOT
+
+- Do NOT report `verified` on a look, a parser pass, or a render of an earlier
+  draft.
+- Do NOT say "matches" or "100 %" about a conversion without the two numbers and
+  the registration they were measured against.
+- Do NOT rename ids or simplify paths as a side effect of a surgical edit.
+- Do NOT restate motion, ARIA or render-security mechanism here — point at the
+  authority and let it own the rule.
+- Do NOT add a rasteriser, a tracing dependency, or an optimiser to the write path.
+
+## See also
+
+> Named rather than linked, and that is a correctness property rather than a
+> style one: this skill ships in four packs, so a relative link to an artifact
+> that lives in only one of them resolves for a consumer who installed that pack
+> and is dead for the other three. The names are stable; the paths are not
+> promises this skill can keep.
+
+- `iconography` — the set comes first; this skill is
+  for the glyph it lacks.
+- `logo-generation` — the brand pipeline that
+  routes a geometric mark here.
+- `image-provider-routing` — illustrative
+  vector art goes to a provider, not here.
+- `fe-design` § Motion — the motion authority, in
+  `references/design-patterns.md` § *Motion — decision-tree and rationale*. The
+  SVG mechanism lines are step **6b, "Which mechanism carries it inside an
+  SVG?"** — `transform-box`, `pathLength`, the `keySplines` range, path-morph
+  command equality, and delivery mode picking the reduced-motion route. Cited
+  here and never restated.
+- `frontend-render-security` § *The
+  patterns AI ships by default*, row **Untrusted SVG markup into an HTML sink**
+  — the sinks an SVG carries into a host origin, and what each delivery mode
+  can execute. Its § *Backstop greps* carries the grep that finds them.
+- `design-intelligence` — diagram layout; its
+  geometric pre-checks are witnessed by the asset profile now.
+- `accessibility-auditor` — the ARIA
+  corpus that answers what a graphic's accessible name has to be; its
+  `data/aria-patterns.csv` carries the **Meaningful standalone graphic** and
+  **Decorative graphic** rows this skill grounds against rather than copies.
+- `canvas-design`, `wireframe`
+  — the two lanes that use SVG as an execution surface.
+- `design-fidelity` — a provided artifact is
+  the spec; the baseline readout above is its surgical-edit witness.
+- `docs/contracts/design-artifact-verification.md` — `frame_seek` and the other
+  primitives the witness depends on.

package/dist/agent-src/skills/wireframe/SKILL.md

@@ -1,7 +1,7 @@
 ---
 model_tier: inherit
 name: wireframe
-description: "Explore a flow or layout with 3+ disposable lo-fi greyscale wireframes on a named axis, before any hi-fi work. Use when the user wants to sketch directions or explore structure."
+description: "Explore a flow or layout with 3+ disposable lo-fi greyscale wireframes on a named axis. Use when the user wants to sketch directions or explore structure."
 domain: product
 personas: []
 workspaces:
@@ -80,7 +80,10 @@ branded, recommendation-bearing). A single refined implementation →
 
 1. **One file** (HTML or annotated markdown/SVG canvas) with ≥3 greyscale
    variations side-by-side — flows as small storyboards (3–5 screens each);
-   no brand color, no styled typography, no real imagery.
+   no brand color, no styled typography, no real imagery. An SVG canvas is
+   authored under [`svg-authoring`](../svg-authoring/SKILL.md); its grays are
+   the wireframe's own non-decisions, so the fidelity floor does not reproduce
+   them as choices.
 2. **Per-variation annotations** — 2–4 callouts naming the structural bet and
    its trade-off, inline next to the variation.
 3. **Decision-capture block** (after user pick) — chosen direction,

package/dist/agent-src/templates/agents/agent-project-settings.example.yml

@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.ts (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "16.4.0"
+agent_config_version: "16.5.0"
 
 # --- Project identity ---
 project: