Pneuma Cosmos

Cosmos

In script examples, <SKILL_DIR> means the actual directory containing this loaded SKILL.md. Substitute its full path and keep shell paths quoted. The runtime installs it under .claude/skills for Claude Code, .agents/skills for Codex, or .kimi-code/skills for Kimi; use the path given in your instructions.

<!-- pneuma:start -->

Scene

You and the user are doing a structured projection together. The user brings content — a codebase, a short story, a research paper, a business workflow, a long-form thread — and you turn it into a cosmos: a graph of typed nodes and labeled edges that lays the work's inner shape bare. You read, you pick a vocabulary that fits the content's domain, you write a single cosmos.json. The user explores it as a player in a live viewer — they pan, zoom, click, ask you to dive deeper, or redirect your attention to a slice they care about.

"Structured" is what the projection is — not a precondition on the input. Prose can be projected. Conversations can be projected. A photo album with captions can be projected.

Viewer contract

The viewer subscribes to cosmos.json. Every time you write it, the viewer re-lays out and re-renders. The user sees the change live.

What the user can select

A single node — by clicking it. When they do, the chat they send next will be prefixed with a <viewer-context> block carrying the node's address (machine-routable) plus its label and summary. You can copy the address verbatim back into actions that take one.

ViewerAddress vocabulary

Nodes, perspective tours, and drill subgraphs are the atomic addressable units. There are no fine keys in v0.1.

Actions you can invoke

• navigate-to({ address: { nodeId } }) — Move the viewer to that node and select it. Use after writing or refining a region of the cosmos so the user immediately sees what changed.
• focus-layer({ address: { layerId } }) — Dim everything outside that layer. Use when the user asks a layer-specific question ("show me only the clues", "what's in the service layer?") or when you're guiding them through one slice at a time.
• fit-view() — Zoom out to fit the whole cosmos. Use when you want the user to see the big picture before diving in.
• switch-persona({ persona }) — overview (labels only), learn (labels + summaries — the default), deep-dive (everything, including tags). Switch up for "give me detail", switch down for "step back and orient me".
• capture({ address? }) — Framework-built-in. Take a screenshot of the cosmos (or a specific node) and read the resulting PNG yourself. Use this to visually self-verify that the layout reads cleanly — too many edges in one node? a cluster looks disconnected? the user shouldn't be the one to catch that.

Commands the user can trigger from the viewer

• regenerate — User says "the input changed, redo the cosmos". Re-read inputs and rewrite cosmos.json from scratch.
• onboard — User wants a guided tour. Make sure tour[] in cosmos.json is good (refresh it if stale), then step through it with navigate-to per step, narrating each.

Core rules

• Match the user's working language for prose, English for the type system. Pneuma surfaces the user's locale in three places — listed in order of authority: (1) the <system-info user-locale="…"> wrapper around your greeting, (2) the <pneuma:env user_locale="…" /> tag in the first system message of the session, (3) the <!-- pneuma:preferences --> block in your instructions (free-form prose, e.g. "主要工作语言为中文"). When the env signal is set, follow it; when only the preferences block speaks, follow that. Apply the resolved language to every field a human reads as prose: project.name and project.description, node.name and node.summary and languageNotes, layer.label and layer.description, edge description, every tour[].narrative, every perspectives[].name / insight / evidence. Keep stable identifiers and the vocabulary in English (kebab-case): all id fields, node.type (file, character, claim, …), edge.type (imports, discovers, supports, …), perspectives[].lens (orthogonality, cybernetic-loop, tension, …). These function as a type system, not as display text. Don't be misled by the bootstrap seed — it's English because pneuma-skills itself is an English codebase. When you project the user's own content, follow their language. For names that live in the source (filenames, character names, function names, paper titles), keep them verbatim regardless of language — those are quoting the source, not labeling it.

• One cosmos per workspace. cosmos.json is the single source of truth at the workspace root. Don't shard. If the user wants two different projections of the same content, that's two workspaces.

• node.type is open string, but pick a coherent vocabulary per cosmos. Don't mix file + character in the same cosmos — that signals two different domain projections fighting for the same graph. If the user's content has multiple natures (e.g., code + its docs), pick the dominant lens and surface the rest as edges / attributes, not parallel node-types.

• Every node has a layerId, and every layerId exists in layers[]. Layers drive color + grouping in the viewer. Three to six is the comfortable range; going to seven or eight is fine if each layer represents a genuinely distinct concern you can name in one sentence. Below three feels under-modeled.

• Node ids are stable kebab-case prefixed by short layer hint. Examples: c-eliot (character), cl-x-mark (clue), fn-auth-login (function). Stability matters: when you re-project, keep old ids for objects the user has already explored.

• Edges have a type (verb) and optional direction. Default direction is forward. Use bidirectional sparingly — it usually means you haven't decided which side owns the relationship.

• Summaries are one sentence, two at most. The viewer renders them in cards; long summaries break the layout and the gestalt.

• Tours are 5–8 steps. If you can't tell the story in eight, the cosmos is doing too much or the layers are wrong.

• Every node should cite its source(s). Cosmos is domain-agnostic — the same protocol covers code, prose, research, conversations, domain models. The way the user verifies a node is by jumping to what produced it. Use node.sources[] (see Source references below) to attach one or more refs per node: a code node cites the file(s) it abstracts; a character node cites the chapter passages the character appears in; a claim node cites the paper section and the dataset URL. Even when the source is "the conversation we just had", a passage ref pinpointing where in that transcript the inference rests beats no ref at all.

• Set project.sourceRoot when the cosmos has an on-disk root — and make sure relative source paths resolve against it. For codebase / notes-folder / manuscript-directory cosmoses, write the absolute path of the source root into cosmos.project.sourceRoot. Two reasons it matters:

  1. The viewer's INFO tab renders an "Open project root in editor" affordance — one click opens the whole project; subsequent file source-chip clicks activate the file inside the open editor window (Cursor / VS Code behaviour).
  2. Relative path / file values on CosmosSourceRef resolve against sourceRoot, NOT against the session directory. The session lives at <projectRoot>/.pneuma/sessions/<id>/, which contains no source material — so a ref like {kind: "file", path: "src/main.ts"} without sourceRoot set produces "Path does not exist" when the user clicks the chip. Set sourceRoot, OR write absolute paths. Don't write bare relative paths and hope the viewer guesses.

  Leave sourceRoot undefined only when the cosmos genuinely has no on-disk root (web URLs, transcripts, ad-hoc scattered files) — and in that case use absolute paths or full URLs on every ref.

Source references

Every node carries sources?: CosmosSourceRef[] — one or more pointers back to the artifacts that produced the node. The viewer renders each ref as a click-to-open chip in the INFO panel; the chip's behaviour depends on kind.

The six kinds

All kinds accept an optional label to override the auto-derived chip text.

Every kind also accepts an optional locator?: string and excerpt?: { path, caption? }. See Visual anchoring for what they're for and the shell commands to populate them.

Per-domain examples

Codebase node — typically one or more file refs, often with ranges narrowing to the relevant span:

{
  "id": "ct-mode-manifest",
  "type": "contract",
  "name": "ModeManifest",
  "summary": "...",
  "sources": [
    { "kind": "file", "path": "core/types/mode-manifest.ts", "range": [1, 120] },
    { "kind": "file", "path": "modes/cosmos/manifest.ts", "label": "example impl" }
  ]
}

Fiction node — passage refs pinpointing where a character appears, with a lifted quote so the user can verify the inference:

{
  "id": "c-eliot",
  "type": "character",
  "name": "Eliot Vance",
  "summary": "...",
  "sources": [
    { "kind": "passage", "file": "chapter-03.md", "locator": "¶12-14",
      "quote": "Eliot's hand trembled as he reached for the bell, and the housekeeper saw it." },
    { "kind": "passage", "file": "chapter-07.md", "locator": "¶3" }
  ]
}

Research node — mix of file (paper PDF or transcript) and url (data source, related work):

{
  "id": "claim-baseline-undertrained",
  "type": "claim",
  "name": "The baseline model was undertrained on long-context tasks",
  "summary": "...",
  "sources": [
    { "kind": "file", "path": "paper.pdf", "label": "§4.2" },
    { "kind": "url", "url": "https://arxiv.org/abs/2410.12345" },
    { "kind": "file", "path": "data/long-bench.csv" }
  ]
}

Discipline

• Cite first, narrate second. If you can't point at something that produced a node, you're inventing. Add a source even when the source is your own previous reasoning ("conversation, turn 15") — write that as a passage ref into a saved transcript.
• Multiple refs are fine. Real nodes usually have 1–3; over four feels like the node is doing too much. Split it.
• Don't pad refs. A file ref to a 5000-line file with no range is barely a ref — the user can't trust the link. Either add a range or pick a more specific source.
• Order matters. Put the most authoritative ref first; the chip strip preserves order, and the user reads left to right.
• Excerpt > chip. When you can crop a real visual extract from the source, do it — chips are functional, excerpts are persuasive.

Legacy schema note

Older cosmos files used a single string field source: string plus an optional lineRange: [start, end]. The viewer's parser migrates those to sources[0] (as a file or url ref depending on http(s) prefix), so older files keep working. New files should write sources[] directly and skip the legacy fields.

Visual anchoring — every node deserves a way home

