@inkeep/open-knowledge 0.6.0-beta.2 → 0.6.0-beta.20

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
 

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.2"
+  version: "0.6.0-beta.20"
   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.2"
+  version: "0.6.0-beta.20"
   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 — 21 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 schemas), `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,36 @@ 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, 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:
+**`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.
 
-- **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.
+**Pick how to open the preview by tool capability — not by host name.** Look at the tools actually available to you this session:
 
-**Four signals to check if it's already open** (you usually can't pre-check, so read these from each write response):
+- **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.
+**`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.
 
-**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.
+If you see `"Hocuspocus server is not running"`, run `ok start` and retry.
 
-If you see `"Hocuspocus server is not running"`, run `ok start` and retry. NEVER construct preview URLs by hand.
+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.
 
-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.
+**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).
 
-**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).
-
-**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,6 +101,35 @@ 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.
 
+## 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.
+
 ## Components — prefer canonicals when one fits
 
 OK projects ship a registry of custom JSX components (callouts, tabs, math, file attachments, …) with richer affordances than plain CommonMark / GFM. Three-step pattern:
@@ -324,7 +356,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)`                  |