@inkeep/open-knowledge 0.6.0-beta.9 → 0.6.0

package/dist/THIRD_PARTY_NOTICES.md

@@ -1510,7 +1510,7 @@ Homepage: https://github.com/Brooooooklyn/canvas
 
 Copyright (c) 2020 lynweklm@gmail.com
 
-### `@napi-rs/keyring@1.2.0`
+### `@napi-rs/keyring@1.3.0`
 Homepage: https://github.com/Brooooooklyn/keyring-node
 
 Copyright (c) 2020 N-API for Rust
@@ -2459,6 +2459,11 @@ Homepage: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/p
 
 Copyright (c) Microsoft Corporation.
 
+### `@types/react@19.2.14`
+Homepage: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/react
+
+Copyright (c) Microsoft Corporation.
+
 ### `@types/statuses@2.0.6`
 Homepage: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/statuses
 
@@ -2489,6 +2494,11 @@ Homepage: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/v
 
 Copyright (c) Microsoft Corporation.
 
+### `@types/vimeo__player@2.18.3`
+Homepage: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/vimeo__player
+
+Copyright (c) Microsoft Corporation.
+
 ### `@types/yargs@17.0.35`
 Homepage: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/yargs
 
@@ -2499,6 +2509,11 @@ Homepage: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/y
 
 Copyright (c) Microsoft Corporation.
 
+### `@u-wave/react-vimeo@0.9.12`
+Homepage: https://github.com/u-wave/react-vimeo#readme
+
+Copyright (c) 2016 Renée Kooi
+
 ### `@uiw/codemirror-theme-basic@4.25.9`
 Homepage: https://uiwjs.github.io/react-codemirror/#/theme/data/basic/light
 
@@ -2514,6 +2529,11 @@ Homepage: https://github.com/upsetjs/venn.js
 
 Copyright (c) 2013 Ben Frederickson Copyright (c) 2021 Samuel Gratzl
 
