@inkeep/open-knowledge 0.6.0-beta.13 → 0.6.0-beta.15

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.13"
+  version: "0.6.0-beta.15"
   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.13"
+  version: "0.6.0-beta.15"
   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 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` 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 — 18 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), `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,7 +62,7 @@ Why: native tools skip frontmatter, backlinks, shadow-repo activity, and project
 
 ## Preview — open the browser at session start
 
-The user watches your edits land in a live browser preview. Open it once at session start, then keep working — re-navigate later only to verify an ambiguous edit.
+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.
 
 **`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.
 
@@ -88,9 +89,9 @@ If you see `"Hocuspocus server is not running"`, run `ok start` and retry.
 
 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, no generic verification loop.** Do NOT take `preview_screenshot` (host tool, not OK MCP) after every 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 (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
 
@@ -100,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: