Pneuma Kami

Pneuma Kami Mode

Credit. This mode's design language, tokens, seed templates, and reference documents are adapted from tw93/kami under the MIT License. See ../NOTICE.md for full attribution.

What this mode is

Paper-canvas web design. The viewer renders your content as a single paper sheet. Size is {{paperSize}} {{orientation}} ({{pageWidthMm}} × {{pageHeightMm}} mm), locked at workspace creation in .pneuma/config.json. Do not change paper size — if the user wants a different size, they must create a new workspace.

You edit HTML / CSS / JS files inside each content set directly with the Edit and Write tools. The iframe preview reflects changes live.

Working with the viewer

The kami viewer renders the active HTML file as a single paper sheet at the locked paper size, inside an iframe with a paper-style chrome (page tabs along the bottom for multi-page documents, viewport presets, view / edit / select / annotate mode toggles, an Export menu). Everything below is how you (the agent) coordinate with that surface.

Reading what the user sees

Each user message may arrive wrapped in two channels — read them before acting:

• <viewer-context> — the live preview state at send time. For kami this includes mode="kami", the active HTML file="..." (full workspace path, e.g. kaku-portfolio/page-3.html), and a page label like Viewing page 3/6: "Projects" derived from the content set's manifest.json. When the user clicks an element in the page, you also get Selected: <selector>, an Address: line (a machine-readable ViewerAddress you can paste straight into a capture call or a <viewer-locator> card), Element: <accessible name>, Tag: <h2>, Classes: ..., Context: <nearby text>, and Accessibility: .... In Annotate mode the block lists multiple annotated elements with the user's per-element Feedback: comment. Resolve deictic phrases like "this heading", "tighten this section", "the figure here" against these fields first.

  Example:

  <viewer-context mode="kami" file="kaku-portfolio/page-3.html" content-set="kaku-portfolio">
  Viewing page 3/6: "Projects"
  Selected: h2.section-title
    Address: {"contentSet":"kaku-portfolio","page":"page-3.html","selector":"h2.section-title"}
    Element: Projects
    Tag: <h2>
    Classes: section-title
    Context: Projects 2024 — selected work
  </viewer-context>

• <user-actions> — discrete UI actions the user took since their last turn. Kami emits one kind: edit-text — inline text edits made directly inside the iframe in Edit mode (the user double-clicked a text node and rewrote it). The action's description includes the before → after diff per element, so treat it as a record of changes the user already committed; don't re-apply them.

  <user-actions>
    <action time="12s ago" id="edit-text">Edited text on "kaku-portfolio/page-3.html":
      <h2>: "项目" → "Projects"
      <p>: "2024 年精选" → "Selected work, 2024"</action>
  </user-actions>

  After an edit-text action, re-read .pneuma/kami-fit.json — text rewrites can flip a page's status from fits to overflow.

If neither block is present, the user has nothing specifically selected; default to the most recently edited file or ask.

ViewerAddress — naming an object in the preview

Kami has one vocabulary for "which object in the viewer". The same shape — a ViewerAddress — is what a <viewer-locator> card points at, what the capture action screenshots, and what a <viewer-context> selection reports back to you. Learn it once; it works across all three.

Use only the keys you need: {"page":"page-3.html"} names a whole page; {"page":"page-3.html","selector":"figure"} names one region of it. When the user clicks an element, the Address: line in <viewer-context> hands you a ready-made ViewerAddress — copy that JSON straight back.

Locator cards

After creating or editing pages, embed <viewer-locator> cards in your reply so the user can jump straight to the result. The card's address attribute is a ViewerAddress — locators navigate the user to a page, so use the coarse keys (page):

<viewer-locator label="Open the cover" address='{"page":"index.html"}' />
<viewer-locator label="Jump to the Projects page" address='{"page":"page-3.html"}' />
<viewer-locator label="See the rewritten Methods page" address='{"file":"methods.html"}' />

One card per landmark you want the user to verify. Switching content sets (e.g. from pneuma-one-pager to kaku-portfolio) is driven by the viewer chrome, not the locator card — point the user there in prose if they need to switch sets.

Viewer actions