+### `@vimeo/player@2.30.4`
+Homepage: https://github.com/vimeo/player.js
+
+Copyright (c) 2016 [Vimeo](https://vimeo.com)
+
 ### `accepts@2.0.0`
 Homepage: https://github.com/jshttp/accepts
 
@@ -2913,6 +2933,11 @@ Homepage: https://mths.be/cssesc
 
 _(No LICENSE file in package; SPDX identifier in `package.json` is the sole declared grant.)_
 
+### `csstype@3.2.3`
+Homepage: https://github.com/frenic/csstype
+
+Copyright (c) 2017-2018 Fredrik Nicol
+
 ### `cytoscape@3.33.2`
 Homepage: http://js.cytoscape.org
 
@@ -4265,6 +4290,11 @@ Homepage: https://github.com/inspiredware/napi-build-utils#readme
 
 Copyright (c) 2018 inspiredware
 
+### `native-promise-only@0.8.1`
+Homepage: http://github.com/getify/native-promise-only
+
+_(No LICENSE file in package; SPDX identifier in `package.json` is the sole declared grant.)_
+
 ### `negotiator@1.0.0`
 Homepage: https://github.com/jshttp/negotiator
 
@@ -5501,6 +5531,11 @@ Homepage: https://github.com/BerkeleyTrue/warning
 
 Copyright (c) 2013-present, Facebook, Inc.
 
+### `weakmap-polyfill@2.0.4`
+Homepage: https://github.com/polygonplanet/weakmap-polyfill
+
+Copyright (c) 2015-2021 polygonplanet
+
 ### `web-namespaces@2.0.1`
 Homepage: https://github.com/wooorm/web-namespaces
 
@@ -6262,6 +6297,7 @@ The following MIT-licensed packages are patched in this repository via Bun's `pa
 | Package | Patch file |
 | --- | --- |
 | `@handlewithcare/remark-prosemirror@0.1.5` | `patches/@handlewithcare%2Fremark-prosemirror@0.1.5.patch` |
+| `@pierre/trees@1.0.0-beta.3` | `patches/@pierre%2Ftrees@1.0.0-beta.3.patch` |
 | `@tiptap/extension-drag-handle@3.22.3` | `patches/@tiptap%2Fextension-drag-handle@3.22.3.patch` |
 | `@tiptap/y-tiptap@3.0.3` | `patches/@tiptap%2Fy-tiptap@3.0.3.patch` |
 | `react-medium-image-zoom@5.4.3` | `patches/react-medium-image-zoom@5.4.3.patch` |

package/dist/assets/skills/discovery/SKILL.md

@@ -3,7 +3,7 @@ name: open-knowledge-discovery
 description: "Read when the user asks what Open Knowledge is, wants to install it on a repository, wants to share an Open Knowledge project with collaborators, or asks how `ok init` / `ok install-skill` / OK Desktop set up a project. Do NOT load to perform Open Knowledge reads/writes — the runtime guidance for editing markdown inside an initialized OK project ships as a separate project-local skill at `.claude/skills/open-knowledge/` whenever `ok init` runs. If the user appears to be editing markdown inside a `.ok/` project and this is the only OK skill loaded, advise them to re-run `ok init` to install the project-local skill."
 compatibility: "Any agent host — no MCP server required. Pure discovery + install guidance."
 metadata:
-  version: "0.6.0-beta.9"
+  version: "0.6.0"
   author: "Inkeep"
   repository: "https://github.com/inkeep/open-knowledge"
 ---

package/dist/assets/skills/project/SKILL.md

@@ -3,7 +3,7 @@ name: open-knowledge
 description: "MUST invoke before reading or editing any `.md` / `.mdx` file, and before any `mcp__open-knowledge__*` tool call (`exec`, `search`, `write_document`, `edit_document`, and the rest). This skill is installed into the repository by `ok init`, so its presence alone means this is an Open Knowledge project — its runtime contract governs every markdown file here, with no need to probe for a `.ok/` directory. Authoritative agent-runtime contract; supersedes the overlapping MCP server `instructions` echo."
 compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires Open Knowledge MCP server + code execution."
 metadata:
-  version: "0.6.0-beta.9"
+  version: "0.6.0"
   author: "Inkeep"
   repository: "https://github.com/inkeep/open-knowledge"
 ---
@@ -19,17 +19,18 @@ Open Knowledge (OK) is a markdown-CRDT collaboration platform exposed via MCP. T
 
 1. **Reads:** `exec("cat …")` for a single doc, `exec("ls -A …")` for a directory (with folder defaults + template menu), `exec("grep …")` for literal, `search` for ranked retrieval. Native `Read` / `Grep` only on source code (`.ts` / `.py` / …), never on in-scope `.md` / `.mdx`.
 2. **Writes:** `write_document` for new or full-replace, `edit_document` for body-only find/replace, `edit_frontmatter` for 1-2 frontmatter keys (JSON Merge Patch — preferred). Full frontmatter rewrites use `write_document({ position: "replace" })`. `edit_document` rejects frontmatter (HTTP 400).
-3. **Preview:** every OK tool response carries the preview URL (`ui.baseUrl` on reads, `previewUrl` on writes). Navigate your in-app browser to it from the first response you see; refresh from later responses if Electron/UI restarted. Surface to the user on a `start-ui` warning (no UI running). Don't `preview_screenshot` after every edit.
+3. **Preview:** every OK read/write response carries a route-only `previewUrl` (`/#/<doc>`, no host:port). If you have a `preview_*` tool, call `preview_start("open-knowledge-ui")`; otherwise call `get_preview_url` once for the full browser URL and open it in your own in-app browser. Surface to the user on a `start-ui` warning (no UI running). Don't `preview_screenshot` to confirm edits — the CRDT tool response is the confirmation.
 4. **Workflow tools** (`ingest` / `research` / `consolidate` / `discover`) return procedural guides, not data. Use them when the work fits the layer; follow their numbered steps.
 
 Everything below is depth. Read on demand.
 
-## Tool index — 17 tools
+## Tool index — 22 tools
 
 The full MCP surface, grouped by risk-level. Every tool's `kind` / `action` set is single-risk-level (never a read and a write behind one discriminator).
 
-- **Reads** — `exec` (primary; shell-style `cat`/`ls`/`grep`/`find` with frontmatter + backlink + history enrichment), `search` (ranked, BM25 + recency), `get_history` (versions for a doc), `links` (`kind: 'backlinks'|'forward'|'dead'|'orphans'|'hubs'|'suggest'`), `get_config` (resolved config), `get_components` (canonical component schemas).
+- **Reads** — `exec` (primary; shell-style `cat`/`ls`/`grep`/`find` with frontmatter + backlink + history enrichment), `search` (ranked, BM25 + recency), `get_history` (versions for a doc), `links` (`kind: 'backlinks'|'forward'|'dead'|'orphans'|'hubs'|'suggest'`), `get_config` (resolved config), `get_components` (canonical component JSX schemas), `get_authoring_palette` (markdown-native authoring forms + themed `html preview` embed starters + theme tokens), `get_preview_url` (browser-reachable preview URL on demand).
 - **Writes** — `write_document` (new or full-replace; supports `template:` instantiation), `edit_document` (body-only find/replace), `edit_frontmatter` (1-2 keys via RFC 7396 JSON Merge Patch — preferred), `delete_document`, `rename` (probes file vs folder; rewrites referrers), `version` (`action: 'save'|'rollback'`), `folder_config` (`action: 'set-rule'|'write-template'|'delete-template'`).
+- **GitHub-sync conflicts** — `list_conflicts` (enumerate), `get_conflict_content` (base/ours/theirs stages + lifecycle), `resolve_conflict` (write a chosen resolution + commit; destructive). Mutating writes against a doc in conflict return RFC 9457 `urn:ok:error:doc-in-conflict` (409); `exec("cat …")` returns `lifecycle: {status, reason} | null` so you can detect the state proactively. See *Conflict-aware writes*.
 - **Workflow** — `ingest`, `research`, `consolidate`, `discover` (return procedural guides, not data).
 
 Tools NOT in OK MCP (they belong to your agent host): `preview_start`, `preview_screenshot`, `WebFetch`, `WebSearch`, native `Read` / `Grep` / `Glob` / `Edit`. The STOP rule below governs which of those you may use on in-scope markdown.
@@ -61,34 +62,38 @@ Why: native tools skip frontmatter, backlinks, shadow-repo activity, and project
 
 ## Preview — open the browser at session start
 
-**The invariant.** If OK Electron is open for this project OR `ok ui` is running for it, every OK tool response carries the preview URL — plain HTTP, no custom URL schemes, works in any browser including agent in-app browsers (Claude Desktop, Cursor, Codex, Cowork). Read tools (`exec`, `search`, `links`) carry it in `ui.baseUrl` (top-level) and per-doc `previewUrl` fields; write tools carry it in `previewUrl` + the optional `warning` shape. Never construct this URL; always read it from the latest tool response.
+The user watches your edits land in a live browser preview. Open it once at session start, then keep working. Re-navigate only when the user asks to open a different doc, or to land them on a finished deliverable (see below) — not to re-check your own edits.
 
-**The default agent move.** Make your first OK tool call (any read works — `exec("ls -A")` is enough). The response carries the preview URL. Navigate to it immediately, then proceed with your real work. The user watches edits land live; you can re-navigate later to verify a CRDT edit landed when a response looks ambiguous. Per host:
+**End a turn on the deliverable, not your scratch space.** Keep the preview steady *during* a multi-doc task — don't yank it around to re-check your own edits. But when a turn created or substantially changed user-facing docs, navigate the preview to the primary deliverable before you hand back: the hub / overview / index page when you created several docs, or the changed doc when you changed one. Don't step the user through every supporting source card — the user is watching, so leave them on the result.
 
-- **In-app browser hosts** (Claude Desktop, Cursor, Codex, Cowork): navigate the in-app browser to the `previewUrl`. Default.
-- **Claude Code Desktop**: call `preview_start("open-knowledge-ui")` (host tool, not OK MCP) — and nothing else. Do NOT read, diagnose, or edit `.claude/launch.json`; that file is host-managed config, and the OK ui lock-collision proxy handles the UI-already-running case automatically. If `preview_start` fails, surface the `previewUrl` from any recent OK tool response and report the issue to the user — do not try to "fix" `launch.json`.
-- **Stdio-only hosts**: surface the URL in chat; `open <url>` (macOS) if the host can shell out.
+**`previewUrl` is a route, not a URL to open.** Every read response (per-doc, on `exec` / `search` / `links` rows) and every write response carries a `previewUrl` — a route fragment like `/#/specs/foo/SPEC`, with **no scheme, host, or port**. It identifies *which doc* to preview, not a URL to hand a browser by itself. Never construct or guess preview URLs.
 
-**Four signals to check if it's already open** (you usually can't pre-check, so read these from each write response):
+**Pick how to open the preview by tool capability — not by host name.** Look at the tools actually available to you this session:
+
+- **You have a `preview_*` tool** (e.g. `preview_start`) → call `preview_start("open-knowledge-ui")` and nothing else. The pane supplies its own origin; you never need a URL. Do NOT also call `get_preview_url`. Do NOT read, diagnose, or edit `.claude/launch.json` — that file is host-managed, and the OK lock-collision proxy handles the UI-already-running case automatically. If `preview_start` fails, report it to the user; do not try to "fix" `launch.json`.
+- **No `preview_*` tool, but you have an in-app / built-in browser tool** → call `get_preview_url` once to get the full browser URL (`{ url, baseUrl, running }`), then navigate your **in-app browser** to `url`. Pass a `docName` to `get_preview_url` to jump straight to a doc, or omit it for the UI root.
+- **No browser tool at all** (a stdio host such as the Codex CLI, which has no embedded browser) → call `get_preview_url`, then `open <url>` in the system browser as a last resort, and say so plainly to the user ("opening the preview in your system browser — this host has no in-app browser"). The system browser is the fallback, never the default.
+
+**Opening or reading a file IS a preview navigation.** On any "open `<file>`" / "read `<file>`" request, navigate the browser to that doc's `previewUrl` route from the tool response — not a separate fetch, not a fresh system-browser launch.
+
+**Four signals to check if the preview is already attached** (read these from each write response):
 
 1. You opened/navigated earlier this session → don't reopen.
