@inkeep/open-knowledge 0.20.0 → 0.20.1-beta.0

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

@@ -3,7 +3,7 @@ name: open-knowledge-discovery
 description: "Read when the user asks what OpenKnowledge is, wants to install it on a repository, wants to share an OpenKnowledge project with collaborators, or asks how `ok init` / `ok cowork` / OK Desktop set up a project. Do NOT load to perform OpenKnowledge 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.20.0"
+  version: "0.20.1-beta.0"
   author: "Inkeep"
   repository: "https://github.com/inkeep/open-knowledge"
 ---
@@ -14,9 +14,13 @@ directory of `.md` / `.mdx` files into a live, multi-writer knowledge base:
 agents and humans edit the same documents in real time, every change is
 attributed, and a browser preview renders edits as they land.
 
-This skill is **discovery-only**. It explains what OpenKnowledge is and how
-to set it up. It carries **no runtime rules** for reading or editing markdown
-— that guidance ships separately (see *Working inside a project* below).
+This skill covers **discovery, install, and opening OpenKnowledge files** —
+including single files that are not part of a project (see *Opening a file
+outside a project* below). It does **not** carry the in-project read/write
+runtime contract (the STOP rules for native file tools, the grounding and
+linking rules, the MCP routing table) — that ships separately as the
+project-local skill installed by `ok init` (see *Working inside a project*
+below).
 
 ## Install OpenKnowledge on a repository
 
@@ -71,6 +75,51 @@ bundles its own CLI, opens a project as an editor + preview window, and keeps
 the project's MCP wiring and skills current on every launch. Download DMGs
 from the releases page.
 
+## Opening a file outside a project
+
+OpenKnowledge can open a single markdown file that is **not** part of an OK
+project — a loose `.md` / `.mdx`, **or a file that lives inside a regular
+repo/folder which was never `ok init`'d**. It opens in a throwaway session (a
+temp project in the OS temp dir — your repo is never touched, no `.ok/` is
+written into it) with the same live preview you get inside a project.
+
+**Never run `ok init` just to view or open a file.** `ok init` turns a repo
+into a shared OpenKnowledge project; it is not a prerequisite for opening one
+file. Opening a file needs no project, no `.ok/`, and no server already
+running — each path below boots the session itself.
+
+When asked to open or preview such a file, **decide by the viewing surface you
+actually have** — check the tool, not the host name. Only open a browser when
+you genuinely have one; never pop a browser tab on a host that has none.
+
+- **You have an in-app / built-in browser** (Cursor, Codex, and similar) — this
+  is the default: call the **`preview_url` MCP tool** with `file` set to the
+  absolute path (it finds, or boots on demand, the session and returns a full
+  `url`), then **immediately open that `url` in your in-app browser**. "Open it"
+  means navigate your browser — don't just print the URL and stop. This is also
+  the only way to view it in a browser when the OK Desktop app is installed
+  (`ok open` prefers the Desktop app). Get the URL from `preview_url` only —
+  never hunt for it via `ok ps` / `ok status` / `ok ui` / `ok start` or a guessed
+  port.
+- **You have a Claude Code Desktop preview *pane* but no general browser** — the
+  pane is project-only: it shows in-project docs via `preview_start`, but it
+  **cannot host a file from outside the project**. For such a file run
+  `ok open /abs/path/to/file.md` (the Desktop app) instead; don't try to force
+  the file into the pane.
+- **No in-app browser and no pane** (a pure-stdio CLI) — run
+  `ok open /abs/path/to/file.md`: it opens the Desktop app when installed, else a
+  browser, and boots the session itself. Don't force a browser tab the user
+  didn't ask for; `ok open` is the right default here. If `ok` isn't on PATH,
+  `npx @inkeep/open-knowledge open /abs/path/to/file.md` does the same.
+
+If the OK MCP server isn't wired into this host there is no `preview_url` to
+call — use the `ok open` path above. Don't reconstruct what `preview_url` does
+by hand (spawning `ok mcp` yourself, scraping ports from `ok ps`).
+
+The path must be absolute (a file outside a project has no cwd to anchor a
+relative path). Re-opening the same file lands on the same session. Never
+construct or guess the URL — use the one `preview_url` returns.
+
 ## Working inside a project — use the project-local skill, not this one
 
 Do **not** use this skill to perform OpenKnowledge reads or writes. The

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

@@ -3,7 +3,7 @@ name: open-knowledge
 description: "Authoritative agent-runtime contract for working inside an OpenKnowledge project — a markdown-CRDT knowledge base exposed over MCP. Use whenever reading, listing, searching, or editing any `.md` or `.mdx` file in the project, and before any `mcp__open-knowledge__*` tool call (`exec`, `search`, `write`, `edit`, and the rest). Installed by `ok init`, so its presence means this is an OpenKnowledge project and it governs every markdown file here. Covers the read/write tool surface, grounding and linking rules, folder/template conventions, the live browser preview, and the rule that OK's MCP tools — never native file tools — handle in-scope markdown."
 compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server + code execution."
 metadata:
-  version: "0.20.0"
+  version: "0.20.1-beta.0"
   author: "Inkeep"
   repository: "https://github.com/inkeep/open-knowledge"
 ---

package/dist/assets/skills/write-skill/SKILL.md

@@ -3,7 +3,7 @@ name: open-knowledge-write-skill
 description: "Use when the user wants to create, author, write, or design a new Agent Skill (a SKILL.md) — for OpenKnowledge or for their editors — including requests like 'help me write a skill', 'make a skill that…', 'turn this workflow into a skill', or improving an existing skill's triggering and discipline. Also use when capturing reusable agent guidance that should live as an installable skill rather than a one-off prompt. Covers choosing scope (project vs global), the SKILL.md frontmatter contract, progressive-disclosure structure, evaluating the skill, and installing it into the user's editors."
 compatibility: "OpenKnowledge project recommended (uses the `write` / `edit` / `install` MCP verbs). Authoring + validation are pure file ops; live preview + eval want a running server (`ok start`)."
 metadata:
-  version: "0.9.1"
+  version: "0.20.0"
   author: "Inkeep"
   repository: "https://github.com/inkeep/open-knowledge"
 ---