mosage 0.1.0 → 0.8.0

package/skills/apply-comments/SKILL.md

@@ -1,87 +1,74 @@
 ---
 name: apply-comments
-description: 處理作者在 MoSage 介面上留給 AI 的留言。作者說「處理留言」「套用我的留言」「看一下我的意見」「我留了言」「apply comments」時使用。找出所有作者留言（mosage:comment，by=human），依 ai.editMode 以「修改建議」或直接修改的方式處理，然後移除已處理的留言標記。
+description: Use this skill when the user asks to apply, process, or clear the comments they left in the MoSage inspector — phrases like "apply the comments", "apply my edits", "I left notes on the document", "process the markers", "/apply-comments". It finds every `@doc-comment` marker under `docs/`, makes the edit each one asks for, then removes the marker. Do NOT use for authoring new documents — that is `create-doc`.
 ---
 
-# 處理作者留言
+# Apply inspector comments
 
-作者在介面上選取文字、按「留言給 AI」後，留言會以 HTML 註解存進章節檔，放在它所指的區塊（段落、標題、清單、表格…）**正上方**：
+The dev UI's **Inspect** mode lets the user click any element on a page and leave a note. Each note is written into the document source as a marker:
 
-```markdown
-<!-- mosage:comment id=c-3f9a12bc by=human at=2026-09-26T08:12:03Z quote="這一段的第二句"
-太生硬了，改得口語一點，並補一個例子
--->
-這是作者留言所指的那一段……
+```tsx
+<p style={p}>
+  {/* @doc-comment id="c-4591fd61" ts="2026-08-15T15:40:52.644Z" text="<base64url>" */}
+  從 FastMCP 開發、容器化…
+</p>
 ```
 
-- `quote` 是作者選取的文字（可能沒有 —— 那就是針對整個區塊）。
-- 標記下方緊接的那個區塊就是留言的對象。
+The marker is always the **first child of the element the note is about** — that is your anchor. `text` is base64url-encoded JSON: `{"note": "...", "hint": "p"}`.
 
-## 1. 找出留言
+## Step 1 — Find the pending comments
 
 ```bash