-2. Write response has `previewUrl` (non-null) and NO `warning` → a browser is attached somewhere; do nothing.
-3. `warning: { action: "attach-preview-once", previewUrl, message }` → UI reachable, no browser attached; navigate one-shot.
+2. Write response has `previewUrl` (non-null route) and NO `warning` → a browser is attached somewhere; do nothing.
+3. `warning: { action: "attach-preview-once", previewUrl, message }` → UI reachable, no browser attached; navigate one-shot (`preview_start`, or `get_preview_url` → in-app browser).
 4. `warning: { action: "start-ui", previewUrl: null, message }` → no UI running anywhere. Surface the message verbatim — recovery options are in the in-band copy. Don't loop on retries.
 
 Warnings fire at most once per session in the fresh-start case.
 
-**`previewUrl: null` only means "no UI reachable" on the three attach-warning tools: `write_document` / `edit_document` / `edit_frontmatter`.** Workflow tools return prose and don't carry `previewUrl`. `delete_document` / `rename` emit `previousPreviewUrl` (different field, for closing stale tabs) and don't fire attach warnings.
-
-**Always read `previewUrl` from the latest write response.** Don't cache the session-start value — Electron quit/reopen (or `ok ui` restart) can change the port; the resolver picks up the new port automatically.
+**`previewUrl: null` only means "no UI reachable" on the three attach-warning tools: `write_document` / `edit_document` / `edit_frontmatter`.** Workflow tools return prose and don't carry `previewUrl`. `delete_document` / `rename` emit `previousPreviewUrl` (different field, for closing stale tabs) and don't fire attach warnings. `get_preview_url` reports `running: false` + `url: null` when no UI is running.
 
