@prismer/runtime 2.0.7 → 2.2.55

package/built-in-skills/pkf-svg/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: pkf-svg
+scope: common
+description: 'Design controlled SVG, visual widgets, topology and Visual Core explainers with semantic color, safe geometry, accessibility, and bounded complexity. Use for an explicitly supported SVG/widget surface or to plan PKF visuals. PKF v1.1 has no production inline-SVG authoring surface (diagrams are Mermaid, data charts are d3); v1.2 controlled prismer-svg (pkf209 D19) is activated for PKF source authoring within the frozen validator whitelist.'
+metadata:
+  aliases:
+    - pkf-visual
+---
+
+# pkf-svg
+
+Visual discipline for controlled SVG, widgets, architecture/topology maps,
+and Visual Core experiments. It owns composition, semantic color, geometry,
+safety, and a11y — not PKF persistence or memory placement.
+
+## Production boundary (tell the truth)
+
+- PKF v1.1 keeps no `prismer-svg` production authoring element: SVG travels as
+  a reviewed static asset or a trusted host surface only.
+- PKF v1.2 CONTROLLED `prismer-svg` (docs/pkf209 03 D19) is ACTIVATED
+  (2026-08-18): it may be authored inside PKF source. The production reader
+  validates against the frozen whitelist — script, foreignObject, on*,
+  external href, animation and canvas overflow are hard structure failures
+  (stable `svg-*` codes), not soft conventions. Never author free/raw SVG in
+  any version.
+- In PKF, author diagrams with `<prismer-diagram format="mermaid">`; use
+  Mermaid `erDiagram|flowchart|sequenceDiagram|xychart-beta` as appropriate.
+- Author data charts with `prismer-data` views
+  `chart-bar|chart-line|chart-pie`; the production reader renders them with d3.
+- Mermaid renders classic today. D19 proposes host-only `handDrawn|neo`
+  top-right menu toggles; the workspace host (DiagramView) ships this
+  radiogroup — keyboard reachable, persisted per workspace, source never
+  carries look. Other hosts may not offer the toggle, so do not rely on
+  non-classic look.
+- Mermaid actor/entity/class colors SHOULD use the semantic ramps below.
+  Implemented status (D19 §7): the workspace reader's `resolveMermaidTheme`
+  consumes this exact 9×7 table for themeVariables by diagram family —
+  sequence actor = blue (system), sequence alt/opt branch frame + activation
+  = amber (attention/reversible), note/signal = gray (annotation), erDiagram
+  entity = teal (approved), classDiagram box = purple (control), flowchart
+  nodes = blue (system). Honest limits: flowchart decision diamonds share
+  node colors (mermaid has no diamond-specific themeVariables), and mermaid
+  11.x does not consume `attributeBackgroundColorOdd/Even` for erDiagram
+  attribute rows. Unknown diagram types keep the accent palette fallback.
+- Apply the SVG rules below for any trusted SVG/widget surface, and for
+  `prismer-svg` authored in PKF source (v1.2 activated). Otherwise use Mermaid,
+  d3, semantic HTML/prose, or a reviewed static asset.
+
+## Scenario routing
+
+- ERD/database schema → Mermaid `erDiagram`, never hand-drawn.
+- Sequential process/decision tree → Mermaid `flowchart`; ≤5 flow nodes.
+- Statistical data → d3 chart view; tables → markdown table, not a figure.
+- Controlled SVG/widget → structural, illustrative, or multi-cluster topology
+  only when Mermaid/data surfaces cannot express the intended hierarchy.
+- Loops/cycles → stepper with an explicit wrap-back cue, never a decorative ring.
+
+## Quality floor: 680×480 topology reference
+
+- Use a 680×480 reference canvas for dense topology; preserve the safe area
+  x=40..640 and keep the bottom-most element at least 20px above the edge.
+- Build at least 3 information layers: figure → container → node or status.
+  Containers express bounded contexts; nodes express actors/services/resources;
+  status annotations never compete with the primary topology.
+- Provide accessible `<title>` and `<desc>` in any trusted SVG surface, plus
+  visible labels. Accessibility text must explain the same relationships.
+- Use 0.5px default strokes, boundary-anchored connectors, symmetric padding,
+  and named geometry constants. Nothing clips or floats outside its owner.
+- Maintain stable density: consistent node heights, spacing rhythm, label
+  lengths, and connector clearance across peer clusters.
+
+## Validator quality floors (stable svg-* rejections)
+
+The frozen whitelist audit also rejects objectively unreadable figures:
+svg-too-sparse (<3 visible shapes), svg-monochrome (<2 distinct shape fills,
+backdrop excluded), svg-contrast (text vs container below the 3.0 WCAG
+large-text floor), svg-text-overflow (label width outside x∈[40, width-40]),
+svg-stroke-floor (authored stroke-width <0.5), svg-unlabeled (zero visible
+labels). Each message names the element to fix — repair, never argue.
+
+## Copy-first authoring loop
+
+```text
+1. copy the skeleton below into ONE `prismer-svg` element (wrapper carries
+   width/height/viewBox; the markup inside is the <svg> block)
+2. replace labels, coordinates and colors — ramp hexes from the table only
+3. run `pkf_svg_check({"svg":"<complete svg markup>"})` and fix every svg-*
+   error (one round: each diagnostic names the element/attribute to change)
+4. only then `pkf_validate` the complete PKF and persist
+```
+
+`pkf_svg_check` is a pure local tool: write → check → fix without spending a
+persist round. If the runtime does not offer it, fall back to `pkf_validate`
+on the whole document.
+
+## Skeleton — 680×480, three layers (copy verbatim)
+
+```svg
+<svg viewBox="0 0 680 480" role="img" aria-label="Skeleton: two clusters with one orthogonal edge">
+<title>Skeleton: two clusters, one orthogonal edge</title>
+<desc>Copyable 680x480 skeleton in three layers: backdrop (neutral canvas plus figure title), edges (orthogonal connectors), nodes (clusters, node rects, labels). Replace labels, coordinates and ramp colors.</desc>
+<g id="sk-backdrop">
+<rect x="0" y="0" width="680" height="480" rx="12" fill="#F1EFE8" stroke="#B4B2A9" stroke-width="0.5"></rect>
+<text x="40" y="32" font-size="13" font-weight="500" fill="#2C2C2A">Figure title — replace</text>
+</g>
+<g id="sk-edges">
+<line x1="248" y1="170" x2="432" y2="170" stroke="#5F5E5A" stroke-width="0.5"></line>
+<circle cx="248" cy="170" r="2.5" fill="#5F5E5A"></circle>
+<circle cx="432" cy="170" r="2.5" fill="#5F5E5A"></circle>
+<text x="340" y="158" font-size="11" fill="#444441" text-anchor="middle">relates</text>
+</g>
+<g id="sk-nodes">
+<rect x="40" y="72" width="208" height="196" rx="10" fill="#E6F1FB" stroke="#185FA5" stroke-width="0.5"></rect>
+<text x="56" y="94" font-size="12" font-weight="500" fill="#0C447C">Cluster A · blue · system</text>
+<rect x="56" y="106" width="176" height="34" rx="6" fill="#FFFFFF" stroke="#185FA5" stroke-width="0.5"></rect>
+<text x="64" y="127" font-size="12" fill="#0C447C">Node label one</text>
+<rect x="56" y="152" width="176" height="34" rx="6" fill="#FFFFFF" stroke="#185FA5" stroke-width="0.5"></rect>
+<text x="64" y="173" font-size="12" fill="#0C447C">Node label two</text>
+<rect x="432" y="72" width="208" height="196" rx="10" fill="#E1F5EE" stroke="#0F6E56" stroke-width="0.5"></rect>
+<text x="448" y="94" font-size="12" font-weight="500" fill="#085041">Cluster B · teal · ready</text>
+<rect x="448" y="106" width="176" height="34" rx="6" fill="#FFFFFF" stroke="#0F6E56" stroke-width="0.5"></rect>
+<text x="456" y="127" font-size="12" fill="#085041">Node label one</text>
+<rect x="448" y="152" width="176" height="34" rx="6" fill="#FFFFFF" stroke="#0F6E56" stroke-width="0.5"></rect>
+<text x="456" y="173" font-size="12" fill="#085041">Node label two</text>
+</g>
+<text x="40" y="452" font-size="11" fill="#444441">Fallback caption — describe the same relationships in words.</text>
+</svg>
+```
+
+Layer contract: `sk-backdrop` (neutral canvas + figure title), `sk-edges`
+(orthogonal connectors between clusters), `sk-nodes` (cluster frames, node
+rects, labels). Safe area x=40..640; bottom-most element ≥20px above y=480.
+
+## Fragments — cluster / node / orthogonal edge
+
+Each fragment is standalone-valid; copy the inner layer you need into the
+skeleton and re-check with `pkf_svg_check` after editing.
+
+```svg
+<svg viewBox="0 0 240 150" role="img" aria-label="Cluster frame fragment">
+<title>Cluster frame fragment</title>
+<desc>One bounded-context frame with a title row and one node slot.</desc>
+<rect x="0" y="0" width="240" height="150" rx="8" fill="#F1EFE8"></rect>
+<rect x="40" y="24" width="160" height="96" rx="10" fill="#E6F1FB" stroke="#185FA5" stroke-width="0.5"></rect>
+<text x="52" y="44" font-size="12" font-weight="500" fill="#0C447C">Cluster · context</text>
+<rect x="52" y="56" width="136" height="30" rx="6" fill="#FFFFFF" stroke="#185FA5" stroke-width="0.5"></rect>
+<text x="60" y="76" font-size="12" fill="#0C447C">Node label</text>
+</svg>
+```
+
+```svg
+<svg viewBox="0 0 240 150" role="img" aria-label="Node and status fragment">
+<title>Node and status fragment</title>
+<desc>One node rect plus a status chip from a second ramp family.</desc>
+<rect x="0" y="0" width="240" height="150" rx="8" fill="#F1EFE8"></rect>
+<rect x="40" y="28" width="136" height="34" rx="6" fill="#FFFFFF" stroke="#185FA5" stroke-width="0.5"></rect>
+<text x="52" y="49" font-size="12" fill="#0C447C">Node label</text>
+<rect x="40" y="72" width="136" height="22" rx="5" fill="#FAEEDA" stroke="#854F0B" stroke-width="0.5"></rect>
+<text x="52" y="87" font-size="11" font-weight="500" fill="#633806">attention note</text>
+</svg>
+```
+
+```svg
+<svg viewBox="0 0 300 120" role="img" aria-label="Orthogonal edge fragment">
+<title>Orthogonal edge fragment</title>
+<desc>Two nodes joined by an orthogonal polyline with endpoint dots and a label.</desc>
+<rect x="0" y="0" width="300" height="120" rx="8" fill="#F1EFE8"></rect>
+<rect x="40" y="40" width="80" height="36" rx="6" fill="#E6F1FB" stroke="#185FA5" stroke-width="0.5"></rect>
+<text x="52" y="62" font-size="12" fill="#0C447C">source</text>
+<polyline points="120,58 160,58 160,80 204,80" fill="none" stroke="#5F5E5A" stroke-width="0.5"></polyline>
+<rect x="204" y="62" width="80" height="36" rx="6" fill="#E1F5EE" stroke="#0F6E56" stroke-width="0.5"></rect>
+<text x="216" y="84" font-size="12" fill="#085041">target</text>
+<text x="160" y="48" font-size="11" fill="#444441" text-anchor="middle">relates</text>
+</svg>
+```
+
+## Semantic ramp hex table (host tokens — hex only, never CSS variables)
+
+| family | 50 | 100 | 200 | 400 | 600 | 800 | 900 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| purple | #EEEDFE | #CECBF6 | #AFA9EC | #7F77DD | #534AB7 | #3C3489 | #26215C |
+| teal | #E1F5EE | #9FE1CB | #5DCAA5 | #1D9E75 | #0F6E56 | #085041 | #04342C |
+| coral | #FAECE7 | #F5C4B3 | #F0997B | #D85A30 | #993C1D | #712B13 | #4A1B0C |
+| pink | #FBEAF0 | #F4C0D1 | #ED93B1 | #D4537E | #993556 | #72243E | #4B1528 |
+| gray | #F1EFE8 | #D3D1C7 | #B4B2A9 | #888780 | #5F5E5A | #444441 | #2C2C2A |
+| blue | #E6F1FB | #B5D4F4 | #85B7EB | #378ADD | #185FA5 | #0C447C | #042C53 |
+| green | #EAF3DE | #C0DD97 | #97C459 | #639922 | #3B6D11 | #27500A | #173404 |
+| amber | #FAEEDA | #FAC775 | #EF9F27 | #BA7517 | #854F0B | #633806 | #412402 |
+| red | #FCEBEB | #F7C1C1 | #F09595 | #E24B4A | #A32D2D | #791F1F | #501313 |
+
+Light mode = 50 fill + 600 stroke + 800 title; dark = 800 fill + 200 stroke
++ 100 title (same table, different usage). The svg-monochrome floor requires
+≥2 distinct families among shape fills.
+
+## Coordinate grid reference
+
+- x columns at 60px rhythm: 40, 100, 160, 220, 280, 340, 400, 460, 520, 580,
+  640 — labels start at a column, nodes span 3 columns (176px at 56px inset).
+- y bands: figure title 32, cluster title 94, node rows 127 / 173 (34px tall,
+  46px pitch), legend 316..346, fallback caption 378..394, bottom ≥460.
+
+## Semantic color and complexity
+
+- Palette ramps: purple/teal/coral/pink/gray/blue/green/amber/red; use host
+  tokens, never improvised hex values. Shape/size/color changes encode meaning.
+- Stable defaults: blue = system/deployment, teal = approved/ready/success,
+  purple = control/rollback, amber = attention/reversible action, and red =
+  risk/blocker only. Use gray for annotation, never to weaken a main branch.
+- Dark surfaces preserve depth: map light 50 → dark 800 and light 100 →
+  dark 900; keep text/connector contrast explicit instead of auto-inverting.
+- Ordinary figure default: ≤2 ramps per figure.
+- Complex topology/architecture exception: group by bounded context and use
+  up to 4 domain ramps, plus 1 reserved status/risk ramp. Each visual group
+  remains ≤2 ramps. Color must express category or status and carry a text cue;
+  color alone is never the only signal.
+- A figure containing two small flows keeps each of the two small flows ≤2
+  ramps; do not borrow the topology exception for decorative variety.
+- ≤4 boxes per horizontal tier, ≤5 nodes per simple flow, nesting ≤3,
+  subtitles ≤5 words, and ≥60px between flow boxes.
+
+## Typography and composition
+
+- Weights 400/500 only; minimum 11px; sentence case; no emoji as iconography.
+- One reading direction and one focal story. Use primary/secondary/annotation
+  rhythm; do not distribute motifs merely to fill the canvas.
+- Labels remain inside their owning container and outside the object they name.
+- Legends reuse rendered token colors and pair every swatch with a label.
+
+## Safety and accessibility gate
+
+- The host allowlist is authoritative. Never emit `script`, `foreignObject`,
+  event handler (`on*`), external URL/reference, remote CSS/font, animation,
+  iframe, image, or untrusted `use` content.
+- v1.2 wire: the frozen validator whitelist (elements {svg,g,rect,circle,
+  ellipse,line,path,polyline,polygon,text,tspan,title,desc}, geometry/paint/
+  text attributes, budgets 512 elements / 2048 attributes / viewBox ≤4096) is
+  enforced by the production reader — author inside it, never around it.
+- Internal fragment IDs must be unique and namespaced; references stay local.
+- Every connector has a visible endpoint and a textual relationship cue.
+- On rejection or unsupported surfaces, fail closed to source/prose/static
+  fallback; never claim a sanitized or dropped figure was persisted.
+
+## Self-check
+
+- Correct surface and scenario? v1.2 controlled prismer-svg stays inside the
+  frozen whitelist — script/foreignObject/on*/external refs/animations absent,
+  title+desc present, ids unique — and is never free/raw?
+- Copied the skeleton, kept three information layers, 680 safe area,
+  title+desc, 0.5px, stable density — and `pkf_svg_check` is green?
+- Ordinary ≤2 ramps, or a justified bounded-context exception within caps?
+- Color has semantic meaning plus a text cue; each visual group remains ≤2?
+- One reading direction, boundary anchors, no clipping, stable peer rhythm?
+- Unsafe tags/attributes/external references absent; fallback remains readable?

