# Pneuma Doc > Pneuma Doc Mode workspace guidelines. Use for ANY task in this workspace: writing, editing, creating documents, reports, articles, READMEs, notes, outlines, research summaries, translations, restructuring, formatting, or any markdown content. This skill defines how the live-preview environment works and how to edit effectively. Consult before your first edit in a new conversation. - Skill: `pandazki/pneuma-doc` (Agent Skill) - Install (CLI): `npx skillmds@latest add pandazki/pneuma-doc` - Raw SKILL.md: https://api.skillmd.com/api/skills/pandazki/pneuma-doc/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: pandazki (https://skillmd.com/u/pandazki) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/pandazki/pneuma-doc --- # Pneuma Doc Mode — Document Editing Skill You are working in Pneuma Doc Mode — a WYSIWYG markdown editing environment where the user views your edits in real-time in a browser preview panel. ## Core Principles 1. **Act, don't ask**: For straightforward edits, just do them. Only ask for clarification on ambiguous requests 2. **Incremental edits**: Make focused changes — the user sees each edit live as you make it 3. **Preserve structure**: Don't reorganize content unless explicitly asked 4. **Quality markdown**: Use proper GFM conventions consistently ## Working with the viewer The user watches a live markdown preview while you edit. Treat the viewer as a shared surface: read what they're looking at, drop them locator cards back to the result, and reach for the scaffold action only when they want a clean slate. ### Reading what the user sees Each user message may be preceded by a `` block describing the panel state, and a `` block describing what they just clicked. Use these to resolve deictic phrases like "this section", "here", "that heading". Example context: ``` [Context: file "README.md"] [User selected: heading (level 2) "Installation"] Address: {"file":"README.md","heading":"Installation","lineRange":[40,72]} ``` When you see the above and the user says "tighten this section up", they mean the `## Installation` heading and the prose underneath it in `README.md`. Edit that file directly — don't ask which one. The `Address:` line is a machine-readable ViewerAddress — copy it straight into a `` card to point back at the same object. If no `` is attached, the user hasn't selected anything specific; default to the most recently edited file or ask only when the request is genuinely ambiguous. ### ViewerAddress — naming an object in the document A **ViewerAddress** is the one JSON shape that names "which object in the document": it is what a `` card points at and what a `` selection reports back to you. Doc's vocabulary: | Key | Granularity | Meaning | |---|---|---| | `file` | coarse | The document path relative to the workspace root (`notes.md`, `docs/README.md`). | | `heading` | fine | The text of the selected heading (`"Installation"`) — present only when a heading element is selected. | | `lineRange` | fine | `[startLine, endLine]` — the source line range of the selected block. | A selection in `` hands you a ready-made ViewerAddress on its `Address:` line — copy that JSON straight back. Line ranges shift as the document is edited, so prefer `heading` as the durable handle when one is available. ### Locator cards After creating or editing a document, post a `` card at the end of your reply so the user can jump straight to the result. The `address` attribute is a ViewerAddress — locators navigate the user to a **document**, so use the coarse `file` key. Examples: ``` ``` ``` ``` One card per file you touched is plenty. Use a label that names what the user will find when they click — "Open the new draft" beats "View file". ### Viewer actions The viewer exposes one agent-invocable action: `scaffold`. Call it with a POST to `$PNEUMA_API/api/viewer/action`: ```bash curl -X POST "$PNEUMA_API/api/viewer/action" \ -H "Content-Type: application/json" \ -d '{ "actionId": "scaffold", "params": { "files": "[{\"name\":\"intro.md\",\"heading\":\"Introduction\"},{\"name\":\"methods.md\",\"heading\":\"Methods\"},{\"name\":\"results.md\",\"heading\":\"Results\"}]" } }' ``` The browser will surface a confirmation prompt before the scaffold runs. ### Scaffold `scaffold` initializes the workspace with empty markdown files. It clears only the currently viewed files, then writes one file per entry in `files`. - **`files`** (optional): a JSON-encoded array of `{ name, heading? }`. `name` is the filename (with or without `.md`); `heading` becomes the H1 inside the new file. Use scaffold only when the user explicitly asks to start fresh — "wipe these and start over", "set up an outline with these chapters", "blank workspace with three files for X / Y / Z". For everyday additions, just `Write` a new `.md` file directly. Scaffold requires user confirmation in the browser, so don't fire it speculatively. ## File Convention - The workspace contains markdown files (`.md`) - Edit existing `.md` files or create new ones as requested - Use standard GitHub-Flavored Markdown (GFM) - One document per file — separate topics keep the workspace navigable and let the viewer show clean file tabs ## Editing Guidelines - Use the `Edit` tool (preferred) for surgical changes to existing content - Use the `Write` tool for creating new files or full rewrites - Make focused, incremental edits — the user sees changes live, so each edit should leave the document in a valid state - Preserve existing content structure unless asked to reorganize — the user chose that structure deliberately ## Constraints - Do not create non-markdown files unless explicitly asked - Do not modify `.claude/` directory contents — managed by the runtime, your edits would be overwritten on next session - Do not run long-running background processes - Do not ask for confirmation before simple edits — just do them. The user sees your edits live and can course-correct immediately