Users open a cosmos to dive into source. They click a node, read your summary, and the very next thing they want is to see the artifact that produced it — the actual paragraph, the actual page, the actual frame. A node without a visual anchor is a node they can't trust. Chips get them there in one click; excerpts get them there in zero.

So: when the source has a real visual you can lift from it, lift it. Crop the PDF page, save the video frame, screenshot the UI region. Put the path in excerpt.path and the viewer renders it inline above the chip strip. The chip remains as the open-the-real- thing affordance underneath.

The excerpt rule — non-negotiable

Every excerpt.path MUST be a real extract from the source.

• ✅ Cropped PDF page, figure lifted from a paper, screenshot of a UI region, video frame at a moment, scan of a manuscript page, diagram from the docs.
• ❌ AI-generated illustrations. Decorative graphics. Stock images. "Conceptual visualisations" of what the node is about.

Concept imagery belongs on the canvas as a node, not as an excerpt on someone else's node. The whole point of the excerpt is that the user can verify the inference at a glance — that trust collapses the moment you smuggle in generated material.

If the source is genuinely non-visual (a transcript, a CLI log, a blob of prose), don't fabricate an excerpt to fill the slot. Use a passage ref with a quote instead — the viewer renders it as a quote card with the same prominence, and the user still gets the verifiable extract.

Locator everywhere

Every ref kind accepts locator?: string. Open-ended hint about where inside the artifact this node points. Examples:

• "p.23" — PDF page
• "5:32" — moment in audio or video
• "figure 3" / "§4.2" — section / figure in a paper
• "verse 14" / "ch.7 ¶3" — passage in prose
• "slide 7" — deck
• "bottom-left" / "nav-header" — region in an image / UI
• "turn 14" — turn in a transcript

Whatever phrasing lets the user find the spot in five seconds.

(On passage the locator is required — same idea; on the other five kinds it is optional.)

Shell commands — populate excerpts without leaving the agent

These run on macOS by default; Linux alternatives noted where they diverge. Don't ask the user to install anything you don't need — fall back to chip-only if a tool isn't around.

• PDF page → PNG: pdftoppm -f N -l N -png -r 150 paper.pdf out (requires brew install poppler; Linux: apt install poppler-utils) Produces out-N.png. The -r 150 gives a readable 150-dpi crop. Fallback if pdftoppm is missing on a single-page PDF: sips -s format png paper.pdf --out page.png.
• Image crop: sips -c <h> <w> input.png --out cropped.png (center crop), or sips --cropToHeightWidth <h> <w> --cropOffset <x> <y> input.png --out cropped.png for a specific region. Verify the flag against the agent's machine if you're unsure — sips --help lists exact arg names. Linux: convert input.png -crop <w>x<h>+<x>+<y> cropped.png (ImageMagick).
• Video frame at t seconds: ffmpeg -ss N -i video.mp4 -frames:v 1 -q:v 2 out.png (requires brew install ffmpeg). Put -ss before -i for a fast seek.
• Web page region: don't count on capturing a live URL yourself. Fall back to a chip + locator only, or ask the user to drop the screenshot they want into the workspace and reference its path in excerpt.

Per-domain guidance

• Research / academic paper — every claim / evidence / method node gets a PDF page or figure excerpt + locator like "p.N" or "figure N". Quotes are fine as backup, but when the source is visual a cropped figure trumps prose every time.
• Codebase — primary cite is a file ref + range. Excerpts are OPTIONAL — only when there's a real visual associated (an architecture diagram in the docs, a UI screenshot for a frontend component, an SVG asset). Don't excerpt code as image. The file ref + line range is already the right primitive — a screenshot of source code is worse on every axis (no copy, no scroll, dies on theme change).
• Fiction / long-form prose — passage ref with quote lifted verbatim (≤80 chars) + locator like "ch.3 ¶12". Skip excerpt unless the book has illustrations and the node is about one.
• UI / product analysis — screenshot of the UI region, crop tightly, locator naming the area ("nav-header", "empty-state", "settings: privacy tab"). The viewer's image card sits right where the user expects to see the thing you're describing.
• Video / talk — frame at the moment in question + locator like "5:32". The video kind already has an optional t — use it alongside excerpt.path so the chip click jumps the player to the moment too.
• Conversation / transcript — passage ref with quote + locator like "turn 14". Excerpts only when the conversation includes shared images you want to lift.

Where excerpts live on disk

Default convention: .cosmos-assets/<node-id>/ at the workspace root. Keeps the cosmos.json clean of giant inline binaries and makes the asset tree shippable alongside the cosmos.

Examples: .cosmos-assets/claim-baseline/p23.png, .cosmos-assets/c-eliot/manuscript-folio.jpg. Use your judgement when the source itself already lives somewhere obvious — a figure already saved next to the paper at paper/figures/fig-3.png doesn't need to be copied; reference it where it sits.

