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 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)

1. choose carrier + authority → message inline | Library Asset | Memory Page
2. inspect source and refs    → copy real resolved URIs; never fabricate
3. mint + author + review     → `pkf_mint_sids` once; run the quality gate below; 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

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 + full-document review gate

Before pkf_reply_inline or any carrier persist, run this gate. 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 — plain tables do NOT count toward the two: <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.

Then review the COMPLETE draft once against the content→visual selection table above, filtering quality defects that model habit or context pressure inject. Repair every failed check by editing (convert, split, delete) — never by arguing in prose:

1. shape→carrier: name each major section's dominant shape (numbers compared / trend / part-to-whole / entities+relationships / decision flow / phases); where the table routes that shape to a diagram or chart, that element must be present — a prose enumeration or a default table is a failed check, not a style choice.
2. no duplication: a fact a visual already shows is removed from body prose; the visual keeps structure, prose keeps interpretation, source qualifiers, and facts the visual cannot hold.
3. captions: every visual's caption states what it proves, not decoration; alt text conveys the same relationships.
4. coverage: a section with 3+ paragraphs and no visual or table either gains one or carries a one-line, content-specific reason; a document-level "no visual fits" excuse fails the gate, and so does ornamental content added just to satisfy the checklist.
5. degradation: when a blocked carrier forces a Markdown projection, project the same visuals (mermaid fences / Markdown tables); a prose-only fallback fails the gate. State remaining limits after readback.

Core format (PKF v1.1 strict)

Canonical MIME: application/vnd.prismer.pkf+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:

A report with ≥3 major sections and zero visuals is a smell — add the missing visual, or justify per section with a content-specific line; a document-level excuse fails the review gate. 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; live WebGL (drag-orbit, ± / Ctrl⌘+wheel zoom) + static isometric fallback.

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.

<prismer-widget type="tabs">{"tabs":[{"label":"Plan","content":"Phase A complete."},{"label":"Risk","content":"Phase B risk: cache staleness."}]}</prismer-widget>

<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

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.