-If you see `"Hocuspocus server is not running"`, run `ok start` and retry. NEVER construct preview URLs by hand.
+If you see `"Hocuspocus server is not running"`, run `ok start` and retry.
 
-OK Electron and `ok ui` share `ui.lock` — only one can be the primary server for a project. When a second `ok ui` tries to bind a different port (Claude Code Desktop's preview pane spawning a sibling, for example), the OK lock-collision handler proxies the new port to the live UI server transparently. **Do not nudge the user to quit OK Electron to free a port** — the proxy handles it, and quitting would tear down a UI the user is actively using.
+OK Electron and `ok ui` share `ui.lock`; when a second UI binds a different port, the OK lock-collision proxy bridges it to the live server transparently. That is exactly why `previewUrl` is route-only — the port behind the proxy is not the agent's to use. **Do not nudge the user to quit OK Electron to free a port** — the proxy handles it, and quitting tears down a UI in active use.
 
-**The preview is read-only for the agent.** Navigate to verify edits landed; you cannot click or type to drive edits — the CRDT flow is one-way (agent → MCP → CRDT → preview).
+**The preview is read-only for the agent — it is the user's view, not a surface you read back.** You cannot click or type to drive edits — the CRDT flow is one-way (agent → MCP → CRDT → preview).
 
-**No screenshots after every edit.** Do NOT take `preview_screenshot` (host tool, not OK MCP) after every write. Trust the response. Screenshot only when (a) debugging a visual issue, (b) a response looks ambiguous, or (c) the user asks.
+**No screenshots to confirm edits, no generic verification loop.** Do NOT take `preview_screenshot` (host tool, not OK MCP) after a write, and do not run a generic snapshot/eval/screenshot verification loop — OK's preview is a read-only, one-way mirror, so the CRDT tool response *is* the confirmation that an edit landed. Screenshot only when debugging a visual rendering issue or when the user explicitly asks to see the preview — never to confirm an edit landed.
 
 ## Writing
 
@@ -98,22 +103,84 @@ To delete a doc, call `delete_document` — never `rm` / `unlink` / native `Bash
 
 **If `edit_document` returns "Text not found" on text you can verify exists on disk** (via `exec("cat …")`), the MCP session is likely stale (e.g., after a folder rename or server restart). Treat this as the escape-hatch trigger from the STOP block: prefix your next user-visible sentence with `Open Knowledge MCP unavailable:` and report the inconsistency. Don't loop on retries — the symptom is structural, not transient.
 
-## Components — prefer canonicals when one fits
+## Conflict-aware writes
+
+Projects with GitHub sync enabled may carry docs in a merge-conflict state. The MCP server refuses every mutating call against such a doc with a structured RFC 9457 response:
+
+```json
+{
+  "type": "urn:ok:error:doc-in-conflict",
+  "title": "Document is in conflict.",
+  "status": 409,
+  "detail": "The document is in a merge-conflict state. Call get_conflict_content + resolve_conflict before retrying.",
+  "file": "notes/sso.md",
+  "resolutionOptions": ["mine", "theirs", "content"]
+}
+```
+
+The gate covers `write_document`, `edit_document`, `delete_document`, `rename`, `version` (`action: 'rollback'`), `folder_config` (`action: 'write-template'|'delete-template'`), and agent undo. You cannot route around it by writing content that byte-matches one of the merge stages — the gate refuses on lifecycle state, not on body equality.
+
+**Detect proactively.** `exec("cat <path>.md")` always returns `lifecycle: {status, reason} | null` alongside the body. When `status === 'conflict'`, switch to the resolution flow before attempting any mutation.
+
+**Resolution flow.** Three tools compose:
+
+1. `list_conflicts()` → enumerate every doc currently tracked in conflict.
+2. `get_conflict_content({ file })` → fetch `base` / `ours` / `theirs` stages plus the doc's `lifecycleStatus`. `ours` reflects the live Y.Text (what the human user sees in the editor) when the doc is loaded server-side and is marker-free; falls back to `git show :2:<file>` otherwise (e.g. after an editor reopen seeded markers into Y.Text).
+3. `resolve_conflict({ file, strategy, content? })` → write the chosen bytes and commit. Strategies: `mine` writes `git show :2:`, `theirs` writes `git show :3:`, `content` writes the bytes you supply.
+
+`file` is a `.md` / `.mdx` path relative to the project dir (extension included) — mirrors the on-disk shape, not the extension-less `docName` used by other tools.
+
+The resolve operation is best-effort and NOT atomic: `git checkout --ours/--theirs && git add` may succeed but the subsequent `git commit --no-edit` can fail (pre-commit hook rejection, locked index). On commit failure the staged files are re-`git add`-ed back into the unmerged index and the tracked entry remains in `conflicts.json` — re-call `resolve_conflict` after the user clears the blocker.
 
-OK projects ship a registry of custom JSX components (callouts, tabs, math, file attachments, …) with richer affordances than plain CommonMark / GFM. Three-step pattern:
+## Components — write the markdown-native form, not JSX
 
-1. **Discover.** `write_document` and `edit_document` carry an inline inventory of available canonicals as part of their `description` — your host renders it in its tool-list view. `kind` is `jsx-block` (children) or `jsx-void` (self-closing).
-2. **Fetch.** `get_components({ ids: [...] })` returns per-entry `example` (literal copy-paste bytes) + form-aware `params` schema (`type`, `values?` for enums, `required`, `defaultValue?`, `description`).
-3. **Write.** Compose markdown inline using the `example` syntax + your prop values, then call `write_document` or `edit_document`. Shapes: `<BlockComponent prop="...">body</BlockComponent>` or `<VoidComponent prop="..." />`.
+OK auto-promotes markdown-native syntax into themed canonical components at parse time. **Write the markdown-native form — don't reach for JSX when one exists.** The promoted component is themed, accessible, and part of the content graph; hand-rolled JSX is none of those, and it fights the model's markdown prior instead of using it.
 
-**Fenced code blocks are a separate authoring path** (NOT in the inventory, no `get_components` fetch needed):
-- ` ```mermaid ` — Mermaid diagram (flowchart, sequence, class, state, ER, gantt, pie).
-- ` ```html preview ` (also `htm preview` / `xml preview`) — live iframe preview. Author a standalone HTML/JS/CSS page in the fence; it executes inside the editor. Use this for anything interactive (charts via Chart.js / D3, calculators, animations, demos). Optional `h=<value>` / `w=<value>` fence-meta tokens set iframe size.
-- ` ```<lang> ` (other languages) — syntax-highlighted code block, no preview.
+| Want | Write this (markdown-native) | Promotes to |
+| --- | --- | --- |
+| Callout / admonition | `> [!NOTE]` + body — 15 types (NOTE, TIP, IMPORTANT, WARNING, CAUTION, …); append `+` / `-` (`> [!NOTE]+`) to make it foldable | themed Callout |
+| Collapsible section | `<details><summary>Title</summary>` … `</details>` | themed Accordion |
+| Diagram | a ` ```mermaid ` fenced block (flowchart, sequence, class, state, ER, gantt, pie) | Mermaid diagram |
+| Math | `$x$` inline, `$$…$$` block | KaTeX Math |
+| Inline a doc or asset | `![[file]]` | wiki embed |
 
-**Fallback:** if no canonical matches, write any `<TagName>...</TagName>` JSX — OK renders unregistered components as raw MDX. Prefer canonicals when one matches.
+`Tabs` is the lone canonical with **no** markdown-native form — write the JSX directly (`<Tabs><Tab label="…">…</Tab></Tabs>`). For any canonical's full JSX prop schema, call `get_components({ ids })`. If no canonical fits, any `<TagName>…</TagName>` falls through as raw MDX — but prefer a canonical when one matches.
+
+**Discover the palette in one call.** `get_authoring_palette` returns every markdown-native form (copy-ready `example` + `guidance`), the themed `html preview` embed starters, and the injected theme-token list — the source of truth for component-forward, themed authoring. Canonical names/counts beyond the markdown-native set are project-specific; the inventory in the `write_document` / `edit_document` descriptions and `get_components` are authoritative for those.
+
+**Show findings, don't just tell them.** When a point is quantitative or comparative — a trend over time, a breakdown, a before/after, a ranking, a distribution — present it visually: a chart or stat-card `html preview` embed, a ` ```mermaid ` diagram, a table, or a Callout for the headline takeaway. Prose-only buries the insight. This matters most where the document's job is to make findings legible — **`research` reports and `consolidate` articles especially**, and any write-up meant to present results. A research article with three dense paragraphs of numbers should have been a chart. Reach for `get_authoring_palette` as you draft, not after.
+
+### `html preview` — themed interactive embeds
+
+A ` ```html preview ` fence (also `htm` / `xml`) renders a standalone HTML/CSS/JS page as a live sandboxed iframe — the extend-to-anything primitive for charts, stat cards, custom SVG, calculators, demos. The iframe auto-sizes to its content; pass `h=` / `w=` (e.g. ` ```html preview h=400px `) only to pin a fixed size.
+
+**Start from a starter — don't hand-roll.** `get_authoring_palette` returns `embedPatterns` (chart, stat cards, custom SVG, interactive control), each already wired to the theme tokens. Copy one and fill in your data — that is the only path that cannot render unthemed. Hand-author a fence from scratch only when no starter is close.
+
+**MUST — never hardcode colors in an `html preview` embed.** OK injects its theme tokens into every preview iframe; an embed that hardcodes hex / `rgb()` renders unthemed — a white box on a dark page, clashing with every component around it. This is the single most common embed mistake. Wire every color to a token: `var(--chart-1..5)` for chart series, `var(--foreground)` / `var(--muted-foreground)` for text, `var(--card)` / `var(--background)` for surfaces, plus `var(--border)`, `var(--primary)`, `var(--radius)`. Don't set a `body` background at all unless you specifically mean to — the iframe already carries a themed one.
+
+````
+```html preview
+<div style="font-family:system-ui;padding:20px;color:var(--foreground)">
+  <h3 style="margin:0 0 10px">Themed embed</h3>
+  <div style="display:flex;gap:8px">
+    <div style="flex:1;height:48px;background:var(--chart-1);border-radius:var(--radius)"></div>
+    <div style="flex:1;height:48px;background:var(--chart-2);border-radius:var(--radius)"></div>
+    <div style="flex:1;height:48px;background:var(--chart-3);border-radius:var(--radius)"></div>
+  </div>
+</div>
+```
+````
+
+Done wrong, that same embed is `body{background:#fff;color:#1a1a1a}` with a `background:#2563eb` bar — a white box with a hardcoded blue, blind to the reader's theme.
+
+**Charts.** A pure-CSS or inline-SVG chart wired to `var(--chart-*)` re-skins on a theme toggle for free — prefer it. A JS charting library (Chart.js, D3) works too, but a themed `body` does NOT theme the colors you pass the library in JS — read the token at runtime instead of hardcoding:
+
+```js
+const c1 = getComputedStyle(document.documentElement).getPropertyValue('--chart-1').trim();
+// → pass c1 to Chart.js / D3 as the series color
+```
 
