Pkf Writing

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.