-npx mosage status <書> --json     # 看 notes 陣列：kind 為 comment 且 by 不是 ai 的就是作者留言
-grep -rn "mosage:comment" books/<書>/chapters/
+grep -rn "@doc-comment" docs/
 ```
 
-作者沒指定書時，處理所有書裡的作者留言（先告訴作者有幾則、在哪幾本）。沒有任何留言 → 告訴作者並結束。
+If the dev server is running you can read them decoded instead, which is easier:
 
-## 2. 讀懂每一則
-
-- 讀留言所在的整個區塊，以及前後各幾段（「改短一點」要看上下文才知道怎麼改）。
-- 依 `at` 由舊到新處理 —— 後面的留言可能修正前面的。
-- 先讀 `brief.md`、`STYLE.md`，修改要符合風格。
+```bash
+curl -s "http://localhost:5273/__comments?docId=<id>"
+```
 
-## 3. 處理
+That returns `{ comments: [{ id, line, ts, note, hint }] }`. If neither turns anything up, tell the user there are no pending comments and stop.
 
-先看 `ai.editMode`（`books/<書>/book.yaml` 的設定優先，否則看 `mosage.yaml`，預設 `suggest`）。
+## Step 2 — Read each one in context
 
-### suggest（預設）— 提出修改建議，讓作者在介面上決定
+For every marker, read the surrounding element — not just the marked line. A note like *"make this shorter"* is meaningless without the paragraph it sits in. Open the file with `Read` around the marker's line (±40 lines is usually enough) so you can see the element, its styles, and its neighbours.
 
-**不要改原文**。把作者的留言標記**換成**一個修改建議標記，放在同一個區塊的正上方：
+Group comments by document, and handle them **oldest `ts` first** — later notes may refine earlier ones.
 
-```markdown
-<!-- mosage:suggest by=ai note="回應留言：改得口語，加上咖啡店的例子"
-改寫後的**完整段落**（整段，不是只有改的那一句）。
--->
-這是原本的那一段……
-```
+## Step 3 — Make the edit
 
-- 標記內容會**整個取代**下方的區塊。只改一句也要寫出整段，其餘文字保持原樣。
-- 要取代**連續多個區塊**（例如把兩段合併、重寫一整個清單加一段）→ 加上 `span=2`（取代下方 2 個區塊），內容寫出全部新文字，區塊之間空一行。
-- 要**插入新段落**而不取代任何東西 → `span=0`，內容會插在下方區塊之前。
-- `note` 用一句話說明你改了什麼、為什麼；作者會在介面上看到新舊對照，按「接受」或「拒絕」。
-- `id` 可以省略（系統會自動產生）。
+Apply what the note asks for, following the **`doc-authoring`** skill: it owns the type scale, the flow/vertical-budget rules, and the design tokens. In particular:
 
-### direct — 直接修改
+- Edit the element the marker is anchored to. Never reformat the whole file.
+- A note about wording changes the text; a note about weight, color, or size changes the inline style — prefer `var(--od-*)` tokens over new hard-coded values.
+- If the change makes a fixed page overflow, split the page or move the content into the `flow()` section (`references/pagination.md`).
+- If a note is ambiguous ("fix this"), do the smallest reasonable interpretation and say what you assumed at hand-off. Don't guess at a large rewrite.
+- If a note asks for something the framework can't do (per-page orientation, a splitting table), say so in the hand-off and leave the marker in place.
 
-直接改寫原文，然後刪除留言標記。
+## Step 4 — Remove the marker
 
-### 特殊情況
+Delete the marker line for every comment you actually applied. Leave markers you deliberately skipped, and say which ones and why.
 
-- **留言是問題**（「這裡的數據對嗎？」）或**意思不明確** → 不要猜著大改。刪除作者的留言，在同一位置留下 AI 留言回覆：
-  ```markdown
-  <!-- mosage:comment by=ai quote="原本的 quote"
-  關於「這裡的數據對嗎？」：這個數字來自……；如果要更新，請提供新的來源。
-  -->
-  ```
-- **留言要求全書一致的修改**（「全書統一用『使用者』」）→ 找出所有相關位置，每個受影響的區塊各提一個修改建議（suggest 模式）或直接修改（direct 模式）。
-- **無法處理的要求**（例如需要作者提供的資料）→ 保留原留言，並在回報中說明原因。
-
-## 4. 移除已處理的留言標記
+```bash
+# with the dev server running
+curl -s -X DELETE "http://localhost:5273/__comments?docId=<id>&id=<comment-id>"
+```
 
-每一則處理完的作者留言，刪除整個 `<!-- mosage:comment … -->`（包含它後面的換行）。
-在 suggest 模式下，你已經用修改建議標記取代了它。**沒處理的留言要保留。**
+Or delete the `{/* @doc-comment … */}` line directly with `Edit`. Removing it by hand is fine — the marker is a plain JSX comment.
 
-檢查：`grep -rn "mosage:comment" books/<書>/chapters/` 只剩你刻意保留的與 AI 回覆。
+## Step 5 — Verify
 
-## 5. 回報
+- No `@doc-comment` marker remains for an applied note: `grep -rn "@doc-comment" docs/`.
+- The document still compiles: it hot-reloads in the browser; check the terminal for a Vite error.
+- Run the "Self-review before finishing" checklist in `doc-authoring` for any page you touched.
 
-簡短列出，每則一行：
+## Step 6 — Hand off
 
-- 第幾章：留言重點 → 你做了什麼（修改建議／直接修改／回覆了問題）
-- 跳過的留言與原因
+Tell the user, in one short list:
 
-suggest 模式下提醒作者：
+- What you changed, one line per comment.
+- Anything you skipped and why.
+- Any assumption you made on an ambiguous note.
 
-> 請到介面上逐一查看修改建議，按「接受」或「拒絕」。
+Do not restate the whole document.

package/skills/create-doc/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: create-doc
+description: Use this skill when the user wants to create, draft, author, or generate a new document, report, whitepaper, proposal, memo, or spec in this MoSage repo. Triggers on phrases like "write a report about X", "draft a proposal", "make a whitepaper", "create a document", "write up the Q3 results", or when the user asks to add content under `docs/`. Do NOT use for editing the framework itself — only for authoring content inside `docs/<id>/`.
+---
+
+# Create a document in MoSage
+
+This skill owns the **workflow** for drafting a new document. The technical reference — file contract, page canvas, print type scale, vertical budget, tables, TOC — lives in the **`doc-authoring`** skill. Read it before writing code; don't duplicate its rules here.
+
+You only write files under `docs/<id>/`. Never modify `package.json`, `mosage.config.ts`, or existing documents.
+
+**If the user already has the content written as Markdown, don't retype it into JSX.** `mosage import <file.md> --id <id>` produces a real document — `flow()` body, cover, contents, local images copied into the document's assets — which you then refine. Steps 0–2 still apply for the parts the import cannot know (theme, page size, visual direction).
+
+## Step 0 — Pick a theme
+
+List files under `themes/`. If any theme markdown exists (anything other than `README.md`), call `AskUserQuestion` with each theme id as an option plus a final **"no theme — design from scratch"** option. (`AskUserQuestion` holds at most 4 options — with 4+ themes, offer the 3 most relevant plus "no theme"; the auto-added "Other" lets the user name an omitted one.)
+
+- If the user picks a theme: read `themes/<id>.md` end-to-end. Its palette, typography, page setup, and paste-ready components are now authoritative — copy them into the document, and set `meta.theme: '<id>'` in `index.tsx`. Skip the **visual direction** question in Step 2 (the theme already commits to one) and restate the theme name so the user can correct course. Page size comes from the theme's frontmatter unless the user overrides it.
+- If the user picks "no theme", or `themes/` has no theme files: continue unchanged.
+
+## Step 1 — Gather the substance first
+
+A document is judged on content, not layout. Before anything else, establish:
+
+- **Topic and purpose** — what decision or action should this document produce?
+- **Audience** — executives (lead with the recommendation), engineers (lead with the mechanism), clients (lead with the outcome and the price).
+- **Source material** — does the user have data, a draft, notes, a repo, an existing doc? Ask for it. **Never fabricate figures, quotes, citations, or customer names.**
+
+If the request is thin ("write me a report"), make a **separate** `AskUserQuestion` call for topic, audience, and source material before the style questions below. If the topic is already clear, restate your reading of it in the next call so the user can correct course.
+
+## Step 2 — Clarify the shape (MUST ask before writing code)
+
+Ask these in a single `AskUserQuestion` call (multi-question form). Skip a question only when the user's message already answers it unambiguously — and restate the assumption if you skip.
+
+1. **Document type** — propose 3 concrete types that fit *this* topic, each with what it implies structurally. Not bare labels:
+   - *"our Q3 infrastructure numbers"* → **internal review** (summary, metrics, incidents, actions) · **exec brief** (2 pages, recommendation-first) · **post-incident deep dive** (timeline, root cause, remediation)
+   - *"our new product for enterprise buyers"* → **whitepaper** (problem, approach, evidence, references) · **sales proposal** (scope, deliverables, timeline, price) · **one-pager** (positioning + proof + CTA)
+   Mark the best fit "(Recommended)".
+2. **Length** — offer brackets: 2–4 pages (brief), 5–10 (standard report), 11–25 (deep dive). The auto-added "Other" covers custom counts.
+3. **Page size** — A4 portrait (default) · A4 landscape (data-heavy, wide tables) · B4 or A3 (plans, posters, very wide tables). The only sizes are A4, B4 and A3, each portrait or landscape. Skip if the user already said.
+4. **Visual direction** — 3 options tailored to the audience, each naming a palette + typographic cue: e.g. **corporate neutral** (near-white, single blue accent, sans throughout) · **editorial serif** (serif headings, generous leading, hairline rules) · **technical mono-accent** (mono labels, dense tables, monochrome + one signal color).
+
+Ask about brand colors, a logo, or required sections only if still unclear afterwards.
+
+## Step 3 — Pick a doc id
+
+**kebab-case**, short, descriptive: `q3-infra-review`, `acme-proposal-2026`, `auth-migration-rfc`. Check `docs/` for collisions.
+
+## Step 4 — Outline before code
+
+Write the page plan first — one line per page, with its role. Typical structures:
+
+| Type | Page plan |
+| --- | --- |
+| Report | Cover · Contents · Executive summary · Method · Findings (n pages) · Risks · Recommendations · Appendix |
+| Whitepaper | Cover · Abstract · Problem · Approach · Evidence · Comparison · Conclusion · References |
+| Proposal | Cover · Summary · Scope · Deliverables · Timeline · Pricing · Terms · Next steps |
+| RFC / spec | Summary · Motivation · Design · Alternatives · Migration · Open questions |
+| Memo | Header block · Context · Recommendation · Rationale · Next steps |
+
+Rules for the plan:
+
+- **Page 1 is the cover**; if the doc is over ~6 pages, **page 2 is `<TableOfContents />`**. Both are fixed pages; everything after them belongs in one `flow()` section so the framework paginates the body.
+- The executive summary must stand alone — a reader who reads only that page should know the conclusion and the ask.
+- One section per page unless a section is genuinely two paragraphs long.
+- Plan the body as a **sequence of sections**, not as a page count — `flow()` decides how many pages that becomes. Only estimate the vertical budget for the fixed pages (cover, contents, dividers); see `doc-authoring` → `references/pagination.md`.
+
+Show the user the page plan and the estimated page count before writing the file if the document is over ~8 pages — restructuring a 20-page doc after the fact is expensive.
+
+## Step 5 — Commit to a visual direction
+
+Declare a top-level `export const design: DesignSystem` and consume `var(--od-*)` everywhere. Print constraints (white background, ≥13px body, one accent) are in `references/design-system.md` — read it before choosing the palette. If a theme was picked in Step 0, copy its `design` const verbatim instead of inventing one.
+
+Keep the const a plain object literal: the dev UI's **Design panel** parses and rewrites it, and a spread or a value read from another constant makes the document untweakable (see "Writing for the Design panel" in `doc-authoring`).
+
+Define the shared page shell, heading styles, and the running footer **once** as local constants/components at the top of `index.tsx`, then reuse them on every page. Copy-pasted page styling is how documents drift.
+
+## Step 6 — Write `docs/<id>/index.tsx`
+
+Read **`doc-authoring`** first — file contract, canvas, type scale, headings/outline, TOC, page numbers, and a starter template are all there.
+
+While writing:
+
+- Real `<h1>/<h2>/<h3>` for every section title, so the outline and TOC populate.
+- `<TableOfContents />` for the contents page. Never hand-write one.
+- `useDocPageNumber()` / `useDocPageCount()` for the footer. Never hardcode.
+- Put body content in one `flow(<>…</>, { footer: Footer })` section; mark captions `data-od-keep-with-previous`. Only run budget math for fixed pages.
+- Where the user must supply data, leave `<ImagePlaceholder hint="…">` or an explicit `TODO:` in the copy — never invent numbers.
+
+## Step 7 — Self-review
+
+**Run `mosage check <id>` first.** You cannot see the sheets you produced; it renders them at true page size and reports clipped content, blank pages, stranded headings, and unreadable type, each with a source location. Fix every error before moving on.
+
+Then run the checklist in `doc-authoring` ("Self-review before finishing"), and re-read the prose once as a reader: does the summary state the conclusion? Does every claim have a source?
+
+## Step 8 — Hand off
+
+Tell the user:
+
+- The doc id and file path.
+- That the dev server hot-reloads — open `http://localhost:5273/d/<id>` (or refresh the home page).
+- **Every placeholder and `TODO:` you left**, and what data each one needs.
+- That "Export PDF" in the toolbar prints at the true page size, and "HTML" downloads a self-contained copy — or `mosage export <id>` for the same files without a browser.
+- That the **Design** button live-tweaks the palette and type scale and writes the result back to the source, and that images they want to drop in go through the **Assets** page.
+
+Don't run the dev server yourself unless asked.

package/skills/create-theme/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: create-theme
+description: Use this skill when the user wants to create, draft, author, or extract a document theme in this MoSage repo — a reusable house style for reports, proposals, or memos. Triggers on phrases like "create a theme", "make a company template", "extract a theme from <doc>", "match our brand guidelines". Produces two paired files under `themes/` — `<id>.md` (palette, typography, page setup, paste-ready Title/Footer/Table components) and `<id>.demo.tsx` (a runnable two-page demo the Themes gallery previews). Do NOT use for editing real documents — only for authoring the theme bundle.
+---
+
+# Create a document theme
+
+A **theme bundle** under `themes/` is two paired files describing a reusable house style:
+
+1. `themes/<id>.md` — agent-facing documentation: palette, typography, page setup, paste-ready components. This is what `create-doc` reads when the author picks the theme.
+2. `themes/<id>.demo.tsx` — a runnable two-page mini-document (a normal document module: `export default DocPage[]`) that shows the theme in use. The Themes gallery renders it as the live preview.
+
+Both files share the same stem so the runtime pairs them automatically.
+
+A theme is **distinct from a document's `design` const**:
+
+| | What it is | Who reads it |
+| --- | --- | --- |
+| `themes/<id>.md` | Authoring-time direction, copied into a real document | `create-doc`, you |
+| `themes/<id>.demo.tsx` | A preview, not a real document (never appears in the documents list) | The Themes gallery |
+| `export const design` in `docs/<id>/index.tsx` | Runtime tokens the Design panel can live-tweak and write back | The runtime |
+
+You only write `themes/<id>.md` and `themes/<id>.demo.tsx`. Never modify real documents or config. Read the **`doc-authoring`** skill first — the page canvas, print type scale, and vertical budget it defines are what your overrides are stated against.
+
+## Step 1 — Identify the input source
+
+A theme can come from any combination of:
+
+- **Brand material** — a style guide PDF, brand colors, a letterhead, existing reports (paths or URLs).
+- **Free-text description** — prose describing palette, fonts, and feel.
+- **An existing document** — `docs/<id>/index.tsx` whose look should be lifted into a reusable theme.
+
+If the user's message already names the inputs, proceed. Otherwise call `AskUserQuestion` (multi-select) and ask follow-ups (paths, doc id, prose) only as needed.
+
+## Step 2 — Gather raw inputs
+
+- **Images / PDFs**: read each path with `Read` (it accepts images and PDFs). Note hex colors, heading/body faces and weights, margin rhythm, rule weights, table styling, and any recurring chrome (letterhead, footer rule, page-number position).
+- **Text**: extract explicit tokens (hex codes, font names, "20mm margins") and implicit tone ("conservative", "editorial", "technical"). Resolve vague language into concrete numbers before writing.
+- **Existing document**: read `docs/<id>/index.tsx` and pull the `design` const, the shared `page`/`h1`/`h2` style objects, the running `Footer`, table cell components, and the callout style.
+
+When inputs disagree (brand deck says navy, the sample report is black), ask which wins.
+
+## Step 3 — Pick a theme id
+
+**kebab-case**, short, descriptive: `acme-corporate`, `editorial-serif`, `technical-brief`, `board-memo`. Check `themes/` for collisions.
+
+## Step 4 — Write `themes/<id>.md`
+
+Keep this exact section order; adapt the bodies.
+
+````markdown
+---
+name: <Human title, e.g. "Acme Corporate">
+description: <one-line elevator pitch>
+pageSize: <A4 | B4 | A3>
+mode: <light | dark — light for anything that prints>
+---
+
+# <Theme name>
+
+## When to use
+
+<Two sentences: which document types this fits, and which it doesn't.>
+
+## Palette
+
+| Role   | Value     | Notes                                   |
+| ------ | --------- | --------------------------------------- |
+| bg     | `#ffffff` | sheet background — keep near-white       |
+| text   | `#16181d` | body copy                                |
+| muted  | `#6b7280` | captions, footers, secondary cells       |
+| accent | `#1d4ed8` | section numbers, rules, chart series     |
+| rule   | `#e5e7eb` | table borders, hairlines, dot leaders    |
+
+Extra colors outside the `DesignSystem` shape (status green/amber/red, chart series) go in a
+"Supporting colors" list below the table.
+
+## Typography
+
+- Heading font: `<stack>` — weight <n>.
+- Body font: `<stack>` — weight 400.
+- Mono font: `<stack>` — tables of code/IDs only.
+- Webfont import (omit for system stacks): `<stylesheet URL>` — load per `references/design-system.md` in `doc-authoring`.
+- Type scale (px at 96dpi): title <n> · h1 <n> · h2 <n> · h3 <n> · body <n> · caption <n>.
+
+## Page setup
+
+- Page size: A4 portrait (794 × 1123 px).
+- Margin: <n> px on all sides (<n> mm).
+- Leading: <n>.
+- Running footer: <what it shows, where it sits>.
+- Cover: <centered / bottom-aligned, what it carries>.
+
+## Design const
+
+Paste-ready — this is what a document using the theme declares:
+
+```tsx
+export const design: DesignSystem = {
+  palette: { bg: '…', text: '…', muted: '…', accent: '…', rule: '…' },
+  fonts: { heading: '…', body: '…', mono: '…' },
+  typeScale: { title: 44, h1: 28, h2: 20, h3: 16, body: 14, caption: 10 },
+  margin: 76,
+  leading: 1.55,
+  radius: 6,
+};
+```
+
+## Fixed components
+
+Paste-ready. Copy verbatim into a document using this theme.
+
+### Page shell + headings
+
+```tsx
+const page = { /* … */ } as const;
+const h1 = { /* … */ } as const;
+const h2 = { /* … */ } as const;
+```
+
+### Running footer
+
+Read the page number from `useDocPageNumber()` / `useDocPageCount()` — never hardcode it.
+
+```tsx
+const Footer = () => { /* … */ };
+```
+
+### Table
+
+```tsx
+const Th = ({ children }: { children: React.ReactNode }) => /* … */;
+const Td = ({ children }: { children: React.ReactNode }) => /* … */;
+```
+
+Include a callout and a stat component when the theme calls for them.
+
+## Rules
+
+- <3–6 bullets a document must follow to stay on-theme: what never appears, how sections are numbered, whether the cover carries a logo, table style, figure captions.>
+````
+
+## Step 5 — Write `themes/<id>.demo.tsx`
+
+A normal document module — **two pages**: a cover and one content page that exercises the theme's headings, body copy, a table, and the running footer.
+
+```tsx
+import { type DesignSystem, type DocPage, useDocPageCount, useDocPageNumber } from 'mosage';
+
+export const design: DesignSystem = { /* the same const as in the .md */ };
+
+const Cover: DocPage = () => ( /* … */ );
+const Content: DocPage = () => ( /* … */ );
+
+export default [Cover, Content] satisfies DocPage[];
+```
+
+Rules for the demo:
+
+- **No `meta` export** — the demo is not a real document and must not carry `createdAt` or a title that implies it is.
+- Two pages, no more. The gallery renders the first; the theme detail page renders both.
+- Use placeholder copy that shows the type scale honestly (a real heading, a real paragraph, a real 4-row table) — not lorem ipsum blocks that hide how the theme handles wrapping.
+- Respect the vertical budget from `doc-authoring` → `references/pagination.md`. A demo that overflows teaches the wrong lesson.
+- Keep it self-contained: no asset imports, no webfont the `.md` didn't declare.
+
+## Step 6 — Self-review
+
+- [ ] Both files exist and share the same stem.
+- [ ] Frontmatter has `name`, `description`, `pageSize`, `mode`.
+- [ ] The `design` const in the `.md` and in the demo are identical.
+- [ ] The palette background is white or near-white (see `references/design-system.md` — dark documents print badly).
+- [ ] Body type ≥ 13px; caption ≥ 9px.
+- [ ] The footer pulls page numbers from the hooks.
+- [ ] Every "paste-ready" component actually compiles as written — no `…` left in the code blocks.
+- [ ] The demo fits its pages.
+- [ ] Nothing outside `themes/` was written.
+
+## Step 7 — Hand off
+
+Tell the user:
+
+- The theme id and both file paths.
+- That it shows up under **Themes** in the dev UI (`http://localhost:5273/themes/<id>`).
+- That new documents can adopt it by setting `meta.theme: '<id>'`, which adds the back-link chip — and that `create-doc` will now offer it as a choice.