package/built-in-skills/pkf-writing/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: pkf-writing
+scope: common
+description: Author, update, convert, validate, persist, and render PKF (`.pkf`) content through message-inline, Library Asset, or Memory Page carriers. Use for structured reports, knowledge pages, delivery cards, or any `.pkf` body. NOT for recall, memory-graph placement, or curation decisions — those belong to the `memory` skill.
+---
+
+# pkf-writing
+
+PKF is the workspace long-content format: sanitized HTML plus frontmatter,
+typed links, and controlled media/data/math/interactive elements. This skill
+owns PKF authoring and carrier discipline. The `memory` skill decides what to
+remember and where; domain workflows decide when a deliverable is required.
+
+## Choose exactly one carrier
+
+| Carrier | Authority | Validation, persist, and readback | Reply |
+| --- | --- | --- | --- |
+| Message inline | PKF bytes delivered mechanically by `pkf_reply_inline`; the attached inline ContentBlock is durable with the message | validate the complete file BEFORE the call; the Runtime re-reads, re-validates, and attaches it for you; inspect the extracted/rendered receipt | Markdown projection is the reply text; never paste sentinel comments, never attach the .pkf as a file |
+| Library `.pkf` Asset | Library asset bytes + content hash/revision + scoped URI | dependency-free: host Library writer; dependency-bearing: atomic `pkf_bundle_commit`; read back authoritative root and graph | link the root asset and include a short projection |
+| Memory Page | Memory Page body + page revision | ask `memory` to choose/create the page; validate before its domain writer; read back the page and revision | summarize the remembered fact and canonical page |
+
+Carrier authority is exclusive. Markdown projection is a readable derivative,
+never canonical authority. Never report success from local draft bytes alone.
+When the user asks for an article/report in chat and does not explicitly ask
+for a downloadable file or Memory page, choose Message inline. Do not create
+an attachment merely because the task workspace exposes an artifacts folder.
+
+### Message-inline delivery (pkf_reply_inline)
+
+Deliver mechanically, never by pasting wire bytes: save the validated PKF to a file in
+the task scratch dir, then call `pkf_reply_inline({"path":"memo.pkf"})` exactly once and
+reply in Markdown projection; the Runtime attaches the ContentBlock. If validation is
+not green, do not deliver at all.
+Never paste sentinel comments into the reply; never attach the .pkf as a file; the
+Runtime still extracts the bytes between the two sentinels
+`<!-- prismer-pkf:inline:start -->` / `<!-- prismer-pkf:inline:end -->` for legacy agents that predate the tool — do not hand-write that region.
+
+## Authoring loop (all carriers)
+
+```text
+1. choose carrier + authority → message inline | Library Asset | Memory Page
+2. inspect source and refs    → copy real resolved URIs; never fabricate
+3. mint + author + validate   → `pkf_mint_sids` once; repair every error; resolve referenced assets
+4. persist through owner      → `pkf_reply_inline` | Library/bundle writer | memory writer
+5. readback + project         → URI/revision/hash + resolved validation; concise Markdown projection
+```
+
+**Never fabricate a URI.** Copy scoped `prismer://workspace/<ws>/asset/<sha256>` values
+from browse/resolve results. Inside one atomic bundle, reference bundle files by their
+bundle-relative path (e.g. `manifest="manifest.json"`, `src="data.csv"`); the Runtime
+normalizer computes every SHA-256 content hash, SRI and source hash, generates the harness
+manifest from `harnessDecl`, and rewrites those references into host-bound scoped asset URIs
+before the commit. Do not compute or hand-type hashes yourself — supply content (`bytesBase64` or
+`text`), paths, mime and usage only; a self-supplied hash is verified locally and a mismatch fails fast.
+Do not pass actor or workspace arguments to the commit tool; the host binds authority. If
+host-bound scope is unavailable, stop instead of guessing it. No base64/data-URI assets,
+remote scripts/fonts, or new bare `prismer://asset/<id>` references. If persistence or
+readback is unavailable, say so and retain a draft; never fake a revision.
+
+## Real command matrix and editing lanes
+
+| Need | Structured/runtime | Native/Cloud CLI |
+| --- | --- | --- |
+| mint section ids | `pkf_mint_sids` | n/a |
+| inspect | `pkf_outline`, `pkf_search`, `pkf_read` | `cloud pkf inspect` or ordinary UTF-8 read |
+| edit local draft | normal file tools | `cloud pkf patch`, `cloud pkf diff` |
+| validate | `pkf_validate` | `cloud pkf validate` |
+| deliver message-inline | `pkf_reply_inline` (task scratch/workdir file path) | n/a |
+| persist Library Asset | host Library writer | `cloud asset upload` only when the host exposes it; require its receipt |
+| persist logical bundle | `pkf_bundle_commit` | one atomic root + dependency graph; require readback |
+| persist Memory Page | `memory_browse` → `memory_write` → `memory_load` | n/a |
+| project/export | host projection | `cloud pkf project`, `cloud pkf render` |
+| harness assets | n/a | `cloud pkf pack-harness` |
+
+`pkf_mint_sids`/`pkf_validate`/`pkf_outline`/`pkf_search`/`pkf_read`/
+`pkf_bundle_commit`/`pkf_reply_inline` are native **function-call tools** —
+not shell executables. Call them through the tool API with JSON arguments;
+never `command -v`, terminal probes, Python imports, or hand-written SID/validator
+replacements. The shell lane is only `cloud …`. If a required native tool and
+`cloud` are both unavailable, keep a draft and report the Runtime capability error.
+
+The `.pkf` file is ordinary UTF-8. Validate the whole page after every edit;
+a 409/412 means re-read and re-target, never force. After persistence, read
+back canonical bytes/receipt and run resolved validation where supported.
+
+## Report quality floor
+
+Before `pkf_reply_inline` or any carrier persist, run a quality self-check.
+A valid PKF shell can still be an unacceptable deliverable: strict validation
+only proves the carrier is parseable. For substantive research memos,
+playbooks, and architecture reviews, unless the user asks plain text, include:
+- five or more semantic sections, including decision/summary and action/checklist;
+- at least two rich affordances chosen by need: comparison/risk/ownership table,
+  `<prismer-diagram ...>`, `<prismer-data ...>`, `<prismer-widget ...>`, or
+  CONTROLLED `prismer-svg` via `pkf-svg` + `pkf_svg_check`;
+- caption/alt text that explains what each visual proves, not decoration.
+
+If no visual/data/widget is useful, state that in the Markdown projection after readback; never add ornamental content just to satisfy the checklist.
+
+## Core format (PKF v1.1 strict)
+
+Canonical MIME: `application/vnd.prismer.pkf+html`.
+
+```html
+<script type="application/prismer+json">
+{"type":"note","title":"Database choice","description":"Chose PostgreSQL over MySQL.","tags":["db","decision"],"timestamp":"2026-06-29T00:00:00Z","visibility":"workspace","sensitivity":"none","pkfVersion":"1.1","presentation":{"theme":"knowledge","density":"comfortable","fontProfile":"auto","locale":"zh-CN"}}
+</script>
+<section><h2 id="decision" data-sid="sec_01k2f6m8v7q4x9a3b5c6d7e8f9">Decision</h2><p>…</p></section>
+```
+
+- `description` is required and feeds previews/TOC. Presentation theme is
+  `knowledge|editorial|technical`; density `compact|comfortable`; fontProfile
+  `auto|sans|serif`; locale is BCP-47. Font profiles never accept URLs.
+- Each `<section>` first direct heading carries `id` + stable `data-sid` (`sec_` + 26
+  lowercase Crockford base32). Mint once; renames do not change it.
+- Typed relations: `derived-from|contradicts|supports|child-of|related|references|cites`.
+  Copy hrefs from browse/search results. `child-of` points from child to hub.
+- Strict errors: scripts/styles, inline handlers/style, javascript URLs, bare
+  asset URIs, malformed frontmatter, duplicate/illegal section identities.
+
+## Semantic content and security
+
+Use headings, paragraphs, lists, blockquotes, code/pre, tables, figure/figcaption,
+details/summary, footnote roles, and optional `data-pkf-layout="columns-2|wide|full-bleed"`.
+Every media figure has alt text or figcaption. Sanitization does not grant permission:
+rejected content must not be persisted as successful PKF; a raw upload may remain
+quarantined but must never render active or be reported as a successful canonical write.
+
+- Media pointers use scoped resolved URIs; never embed copies or remote media.
+- `<prismer-file src="…" name="guide.pdf" mime="application/pdf" bytes="476356">`
+  uses a pathless name; unknown MIME degrades to a generic card.
+- `<prismer-data format="csv" view="table" caption="…">…</prismer-data>`; formats
+  `csv|tsv|json|ndjson|parquet|arrow|npz`, views
+  `table|line|bar|scatter|area|heatmap|json-tree|chart-bar|chart-line|chart-pie`.
+- `<prismer-math format="tex" display="inline|block">E = mc^2</prismer-math>`;
+  TeX only, KaTeX trust=false, ≤16 KiB; unsafe/unknown macros fall back to source.
+
+## Visual capabilities: content → visual selection, delegate the grammar
+
+Content → visual selection (一图胜千言 — pick by content shape); structured
+reports plan visuals in the outline, never decorate afterwards:
+
+| Content shape | Visual | Carrier |
+| --- | --- | --- |
+| Entities + relationships (architecture, topology, integrations) | diagram | `<prismer-diagram format="mermaid">` (`flowchart`/`erDiagram`) |
+| Decision paths, state machines, protocols | diagram | `<prismer-diagram format="mermaid">` (`flowchart`/`sequenceDiagram`) |
+| Who does what when (handoffs, orchestration) | sequence diagram | `<prismer-diagram format="mermaid">` |
+| Numbers compared across categories (gaps, scores, counts) | bar chart | `<prismer-data view="chart-bar">` |
+| Trend over stages/time (adoption, latency, cost) | line chart | `<prismer-data view="chart-line">` |
+| Part-to-whole (share of count/risk/effort) | pie chart | `<prismer-data view="chart-pie">` |
+| Maturity/phases/gates | flowchart or table | `<prismer-diagram>` / table |
+
+A report with ≥3 major sections and zero visuals is a smell — justify prose-only in one
+sentence or add the missing visual; never duplicate (chart OR table OR prose enumeration);
+every caption states the takeaway, not the mechanics, and prose carries interpretation only.
+
+Load `pkf-svg` for visual planning, widget composition, accessibility, and quality review;
+it owns visual/SVG grammar, this skill only routes the carrier. Simple diagrams stay on
+`<prismer-diagram format="mermaid" caption="…">` (Mermaid
+`erDiagram|flowchart|sequenceDiagram|xychart-beta`); data stay on d3-backed
+`chart-bar|chart-line|chart-pie`.
+
+### Visual SOURCES — four lanes, one rule: the pointer must be a scoped URI
+
+1. **Draw it natively (preferred for facts)** — Mermaid diagrams and `prismer-data` charts
+   from YOUR structured data: deterministic, editable, theme-consistent, zero external
+   dependency. Prefer it whenever the visual encodes facts the report states.
+2. **Author controlled SVG** (PKF v1.2 CONTROLLED `prismer-svg`, pkf209 D19 activated
+   2026-08-18; grammar owned by `pkf-svg`) — for topology/complex hierarchy Mermaid cannot
+   express: copy the pkf-svg skeleton, verify with `pkf_svg_check({"svg":"…"})` until green.
+3. **AI-generate imagery** (`image-generate` skill) — concept/mood visuals only (metaphor,
+   hero, illustration), never for facts. `cloud deliver` it into the workspace, read back
+   the asset id/hash, reference the scoped URI in the body
+   (`<figure><img src="prismer://workspace/<ws>/asset/<hash>">`), caption as generated.
+4. **Web imagery** (`web_load`/web search) — licensed/public imagery must be DOWNLOADED and
+   materialized as a workspace asset first (same scoped-URI path as lane 3); remote URLs
+   never render. Public-domain/permissive sources only; attribute in the caption.
+
+Selection order: facts → lane 1; Mermaid-inexpressible structure → lane 2; concept/mood →
+lane 3; real-world photos/screenshots → lane 4 (or lane 3 when nothing suitable exists).
+If `pkf-svg` is unavailable, fallback to Mermaid for diagrams, d3 for data, semantic
+HTML/prose, or a reviewed static asset. Do not hand-roll free SVG.
+
+- Mermaid fences from imported markdown serialize into the same diagram element:
+  `PKF_EXAMPLE_INLINE_DIAGRAM`, `PKF_EXAMPLE_ER_DIAGRAM`, `PKF_EXAMPLE_MERMAID_IMPORT`;
+  data/image/model: `PKF_EXAMPLE_CHARTS`, `PKF_EXAMPLE_AI_IMAGE`, `PKF_EXAMPLE_MODEL_3D`,
+  `PKF_EXAMPLE_MIXED` — all in `src/lib/pkf/examples.ts` (`PKF_EXAMPLE_CAPABILITIES`).
+  AI text-to-image output is a reviewed PNG asset with a resolved scoped URI, never an inline substitute or hand-drawn SVG.
+- `<prismer-model format="primitives" caption="…">`: declarative `box|sphere|cylinder|torus|plane`
+  JSON, ≤50 objects, zero script; renders as a static frame today.
+
+## Interactive content: widgets first, harness only for custom JS
+
+For ordinary interaction (tabbed sections, tag filtering, counters, timelines, checklists)
+use the declarative `<prismer-widget>` — the reader renders it natively with
+zero JS and zero iframe. At most one widget per document, ≤32 entries each, ≤8 KiB total; types
+`tabs|filter|counter|timeline|checklist`.
+
+```html
+<prismer-widget type="tabs">{"tabs":[{"label":"Plan","content":"Phase A complete."},{"label":"Risk","content":"Phase B risk: cache staleness."}]}</prismer-widget>
+```
+```html
+<prismer-widget type="checklist">{"title":"Launch gate","items":[{"text":"Tests green","done":true},{"text":"Docs updated","done":false}]}</prismer-widget>
+```
+
+Seed/onboarding PKF must be self-contained: one canonical tour page, stable ids/SIDs, real scoped
+URIs from manifest or bundle readback, no remote URLs/data URIs/base64/invented hashes; success is
+proven by persisted assets, ledger rows, Memory receipts, and DOM/readback — not welcome wording.
+
+Only when custom JS is genuinely required — knowing the host mount is NOT implemented yet (a bundle packs and validates but does not render) — use the JS harness below and let the Runtime compute its hashes and manifest.
+
+## Interactive harness
+
+Any PKF with JS, CSS, media, CSV, or other support files is one logical bundle. Call
+`pkf_bundle_commit` once with one atomic logical bundle: the PKF root and all dependencies,
+using one stable idempotency key across retries. Completion requires canonical readback of
+the receipt, root, and resource relation graph. Never upload JS, CSS, media, CSV, or
+dependencies separately; never use prose to claim resource relations or attachment associations.
+
+`<prismer-interactive manifest="prismer://workspace/<ws>/asset/<sha256>">` points to a versioned
+manifest whose scripts/styles use scoped URIs and real sha256 integrity; the pack command rejects
+traversal, symlinks, remote imports, and oversize; sandbox is allow-scripts without
+allow-same-origin under CSP. Always provide a static no-JS fallback; non-empty actions require governance.
+
+## Validation, readback, projection, export
+
+```text
+native tool: pkf_validate({"source":"<complete PKF>","level":"structure"})
+cloud pkf validate <file> [--level resolved] [--json]
+```
+
+- Every error blocks persistence. Resource refs remain unverified until the
+  authority readback resolves them. Structure-only success is not completion.
+- Markdown projection is read-only degradation, never executable or canonical.
+- Standalone export contains no bearer/presigned URLs; private refs degrade to
+  labels, interactive content to static fallback, and math uses pinned KaTeX.