Kami exposes no agent-invocable viewer actions today. There is no scaffold, no navigate, no programmatic page-size or orientation change (paper size and orientation are locked at workspace creation in .pneuma/config.json; see "What this mode is"). To start a new document, create a new content-set directory with index.html + manifest.json directly using Write — see "When the user hands over raw content" below.

The base POST $PNEUMA_API/api/viewer/action endpoint exists for modes that declare actions; calling it for kami will not match any registered action.

Native bridge

Desktop APIs (clipboard, shell, notifications, …) are available at $PNEUMA_API/api/native/* when the session runs inside the Pneuma App. Discover what's actually wired up at runtime with GET $PNEUMA_API/api/native — web-only sessions report available: false for unsupported modules.

Verifying your work

The user is already watching a live preview of every edit you make — you do not need to prove the page renders.

Hard rule: do NOT open an external browser, the chrome-devtools MCP, headless Chrome, or browser-use tooling to verify your work.

Why: those tools render the raw HTML outside the kami viewer. Kami renders your content as a single paper sheet at the locked physical paper size — the paper chrome, the sheet dimensions, and the page-fit framing are all applied by the viewer. Open an HTML file directly and you see an unbounded web page, not a paper page. What an external browser shows is not what the user sees. The Pneuma viewer is the only faithful render.

When you genuinely need to see the rendered result for a "quality check → improve" loop, use the framework-level capture viewer action — it returns a PNG screenshot of the live viewer, exactly what the user sees:

# Full viewer — omit params for a whole-sheet shot
curl -s -X POST "$PNEUMA_API/api/viewer/action" \
  -H 'Content-Type: application/json' \
  -d '{"actionId":"capture"}'

# A specific region — pass a ViewerAddress; `selector` resolves inside the rendered page
curl -s -X POST "$PNEUMA_API/api/viewer/action" \
  -H 'Content-Type: application/json' \
  -d '{"actionId":"capture","params":{"address":{"selector":"figure"}}}'

# A region on another page — coarse `page` navigates first, then `selector` resolves
curl -s -X POST "$PNEUMA_API/api/viewer/action" \
  -H 'Content-Type: application/json' \
  -d '{"actionId":"capture","params":{"address":{"page":"page-3.html","selector":"figure"}}}'

params.address is a ViewerAddress — omit it for a full-viewer shot. On success the response is {"success":true,"data":{"path":"<absolute .png path>","width":<n>,"height":<n>}}. Use your Read tool on that path to view the screenshot inline, then iterate. For fit issues, .pneuma/kami-fit.json stays the precise, machine-readable check — capture is for visual judgement.

Aesthetic rules (kami adapted)

--sans aliases --serif in _shared/styles.css; use one serif per page unless the design calls for an explicit mono code block. Match the user's language: CN content stays on the TsangerJinKai02 stack, EN on Charter, JA on YuMincho, KO on Source Han Serif K → AppleMyungjo. JA and KO are best-effort (the fonts are system-bundled, not shipped) — visually verify before shipping. In any stack, the CJK families lead and the Latin faces trail: a substituted CJK serif produces no missing-glyph boxes, so the page still reads and nobody notices it went heavy and flat.

Working rules

• Edit HTML / CSS / JS files directly — the user sees every change live.
• Do not edit _shared/styles.css tokens casually. Aesthetic drift compounds fast. Per-document overrides go in that document's own stylesheet.
• The parchment canvas has exactly one sanctioned exception: the opt-in white-paper print recipe for documents headed to a home or office printer — references/design.md §6.
• When importing raw content, create a new content set (see references/writing.md).
• Do not modify .claude/ — it's runtime-managed.
• Paper size and orientation are locked at workspace creation. A different size means a new workspace, not an edit.

Out of model here. Don't render slides through Python (WeasyPrint / python-pptx) or Marp — kami slides are HTML paper pages in the iframe. Don't build screen-first landing pages, their carousels, or their multilingual SEO companions; that is webcraft's job. Both exist upstream and neither survives the move to a single physical sheet.

Workspace layout

_shared/
  styles.css          # Tokens + paper dimensions. Don't edit casually.
  assets/fonts/       # Bundled fonts: TsangerJinKai02-W04.ttf, JetBrainsMono.woff2
  assets/diagrams/    # 18 self-contained SVG templates — copy the <svg>
                      # block out, drop it inside a <figure> on a page.
pneuma-one-pager/      # EN one-pager demo (Pneuma product brief)
kaku-portfolio/        # CN 6-page portfolio demo (from kami)
.pneuma/kami-fit.json  # Auto-written fit report — READ after every edit

Each content set has an index.html + manifest.json (+ a README.md for provenance). The user can switch between sets, or you can create new ones when they hand over raw content.

Doc types this mode handles

One design language across these document genres. Pick the genre from the user's intent before choosing a layout — the genre dictates length, page count, density, and which diagrams sit naturally inside.

Seed demos cover three points on this spectrum (pneuma-one-pager/, kaku-portfolio/, nvda-equity-report/); the rest you build from scratch into a new content set.

Output format selection is driven by the viewer's Export menu (PDF / PNG); do not auto-trigger PDF/PNG generation from the agent side.

Which kind of task this is

Route on the state of the artifact, not on the words in the request. Four kinds, and only the first one runs the full flow below:

The two that go wrong quietly are content-only and visual repair, because both invite a tidy-up of everything nearby. Approved pages, settled content, and _shared/styles.css are outside the boundary in both.

When the user hands over raw content

This is the New document flow. It assumes you've already classified the doc type using the table above.

Step 1 · Source and material pass

Run this before distilling or filling when the document depends on facts or materials outside the user's draft. Skip it for personal drafts where the user already supplied everything.

Source check fires when the document names a specific company, product, person, release date, version, funding round, metric, market fact, or technical spec. Work from primary sources, keep a short note of source names and dates for the facts that drive the document, and ask the user when sources conflict rather than choosing silently. references/writing.md «5. Sources before phrasing» owns the detail, including which current-sounding claims ("latest", "recent", "new", version numbers, launch dates, financial figures) are banned until checked.

Material check fires when the subject is a company, product, project, venue, or personal brand. Confirm what makes it recognizable before layout:

A missing item gets a compact gap table and one question — never a generic stand-in, an approximated logo, or an invented value. references/writing.md «6. Materials serve recognition» carries the writing-side rules.

Materials status block. After the material check, output a structured status block before continuing. One-shot transparency display, not a question:

Materials status:
- Logo: OK assets/client-logo.svg
- Brand colors: OK #1B365D mapped to --brand
- Product screenshot: MISSING (proceeding with kami default placeholder)
- UI screenshot: not required for this doc type

Use OK, MISSING, or not required. If a required item is missing and no user input arrived, ask once with the gap table; otherwise continue silently.

Step 2 · Layout note (plan before layout)

Before creating the content set, write a short editor-style note stating the plan. It names six things, and the last one is the point: doc genre, page target (or length), narrative arc, embedded diagrams, material status, and the checks this document has to pass before you hand it back. Naming the acceptance bar before layout is what stops it being negotiated downward at the end. Match the user's language, keep it short enough to read in one glance, and continue immediately — this is transparency, not an approval gate.

Example (EN):

Layout intent: Equity Report (EN), two pages A4. Open with thesis and price target, run through valuation (DCF and comparables), close on catalysts and risks. A revenue line chart and an FY26 waterfall sit mid-doc. Logo is in hand; product image is absent, so the header stays text-only. Ships when both pages read fits and every number traces back to the filing.

Example (CN):

排版意图：Equity Report 中文版，2 页 A4。先立论与目标价，进入估值 (DCF 与可比公司)，落于催化剂与风险。中段嵌一张营收趋势折线和 FY26 收入桥瀑 布。Logo 已就位，产品图暂缺，header 改走纯文字。交付标准：两页都 fits， 每个数字都能回溯到财报原文。

If the user pushes back, adjust; otherwise proceed to Step 3.

Step 3 · Create the content set

1. Pick a short content-set name (e.g. acme-whitepaper/).
2. Create the directory with an index.html that starts from the closest existing demo as a skeleton, a manifest.json, and a README.md.
3. Extract every factual claim from the raw content; classify into sections that match the target doc type's structure.
4. Gap-check: list what the layout needs but the content doesn't have. Share the gap table with the user before guessing.

Step 4 · Post-fill fact check

After the pages are filled, re-verify against the extraction from Step 3 that nothing was dropped or mutated on the way into HTML:

• Every name, number, date, and metric from the source lands in the document verbatim — short atomic values are never rephrased, rounded, or "improved". Only prose longer than ~80 characters may be rewritten for flow.
• Every image slot resolves: the referenced asset exists in the content set, or the gap is marked in the materials status block. Never ship a broken <img>.
• Anything the source lacks stays marked [DATA NEEDED: description] — a gap is reported, never silently filled.

Fix a mismatch by fixing the page (or asking the user for the missing fact), not by relaxing the check.

Step 5 · Editorial passes (tables, then lines)

Table pass — whenever the document has a table. A kami table separates rows through alignment and breathing room first; rules are quiet guides.

• One chromatic system: table text stays in the neutral ink hierarchy, every rule is var(--border). No category-colored values, brand-colored rules, per-column hues, tinted header, or vertical grid. Carry meaning with weight, signs, and labels.
• Hairline hierarchy: header and total rules 0.6pt, body rules 0.25pt. If the line is noticed before the values, it is too heavy.
• Padding floor: at least 6pt on headers and 5pt on cells. A resume or one-pager may step down once to 5pt / 4pt after the fit loop proves it must; .compact never goes below 3pt / 2.5pt, and is earned (5+ columns, 8+ body rows, or a verified fit constraint), not reflexive.
• Striping is exceptional: start without .striped; add its neutral fill only when 8+ body rows still track poorly at normal viewing size.

Subtractive pass — before handing back. Remove every visual primitive that does not encode data, state, grouping, or a relationship: decorative eyebrow ticks, short cover or contact rules, side bars on headings / quotations / callouts, fake dash bullets. A callout needs only its fill, padding, and type; a quotation only indentation, olive text, and reading space; a section title only type scale and margin. Keep what does real work: table hairlines, chart axes, diagram connectors, full-width region separators, current-state indicators. The test is to hide the line: if meaning, grouping, and navigation survive, delete it and restore the pause with spacing, not with another ornament.

Both passes change geometry. Re-read .pneuma/kami-fit.json afterwards and look at the affected pages with a capture — a removed rule can collapse an intended pause or leave a neighbour visually unanchored.

Fit discipline — the kami authoring loop

Kami is a strict-page medium. The AUTHOR decides how many sheets a document spans by writing that many <div class="page"> blocks. Every page's content must be tuned to fit exactly one sheet — not overflow, not sit half-empty. This is kami's core discipline.

The viewer makes this loop machine-checkable: after every render, it writes a measurement report to .pneuma/kami-fit.json. Read it after every meaningful edit and iterate until every page reports status: "fits".

Report shape:

{
  "content_set": "musk-resume",
  "file": "index.html",
  "paper": { "size": "A4", "orientation": "Portrait", "height_mm": 297,
             "safe": { "top_mm": 18, "side_mm": 16, "bottom_mm": 18 } },
  "pages": [
    { "index": 1, "paper_height_mm": 297, "safe_height_mm": 261, "content_height_mm": 259.4, "delta_safe_mm": -1.6, "status": "fits" },
    { "index": 2, "paper_height_mm": 297, "safe_height_mm": 261, "content_height_mm": 284.5, "delta_safe_mm": 23.5, "status": "overflow" }
  ],
  "summary": { "total_pages": 2, "sparse_count": 0, "loose_count": 0, "fits_count": 1, "bleed_count": 0, "overflow_count": 1 }
}

delta_safe_mm is the rendered content height minus the safe height (paper height minus the top and bottom safe margins). Five statuses:

The loop (run it after every edit; don't wait for the user to point out overflow):

1. Make a content edit.
2. Read .pneuma/kami-fit.json.
3. If overflow_count > 0, or bleed_count > 0 on any page that is not a deliberate full-bleed cover → trim the offending pages → loop to step 2.
4. If sparse_count > 0 and content intent allows → merge or enrich → loop to step 2.
5. When every page is fits — or loose on a body page you judged acceptable, or bleed only on a deliberate full-bleed cover — stop.

That acceptance bar across every page is what you reach before you tell the user the document is ready. Silence on your part implies the fit is passing. See references/cmd-fit.md for edge cases (sparse-on-purpose cover pages, multi-sheet sections, how to choose what to trim).