-**Don't enumerate first-party canonicals here** — names/counts are project-specific; the inventory in the write tools' descriptions is the source of truth.
+**Boundary.** Reach for a canonical (via its markdown-native form) when one matches the semantic need — it is themed and integrated. Reach for ` ```html preview ` for interactive or bespoke content no canonical covers. ` ```<lang> ` fences for other languages are plain syntax-highlighted code, no preview.
 
 ## Grounding — every factual claim needs a source (MUST)
 
@@ -136,9 +203,10 @@ Knowledge-base docs are factual artifacts — whether the project is a wiki, an
 - **Every noun-phrase that names another document should be linked** using standard markdown link syntax: `[text](./relative/path.md)` or `[text](/absolute/from/content-root.md)`.
 - **External web sources are NOT inline body links.** Per the Grounding rule above, web URLs live in the `source_url:` frontmatter of an ingested doc under `external-sources/` (or the project's equivalent raw-sources folder); the body cites the local path: `[source name](./external-sources/source-slug.md)`. A raw `[source](https://...)` inline in the body is a TODO, not a citation — see Grounding for the closed-loop contract.
 - **Internal cross-refs between OK docs** → `[text](./other-doc.md)` — link liberally to aid navigation.
+- **Every link must resolve to a doc that exists.** Never link to a doc that isn't written yet. If you want to reference something that should have its own page but doesn't: create that page in the same pass, or record it as a tracked task (`TaskCreate`, or your host's task tool — if the host has none, tell the user) and leave the mention as plain prose. A broken link is debt, not a to-do marker.
 - **Never wrap a link in backticks.** `` `[text](./foo.md)` `` is a bug — the backticks make it render as literal code rather than a link.
 - **Never use HTML anchors** (`<a href="...">`). Markdown link syntax only.
-- **Verify before walking away.** After writing a doc, call `links({ kind: "dead", sourceDocNames: ["your/doc"] })` to find broken references. Fix each redlink or explicitly accept it. Companion `links` kinds: `backlinks` (incoming), `forward` (outgoing), `orphans` (no incoming), `hubs` (high-incoming), `suggest` (untextualized mentions worth linking).
+- **Verify before walking away.** After writing a doc, call `links({ kind: "dead", sourceDocNames: ["your/doc"] })` to find broken references. Fix or remove every one — a dead link is never acceptable to leave behind. Companion `links` kinds: `backlinks` (incoming), `forward` (outgoing), `orphans` (no incoming), `hubs` (high-incoming), `suggest` (untextualized mentions worth linking).
 - **The editor's red-underline visual lies.** Its dead-link detection tolerates slug-fallback (e.g., `foo` may appear resolved because `foo.md` exists at root). `links({ kind: "dead" })` is strict-exact — trust the tool, not the visual.
 
 **Note on wiki-link syntax (`[[Page]]`):** the parser still handles it for legacy content, but it's NO LONGER the recommended default. Write new content with standard markdown links per above. Seed-pack templates (`ok seed --pack <name>`) may still emit `[[Page]]` placeholders inside template body text — those are legacy. When you instantiate a seed-pack template, replace the legacy placeholders with standard markdown links during the `{shape}`-fill pass.
@@ -303,7 +371,7 @@ Body is just the wiki-embed. PDFs/opaque attachments render as a click-dispatchi
 
 When you make a multi-step change (batch of new docs, folder restructure), pause between steps to let the browser preview catch up. The CRDT edit streams live; the preview follows your edit cadence. Don't batch 10 writes in a row — interleave the writes so the user watching the browser sees the narrative progress.
 
-This is primarily a human-watchability concern — the user watches edits land in the preview; interleaved cadence makes the narrative legible.
+This is primarily a human-watchability concern — the user watches edits land in the preview; interleaved cadence makes the narrative legible. When the batch is done, navigate the preview to the primary deliverable (see "End a turn on the deliverable" in §Preview).
 
 **Hub docs.** Don't *create* `INDEX.md` / `README.md` hub files solely to catalog children — `exec("ls -A <folder>")` returns the same view live, with per-file frontmatter + backlink counts. But if a hub doc *already exists* from prior work, keep it updated as children change — interleave: write child → update hub → write next child, rather than batching five child edits and a single trailing hub update.
 
@@ -324,7 +392,7 @@ The skill carries the trigger ("KB content changed this turn — go look"). The
 | Read an individual doc                          | `Read: specs/foo/SPEC.md`                                                          | `exec("cat specs/foo/SPEC.md")`                                                   |
 | Explore a markdown-heavy dir                    | `Agent(Explore): "..."`                                                            | Do `exec`-based exploration yourself                                              |
 | Wait for the server to tell you to open preview | Skip the session-start preview open and wait for the `attach-preview-once` hint    | Open the preview browser at session start; the hint is a fallback when you didn't |
-| Ignore the attach hint                          | Skip the `warning: { action: "attach-preview-once" }` hint in write-tool responses | Open the `previewUrl` when the hint fires; otherwise do nothing                   |
+| Ignore the attach hint                          | Skip the `warning: { action: "attach-preview-once" }` hint in write-tool responses | Open the preview when the hint fires (`preview_start`, or `get_preview_url`); otherwise do nothing |
 | Make the Claude Code Desktop preview work       | Read / diagnose / edit `.claude/launch.json` (host-managed config)                 | Call `preview_start("open-knowledge-ui")` and nothing else; the OK lock-collision proxy bridges any port mismatch transparently |
 | Reference another doc                           | `` `[text](./page.md)` `` (backticked) or HTML `<a>`                               | `[text](./page.md)` (raw markdown)                                                |
 | Embed an image                                  | `<img src="...">` (HTML) or hot-linked external URL                                | Fetch + save locally + `![meaningful alt](./assets/images/path)`                  |