@prismer/runtime 2.0.8 → 2.2.55

package/built-in-skills/persona-generator/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: persona-generator
+scope: common
+description: >
+  Given a Council Brief, produce persona-ROLE instance definitions: real,
+  publicly-verifiable people who occupy distinct stakeholder positions on the
+  issue — each a persona-flavored role template (lens / voice / SOUL + the
+  persona-skill capability boundary + icon + an ASCII usernameSlug), handed to
+  convene (council-creator) to be instantiated as a REAL agent. (Search
+  grounding of each person is done by the cloud /councils/plan handler, not by
+  this skill.) Use when the workspace orchestrator needs to convene an expert
+  roundtable ("帮我找几个人聊聊这个 idea"). Personas are LENSES distilled from
+  public records, not the real people — never assert private facts, never
+  impersonate. This skill produces the persona-role DEFINITIONS (who speaks); it
+  does NOT create the group and does NOT drive the discussion — that is
+  council-creator.
+license: MIT
+compatibility:
+  - prismer-sdk
+  - hermes
+metadata:
+  category: council
+  personaPolicy: public_distillation
+  disclaimerRequired: true
+  allowedUse: [analysis, debate, ideation]
+  forbiddenUse:
+    - impersonation
+    - private_claim
+    - legal_advice_without_disclaimer
+    - medical_advice_without_disclaimer
+    - financial_advice_without_disclaimer
+  eval:
+    level: generator # eval the GENERATOR against a Brief — never a single persona
+    assertions:
+      - positions-distinct # N personas occupy N distinct stakeholder positions (no two share one)
+      - insider-view-present # ≥1 persona sits where outsiders cannot see
+      - no-fabricated-people # every displayName is a real, publicly verifiable person
+      - risk-coverage-3plus # cast covers ≥3 risk dimensions (capital/tech/market/org/compliance)
+      - grounding-substring # every quote is a substring of a real search snippet (code-checked)
+      - brief-boundary # no persona asserts company facts beyond the Brief
+      - honest-degradation # ungroundable → role_label; fabricated quotes are a hard fail
+---
+
+# Persona Generator
+
+**Who speaks.** Given a Council Brief (assembled by the orchestrator from the
+Team Manager's materials + memory), produce `cast: PersonaDef[]` — 3–5 people occupying
+**distinct stakeholder positions**, each contributing the one thing only their
+position lets them see. This is a **capability skill**: the orchestrator calls
+it to produce data — a set of **persona-role instance definitions**. Each cast
+member is a persona-flavored **role template def** (lens / voice / SOUL + the
+persona-skill capability boundary + icon + an ASCII `usernameSlug`) that convene
+will instantiate as a **real agent** (`createAgentForWorkspace` + `applyToAgent`,
+M2). It is **not** a virtual `im_users` mask — persona = role instance.
+
+| Do | Do NOT |
+| --- | --- |
+| Enumerate stakeholder positions for the issue | Create the council group (council-creator) |
+| Pick one **real person** per position | Drive or moderate the discussion (council-creator) |
+| Produce `seesWhatOthersDont` per person | Write memory (settle phase, via `memory` skill) |
+| Emit voice (per-turn instructions) per person | Parse / extract materials (orchestrator tool-skills) |
+| Hand the cast to cloud `/councils/plan` for grounding | Run search verification / supply quotes yourself (cloud does it) |
+| Read `droppedCast[]` and substitute for dropped people | Invent people, quotes, or citations — ever |
+
+## Meta-goal (iron rule — supersedes any "debate" framing)
+
+**A discussion is a plurality of viewpoints, not a positive-vs-negative game.**
+Convene people of different identities, professions and stakes; each speaks
+from their own position. If disagreement emerges it is the *natural result* of
+plural perspectives — it is never something you construct. Do **not** hunt for
+"an opposing side"; a target function of "construct opposition" structurally
+excludes the two most valuable classes of people: **insiders** (dismissed as
+same-camp) and **people who reject the axis entirely** (nowhere to stand on
+it). The UI language is "讨论组" (discussion group), never "吵一架".
+
+## Core procedure
+
+### Step 0 — List stakeholder positions first (not "axes of disagreement")
+
+Before picking anyone, enumerate the positions whose duty / expertise / stake
+touches this issue:
+
+```
+运营执行者 / 出资人 / 监管者 / 同行实践者 / 下游客户 / 一线员工 / 被影响的第三方 …
+```
+
+### Step 1 — One REAL person per position
+
+- Pick the person whose **real public track record** naturally puts them in
+  that position. If no fitting famous person exists for a position (e.g. "this
+  company's own CTO"), pick a real person who once held the *equivalent*
+  position elsewhere (e.g. another rocket company's former CTO).
+- **Never invent a name.** Prefer swapping to a position where a real person
+  exists.
+- Do **not** require them to disagree with each other. They may all agree and
+  still each fill in a piece the Team Manager cannot see.
+- **Forbidden:** inserting an artificial "opposing side" to manufacture
+  conflict.
+
+For every person you MUST state `seesWhatOthersDont` — not "which side they
+are on", but "standing here, they can see X that nobody else at the table
+can". This field is the core output of the skill.
+
+### Step 2 — Attach the persona (who arrives at the table)
+
+- Enough verifiable public record and a good fit → **real name**
+  (`displayName: "Elon Musk"`, `subtitle: "SpaceX CEO"`). Compliance is
+  carried by the **disclaimer**, never by renaming — "Elon-style Strategy
+  Lens" style abstractions are forbidden (nobody wants to chat with a
+  concept). Internal terms (`persona`, `lens`) never surface in UI copy.
+- Otherwise → a role label ("一位持保守立场的航天投资人") — still a person,
+  not a concept.
+- `usernameSlug` (**load-bearing — this is the persona-agent's @-handle**):
+  ascii `[a-zA-Z0-9_-]`, 3–20 chars, lowercase slug of the person (e.g.
+  `elon-musk`). It must NOT start with the reserved `prismer-` segment. Final
+  uniqueness (`<slug>-<conv8>` + dedupe suffix) is enforced by the cloud at
+  convene time — you only produce the candidate slug. **Why it MUST be ASCII:**
+  once instantiated (M2), the persona-agent is addressed in the group **only**
+  by `@<usernameSlug>`. The mention router (`agent-dispatcher.ts` `MENTION_RE`)
+  is strict ASCII — a bare `@中文displayName` matches nothing and is silently
+  dropped, so a non-ASCII slug would leave the persona **unreachable** (0
+  dispatches, the exact 0/5 failure). The Chinese `displayName` is display-only;
+  it never routes.
+
+### Step 2.5 — Search grounding is done by the CLOUD, not by you
+
+You **only produce candidates** — position + real person + `seesWhatOthersDont`
++ candidate `usernameSlug`. **Do NOT run search verification yourself and do NOT
+supply any `realCredential` / `whySelected` quotes.** Grounding is performed by
+the cloud `/api/im/councils/plan` handler after you hand over the cast.
+
+- **Why cloud, not you (architectural, 04 §2.5):** the anti-fabrication defense
+  requires a **verbatim substring of a real search snippet**, checked in code
+  against full-text search (`/api/search`). The daemon `web_search` tool you can
+  reach routes through `/api/context/load`→`/api/compress`, so it returns
+  **LLM-rewritten prose, not the original text** — you physically cannot obtain
+  the verbatim snippet the substring check needs. Any quote you write from
+  memory would be a fabrication that the cloud check exists to reject.
+- **What the cloud does with your cast:** for each candidate it searches
+  `"<displayName> <topic terms>"` and requires the person's name + a topic term
+  to co-occur **inside the same sentence** ("some results exist" / "snippet
+  contains the keyword" passes off-topic celebrities — 04 §2.5 实测:
+  李开复+商业航天 returned 5 named-but-off-topic hits). Grounded → the persona is
+  kept with `groundingSource='searched'` and verbatim quote evidence. **0
+  co-occurrence → the person is dropped from the cast** and returned in the plan
+  response's `droppedCast[]` — read it and substitute someone else for that
+  position (do NOT patch up the quote).
+- **You still MUST NOT invent people.** Pick a real, publicly verifiable person
+  for each position (swap positions rather than inventing a name) — but leave the
+  evidence to the cloud. Your job ends at "who plausibly sits here"; the cloud
+  decides "is this person actually on-topic".
+- **`groundingTerms` (optional but recommended for mixed-language topics):** you
+  MAY attach a short `groundingTerms: string[]` per candidate — the topic keywords
+  in **the language this person's public record is in** (English for "Elon Musk",
+  中文 for a 中文人物). The cloud grounds against these instead of naively
+  tokenizing the question. Without them, a Chinese question ("2026年商业航天进展")
+  tokenizes to CJK bigrams that won't match an English-record person → that person
+  is wrongly dropped. So for an English-record person on a Chinese topic, supply
+  e.g. `["commercial spaceflight", "launch cost"]`.
+- 🚫 **Never use self-critique as fact-checking.** Asked to "verify the
+  citations are real", an LLM does not admit it cannot find them — it invents
+  a *more specific* fake source ("引自2021年新浪财经专访"). Self-critique is
+  allowed only for *structural* checks (two people on one position? invented
+  names? missing insider view?), never for factual ones.
+
+### Step 3 — Graceful degradation (three tiers, decided by the CLOUD)
+
+> ⚠️ This tiering is applied by the cloud grounding step, not by you — it is
+> shown here so you understand what happens to your candidates. You never set
+> `groundingSource` yourself. In the current implementation a candidate that is
+> not `searched` is returned in `droppedCast[]` for you to substitute.
+
+The criterion is "**can it be found by search?**" — programmatically checkable
+— never "does the model know enough?" (unverifiable; models claim they do).
+
+| Condition | Strategy | `groundingSource` |
+| --- | --- | --- |
+| Name + topic co-occur in one sentence of a snippet | Use its verbatim substring as the quote | `searched` |
+| Not searchable, but the user supplied materials | Ground the quote in the user's materials | `user_materials` |
+| Neither | **Degrade to a role label** ("一位持保守立场的航天投资人"), quote = null | `role_label` |
+
+`role_label` is the most honest tier and the lowest impersonation risk. The
+generator MUST be able to fall to it and MUST NOT fabricate quotes to "stay
+famous". (Legacy tiers `parametric` / `needs_materials` are retired — they
+presumed unverifiable parametric knowledge.)
+
+### Step 4 — Icon acquisition (cloud-executed; you only reference the result)
+
+Icon fetching and cropping run as **pure code on the cloud** (Serper image
+search → Content-Type + magic-bytes double gate → aspect-ratio cull only
+(0.6 ≤ ar ≤ 1.7, never re-rank by squareness — Google's own ranking encodes
+"this is the standard portrait") → **top-edge square crop**, no face-detect).
+Your responsibility is only to carry the resulting `iconAssetRef` (an
+`im_assets` id) into the PersonaDef, or `null` when nothing usable was found —
+the frontend degrades to a monogram. Never inline image bytes or hotlink URLs.
+
+### Step 5 — Voice
+
+`voice` = the persona-role's speaking instructions (markdown): the position,
+speaking style, and disclaimer discipline. Because persona is now a **role
+instance** (not a mask), `voice` — together with lens and a SOUL 特例档 — is what
+convene bakes into the persona-agent's role template at instantiation, so the
+agent speaks in-character from its **own** session (no one plays five roles).
+Write voice as durable, self-contained instructions the standalone agent can
+carry across turns, not one-off remarks. At convene time the cloud persists it
+onto the persona-agent so later `@<usernameSlug>` follow-ups reuse it.
+
+## Output shape (wire contract — aligns with `POST /api/im/councils/plan` cast)
+
+```jsonc
+{
+  "cast": [
+    {
+      "id": "elon-musk",                  // slug — also the personaId in council metadata
+      "displayName": "Elon Musk",         // REAL name; compliance rides the disclaimer
+      "subtitle": "SpaceX 创始人兼 CEO",   // who this person IS — from primary sources only
+      "usernameSlug": "elon-musk",        // ascii @-handle 3-20, no 'prismer-'; cloud dedupes — the ONLY way to reach this persona
+      "iconAssetRef": null,               // im_assets id from the cloud icon service, or null
+      "position": "同行实践者（已量产的商业航天创始人）",
+      "seesWhatOthersDont": "复用一子级的真实成本曲线与产线爬坡节奏",
+      // ⚠️ Do NOT supply realCredential / groundingSource — the cloud fills these
+      //    from live search after grounding (step 2.5). Omit them from your output.
+      "voice": "Speak as a first-principles propulsion founder. Terse. Numbers first. 你是公开资料蒸馏的视角，非本人；Brief 未提供的公司事实一律说「Brief 未提供」。",
+      "disclaimer": "公开资料蒸馏视角，非本人"
+    }
+  ]
+}
+```
+
+No `stance` field (the meta-goal is plural viewpoints, not sides). No `lens`
+field (a stance is the runtime product of `facts × issue`, not a stored
+attribute). Input: `{ brief, requestedPersonas?, n? }` (default n = 3–5).
+
+## Iron principle: persona = lens, Brief = facts (负控 N8)
+
+A persona **never carries company facts of its own**. Everything about the
+company comes from the Council Brief the orchestrator assembled. If a persona
+is asked to assert a company fact the Brief does not provide, it must say
+"Brief 未提供" or mark `needsVerification` — never improvise. This is the
+architectural cure for "stylized bubbles making things up", not a disclaimer.
+Bake this discipline into every `voice` you emit.
+
+At settle, `council-creator` turns this discipline into a **wire contract**: the
+report's `claims[]` each carry `sourceRefs[]` (the real material a fact stands
+on) + `needsVerification`, and unanswerable facts land in `gaps[]`. So your
+`voice` must instruct the persona to speak in **grounded, attributable claims**
+— tie each factual statement to the Brief fact it uses, and say "缺数据" (→
+`needsVerification=true`, `sourceRefs=[]`) rather than inventing a number, so
+council-creator can emit an honest structured report downstream.
+
+## Generator-level eval
+
+Eval judges the **generator** (input: a Brief; assertions over the cast as a
+set), never a single persona. Code-enforceable oracles are the two grounding
+checks (substring + same-sentence co-occurrence); the set-level assertions
+below are eval judgements (semantic classification):
+
+| Assertion | Criterion |
+| --- | --- |
+| Positions distinct | N personas occupy N different stakeholder positions; no two share one |
+| Insider view present | ≥1 person sits where outsiders cannot see (operator / front-line / former insider) |
+| No fabricated people | every `displayName` is real and publicly verifiable (`realCredential` non-empty) |
+| Risk coverage | cast covers ≥3 of: capital / tech / market / org / compliance |
+| Grounding real | every quote is a snippet substring + same-sentence co-occurrence (code check) |
+| Brief boundary | no persona asserts company facts beyond the Brief |
+| Honest degradation | unsearchable → `role_label`, never a fabricated quote |
+
+## Promote escape hatch
+
+An exceptionally good cast can be saved as a **`persona-pack` skill** (static
+snapshot, `metadata.category: council`, `personaPolicy: public_distillation`,
+`disclaimerRequired: true`) and published to the marketplace for fork / rate /
+compose. This is a third, non-default path — the default is always fresh
+generation against the current Brief.
+
+## Configuration
+
+**N/A.** This skill declares no `config:` block. Grounding credentials
+(search API keys) live cloud-side as Nacos global config consumed by the
+`/api/im/councils/plan` handler and `/api/search` — they are never
+agent-bound, so there is nothing for the skill-config binding system to carry
+(product204/09 boundary ruling, CONFLICT-7).
+
+## Anti-patterns
+
+- ❌ Inventing a person because a position "needs" someone famous (the
+  documented failure: `Will Smith` as Relativity's CEO — the real CEO is Tim
+  Ellis). Swap positions instead.
+- ❌ Filling the cast with five competitor CEOs (letting competitors judge
+  your valuation) — that is the retired adversarial framing.
+- ❌ Writing quotes from memory, or "verifying" them by self-critique.
+- ❌ Renaming a real person into a concept ("工程激进视角") to dodge
+  compliance — the disclaimer carries compliance.
+- ❌ Emitting `stance` / picking a side for anyone.
+- ❌ Creating the group, posting messages, or driving rounds — hand the cast
+  to council-creator.

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?