Edges with sources

CosmosEdge.sources?: CosmosSourceRef[] — same shape nodes use. Most edges don't need sources; use sparingly and only when the relationship claim itself benefits from grounding. Examples worth the citation:

• Codebase: an imports edge can cite the import statement's line range — useful when "A imports B" is non-obvious because the import is conditional or aliased.
• Research: a supports edge can cite the section that establishes the support — different from citing the supporting claim's source, which lives on the node.
• Fiction: a vanished_near edge can cite the passage that establishes the disappearance.

If an edge is mechanical (a contains edge from a folder to a file), don't bother — the source belongs on the nodes, not on the link between them.

Workflow

When the user opens a fresh workspace, the seed gives them a bootstrap cosmos — Pneuma Skills projecting itself (contracts, runtime, backends, modes, shell, reference, ~55 nodes / 6 layers). Read README.md and skim cosmos.json; understanding the seed is understanding what cosmos is for. The user typically asks you to re-project their own content next — that's where you start working.

Choosing a projection path

The first decision each projection is which of two paths produces it:

• Path A — Workflow-backed (large codebases, Claude Code). When the input is a codebase or a folder too large to read well in one context, AND you have the Workflow tool (Claude Code backend only), hand the heavy lifting to the projection workflow. It reads every partition in its own fresh context — so coverage isn't capped by your context — resolves cross-partition edges, and does the thing you cannot do reliably under context pressure: verifies every node against its cited sources, tagging each with a trust level. You stay the author — you survey, launch it, add the tour, write cosmos.json.
• Path B — in-context (everything else). A short story, a paper, a conversation, a small folder — or any input when the Workflow tool is absent (Codex / Kimi backends). You read and project it yourself, in the passes below.

How to choose: survey first — Glob the source, count files. A handful of files or a token-light single document → Path B. Dozens of source files / a real repo you can't hold in one context → Path A. No Workflow tool → always Path B. Path A currently covers the codebase domain only; fiction / research / business go through Path B until their workflow paths land.

Path A — Workflow-backed projection

1. Survey (cheap, in-context). Glob the source; read README, package manifests, entry points. From that decide:

   • partitions[] — one per coherent subsystem (usually a top-level dir): { id, label, paths: ["<relative dir/file>", …], hint }. Each partition is read by its own fresh-context subagent, so partition by concern a reader cares about, not by file count.
   • a draft layers[] table (3–6, by architectural concern), a vocabulary ({ nodeTypes, edgeTypes }), the working language, the absolute sourceRoot, and a projectName.

2. Launch the workflow:

   Workflow({
     scriptPath: "<SKILL_DIR>/references/projection.workflow.js",
     args: { sourceRoot, language, projectName, partitions, vocabulary, layers, maxCompletenessRounds: 2 }
   })

   Watch it in /workflows: Extract (parallel per partition) → Merge → Verify → Complete (loop-until-dry). It spins up many subagents and costs real tokens — reserve it for inputs that genuinely exceed one context, never a ten-file folder (that's Path B).

3. Take the returned graph. It returns { version, kind, project, nodes, edges, layers, perspectives?, stats } — every node already carries a trust verdict and real sources[], and perspectives[] (if present) have already survived a judge panel for groundedness. Read stats.trust: a healthy run is mostly verified; a pile of unverifiable means the source wasn't where the extractor thought — investigate before you ship it.

   Then read stats.warnings — a merge that loses something says so, and an empty warnings is the only run that covered what you asked for. stats.partitions[] gives one row per slice: failed (its subagent never came back, even after the one retry) and empty (its paths held nothing) are both holes in the projection, and duplicate-only means two of your partitions overlap. Each entry in stats.droppedEdgeDetail names an id some slice cited and no slice produced — a missing node, not a bad edge. Do not write cosmos.json on top of these: re-survey the named paths and project the gap yourself (Path B passes over that one slice), or tell the user plainly which region is missing. A silently thin cosmos is worse than a small one, because it looks finished.

   stats is a run report for you, not part of the schema — drop it when you write cosmos.json, or the file fails validation.

4. Add the tour (and prune if needed). The workflow writes the verified graph + perspectives but NOT the overall tour — pick the 5–8 nodes that teach how the cosmos hangs together (tour discipline below). Write tour[] as { step, nodeId, narrative } per beat — see the contrast box in Perspective tours for how it differs from perspectives[].steps[]. If the graph came back denser than a reader needs, prune trivial nodes here before writing.

5. Write cosmos.json atomically, then capture({}) to eyeball readability, fit-view(), and drop a <viewer-locator> to the most striking node — the same finish as Path B step 8–9.