package/skills/current-doc/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: current-doc
+description: Resolve which document, page, and (optionally) selected element the user is currently viewing in the mosage dev server. Consult this whenever the user references "this page", "this document", "this element", "the page I'm on", "the report I'm looking at", or any deictic reference to document content without naming it. Re-read `node_modules/.mosage/current.json` at the start of every such turn — the user navigates between turns, so a value you read earlier in the conversation is almost certainly stale.
+---
+
+# Where is the user right now?
+
+When the user says "fix this page", "tighten this heading", or "the report I'm looking at", they almost never name the document id, page number, or element — they mean wherever they are in the dev viewer. Before asking "which document?" or "which element?", check the file the dev server writes on every navigation and inspector pick.
+
+## Re-read on every deictic turn — never reuse a prior read
+
+`current.json` is a live cursor, not a fact about the conversation. The user moves between documents, pages, and elements freely between your turns — including while you were doing other work. **Read the file fresh at the start of every new turn that uses a deictic reference**, even if:
+
+- you already read it earlier in this same conversation,
+- you just finished editing the document it pointed to,
+- the user's new message sounds like a continuation ("now make it bigger", "also fix this one", "keep going").
+
+A "continue editing" follow-up is exactly the case where the user has likely just scrolled to a different page or picked a different element. Trusting your last read here will silently edit the wrong sheet. Re-read, compare `docId` / `pageIndex` / `selection` against what you used last time, and act on the new values.
+
+## How to read it
+
+```
+node_modules/.mosage/current.json
+```
+
+Path is relative to the project root (the user's `cwd`, the directory that contains `docs/` and `package.json`). Use the `Read` tool. The file is JSON.
+
+## What you get
+
+```json
+{
+  "docId": "q3-review",
+  "pageIndex": 2,
+  "pageNumber": 3,
+  "totalPages": 8,
+  "docTitle": "Q3 Review",
+  "pagePath": "docs/q3-review/index.tsx",
+  "selection": {
+    "line": 42,
+    "column": 6,
+    "tagName": "h2",
+    "text": "Availability"
+  },
+  "updatedAt": "2026-08-17T14:32:11.123Z"
+}
+```
+
+- `docId` — folder name under `docs/`. Use as-is for any `/__docs/<id>/...` API or as the URL segment (`/d/<docId>`).
+- `pageIndex` — 0-based **rendered** page index.
+- `pageNumber` — 1-based, for talking to the user ("page 3 of 8").
+- `totalPages` — how many sheets the document currently renders to.
+- `pagePath` — relative path to the document source. Hand straight to `Read` / `Edit`.
+- `selection` — `null` if nothing is selected. Otherwise, the JSX element the user picked in the inspector overlay:
+  - `line` (1-indexed) and `column` (0-indexed) point to the JSX opening tag inside `pagePath`. This is the canonical handle — match against the source line, not the rendered DOM.
+  - `tagName` is the rendered DOM tag, lowercased (`"h1"`, `"p"`, `"td"`).
+  - `text` is a trimmed snippet (≤120 chars) of the element's `textContent`, useful to confirm you are looking at the right node.
+  - Selection auto-clears whenever the user moves to a different document or page.
+- `updatedAt` — ISO timestamp of the last navigation or selection change. Use it to detect staleness.
+
+## Rendered pages are not entries in the default export
+
+This is the one thing that differs from a slide deck, and getting it wrong means editing the wrong thing.
+
+`export default [Cover, Contents, flow(<>…</>)]` has three *entries*, but may render to twelve *sheets* — the framework measures a `flow()` section and packs it across as many pages as it needs. So:
+
+- **`pageIndex` indexes rendered sheets, not the array.** Do not use it to subscript the default export.
+- To find what to edit, prefer `selection` (it points at real source coordinates), then the page's visible text, then the surrounding heading.
+- If the user is on a flow page and there is no selection, identify the content by what they can see — read the source and match the prose — rather than counting array entries.
+- A fixed `DocPage` component *is* one sheet, so for documents made only of fixed pages the index does line up. Confirm with `pagePath` before relying on that.
+
+## When to use this
+
+- The user references the current document/page deictically: "this", "here", "the page I'm on", "what I'm looking at".
+- The user references a specific element: "this heading", "this table", "tighten this", "make this smaller". If `selection` is non-null, that's the element they mean.
+- Before asking "which document?" or "which page?" as a clarifying question — check this file first.
+- Before guessing from `git log`, recently-edited files, or the newest folder under `docs/`.
+
+## When NOT to use this
+
+- The user names a document explicitly ("edit `q3-review`") — use that name directly.
+- The `apply-comments` workflow already finds its own targets via `@doc-comment` markers; it does not need this skill.
+- For listing or discovering documents — read `docs/` directly.
+
+## Staleness — verify before acting
+
+`updatedAt` is the last time the user navigated. Treat it like a cache:
+
+- **Fresh (under ~5 minutes old)**: trust it. Open `pagePath`, do the work.
+- **Older than ~5 minutes**: confirm with the user before editing. The dev server may not be running; the user may have switched contexts.
+- **Hours/days old**: ignore it. Ask which document they mean.
+
+A *newer* `updatedAt` than the one you saw last turn is the normal signal that the user has moved — switch to the new `docId` / `pageIndex` / `selection` without asking.
+
+## When the file is missing
+
+- The dev server has not been opened on a document yet, or has never run. A static build never writes it.
+- Don't create the file or guess. Ask which document they mean, or suggest they open it in the dev server first.
+
+## Example — page-level reference
+
+User: "tighten the spacing on this page"
+
+1. Read `node_modules/.mosage/current.json`.
+2. Check `updatedAt` is recent.
+3. Read `pagePath` (e.g. `docs/q3-review/index.tsx`).
+4. Work out what is on `pageNumber` — by the selection, or by matching visible content, remembering that a flow section spans many sheets.
+5. Consult the `doc-authoring` skill for the spacing and vertical-budget rules, then edit in place.
+
+If `current.json` is missing or stale, ask: "Which document and page should I tighten? The dev server hasn't published a current page recently."
+
+## Example — element-level reference
+
+User: "make this bigger"
+
+1. Read `node_modules/.mosage/current.json`.
+2. If `selection` is non-null, that is the element. Read `pagePath`, jump to `selection.line`, and find the JSX opening tag near that line/column. Confirm against `selection.text` and `tagName`.
+3. Consult `doc-authoring` for the print type scale before editing — a size that looks fine on screen can print below the legibility floor.
+4. Edit the JSX node in place.
+
+If `selection` is null, fall back to the page-level flow above — and consider asking "which element?", since the user used a deictic but hasn't picked one in the inspector.