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

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

@@ -1,9 +1,9 @@
 ---
 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 install-skill` / 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."
+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 cowork` / 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.19.3-beta.0"
+  version: "0.20.0-beta.0"
   author: "Inkeep"
   repository: "https://github.com/inkeep/open-knowledge"
 ---
@@ -57,10 +57,10 @@ An OK project travels with its repository. To share one:
 Collaboration is real-time once two writers have the project open against the
 same content directory.
 
-## `ok install-skill` — Claude Chat & Cowork
+## `ok cowork` — Claude Chat & Cowork
 
 `ok init`'s editor wiring does not reach Claude Chat or Cowork — those read a
-separate Skills list inside the Claude Desktop App. Run `ok install-skill` to
+separate Skills list inside the Claude Desktop App. Run `ok cowork` to
 build `openknowledge.skill` and open Claude Desktop so the user can upload it
 (Customize → Skills → + → Create skill → Upload skill).
 

package/dist/assets/skills/packs/codebase-wiki/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: open-knowledge-pack-codebase-wiki
+version: "0.18.0"
 description: "How to work in a Codebase Wiki project (the `codebase-wiki` starter pack): an agent-authored, source-grounded wiki of the surrounding codebase. Read when the project has a `wiki/` knowledge base with `architecture/`, `modules/`, `flows/`, `concepts/`, and `guides/` sections plus `wiki/OVERVIEW.md`. Carries the per-folder rules and freshness + log discipline, summarizes the audience/depth knobs and source-reference convention, and points to the `workflow({ kind: 'wiki' })` guide for the full generate/refresh procedure. Complements the platform `open-knowledge` skill; does not replace it."
 compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack codebase-wiki`."
 metadata:

package/dist/assets/skills/packs/entity-vault/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: open-knowledge-pack-entity-vault
+version: "0.18.0"
 description: "How to work in an Entity vault project (the `entity-vault` starter pack, GBrain-compatible): a typed-entity vault of people, companies, meetings, and concepts, each a dossier with a rewritable summary plus an append-only timeline. Read when the project has these folders. Carries the dossier convention and entity-extraction behaviors so that guidance does not live inside template bodies or folder descriptions. Complements the platform `open-knowledge` skill; does not replace it."
 compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack entity-vault`."
 metadata:

package/dist/assets/skills/packs/knowledge-base/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: open-knowledge-pack-knowledge-base
+version: "0.18.0"
 description: "How to work in a Knowledge Base project (the `knowledge-base` starter pack). Read when the project has the three-layer source-grounded layout — `external-sources/` → `research/` → `articles/` — wired to the `workflow` MCP tool's ingest / research / consolidate kinds. Carries the pack's workflow, per-folder rules, status flows, and log discipline so this guidance does NOT live inside template bodies or log.md. Complements the platform `open-knowledge` skill; does not replace it."
 compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack knowledge-base`."
 metadata:

package/dist/assets/skills/packs/okf/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: open-knowledge-pack-okf
+version: "0.18.0"
 description: "How to work in an OKF starter project (the `okf` starter pack): a knowledge base that is conformant with Google's Open Knowledge Format (OKF) from commit one — `concepts/`, `references/`, `notes/`, a reserved `index.md` navigation hub, and a reserved `log.md` change history. Read when the project has these folders + reserved files. Carries the OKF conventions (non-empty `type` on every non-reserved doc; reserved files carry no frontmatter) as guidance, not enforcement. Complements the platform `open-knowledge` skill; does not replace it."
 compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack okf`."
 # `type` keeps this skill doc OKF-conformant: it installs as project-local

package/dist/assets/skills/packs/plain-notes/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: open-knowledge-pack-plain-notes
+version: "0.18.0"
 description: "How to work in a Plain Notes project (the `plain-notes` starter pack): a flat notes/ folder plus a daily/ journal. The 'I just want to write' layout. Read when the project has these folders. Carries the linking habit and daily-entry behavior so templates and folder descriptions stay minimal. Complements the platform `open-knowledge` skill; does not replace it."
 compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack plain-notes`."
 metadata:

package/dist/assets/skills/packs/software-lifecycle/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: open-knowledge-pack-software-lifecycle
+version: "0.18.0"
 description: "How to work in a Software Lifecycle project (the `software-lifecycle` starter pack): proposals → decisions → specs → postmortems, plus guides. Read when the project has these folders. Carries the doc lifecycle, status flows, and per-folder agent behaviors so that guidance does not live inside template bodies or folder descriptions. Complements the platform `open-knowledge` skill; does not replace it."
 compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack software-lifecycle`."
 metadata:

package/dist/assets/skills/packs/worldbuilding/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: open-knowledge-pack-worldbuilding
+version: "0.18.0"
 description: "How to work in a Worldbuilding project (the `worldbuilding` starter pack): a fiction encyclopedia of characters, settings, themes, factions, and lore. Read when the project has these folders. Carries the auto-stub and consistency behaviors so that guidance does not live inside template bodies or folder descriptions. Complements the platform `open-knowledge` skill; does not replace it."
 compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack worldbuilding`."
 metadata:

package/dist/assets/skills/packs/writing-pipeline/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: open-knowledge-pack-writing-pipeline
+version: "0.18.0"
 description: "How to work in a Writing Pipeline project (the `writing-pipeline` starter pack): a three-stage drafting flow, ideas → drafts → published. Read when the project has these folders. Carries the stage flow and review behaviors so that guidance does not live inside template bodies or folder descriptions. Complements the platform `open-knowledge` skill; does not replace it."
 compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack writing-pipeline`."
 metadata:

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`, `edit`, and the rest). This skill is installed into the repository by `ok init`, so its presence alone means this is an OpenKnowledge project — its runtime contract governs every markdown file here, with no need to probe for a `.ok/` directory. Authoritative agent-runtime contract for working inside this OpenKnowledge project."
 compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server + code execution."
 metadata:
-  version: "0.19.3-beta.0"
+  version: "0.20.0-beta.0"
   author: "Inkeep"
   repository: "https://github.com/inkeep/open-knowledge"
 ---
@@ -15,6 +15,8 @@ OpenKnowledge (OK) is a markdown-CRDT collaboration platform exposed via MCP. Th
 
 > Skill version: tracks `@inkeep/open-knowledge-server` package version. Check `cat ~/.ok/skill-state.yml` to see what's installed locally. **Version floor:** `ok seed` (referenced below) requires `@inkeep/open-knowledge` >= 0.4.0. If `ok seed` errors with `unknown command`, upgrade: `npm install -g @inkeep/open-knowledge`.
 
+> **Setup (not connected yet?).** If the `mcp__open-knowledge__*` tools aren't available in your client, this project isn't wired up on this machine — see [`references/setup.md`](references/setup.md) for the rung ladder (approve `.mcp.json` → `ok start` CLI → optional desktop app) and the canonical quickstart.
+
 ## TL;DR — the 90% case
 
 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`.
@@ -22,20 +24,23 @@ OpenKnowledge (OK) is a markdown-CRDT collaboration platform exposed via MCP. Th
 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")`; if you have an in-app browser, call `preview_url` once for the full browser URL and navigate to it; on the Claude Code CLI (no browser tool), run `ok open <doc>` to open it in the OK Desktop app. 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 guides** — `workflow({ kind: 'ingest' | 'research' | 'consolidate' | 'discover' })` returns a procedural guide, not data. Use it when the work fits the layer; follow the numbered steps.
 5. **Direct questions:** a plain business question ("which customers…", "can we use…", "what did we decide about…") routes to `search` / `exec` + a cited answer — no "research" or "report" keyword needed. Persist the answer as a page only when it is durable, spans multiple docs, and isn't already covered — *offer* first, never auto-create. See §Answering direct questions from the corpus.
+6. **Authoring OR improving a skill** ("write/make a skill", "improve this skill", "turn this into a skill"): STOP and invoke the **`open-knowledge-write-skill`** skill — don't improvise from this skill, hand-edit `.ok/skills/…`, or narrate internal build steps / repo paths / project codenames to the user. It owns scope choice (project vs global), the SKILL.md contract, evaluation, and install. Use it for *improving* an existing skill too, not just new ones. **Never read, diff, or edit the installed projections under `.claude/skills/` · `.cursor/skills/` · `.codex/skills/` · `.opencode/skills/` · `.agents/skills/`** — those are generated by `install` and overwritten on the next sync; they are NOT a source of truth (a newer projection over an older checkout is expected, not "stale source"). The skill source lives behind the `skill` target / `write-skill`.
 
 Everything below is depth. Read on demand.
 
-## Tool index — 17 tools
+## Tool index — 19 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), `history` (versions for a doc), `links` (`kind: 'backlinks'|'forward'|'dead'|'orphans'|'hubs'|'suggest'`, or an array of those for a one-call audit, e.g. `links({ kind: ["dead", "orphans", "hubs"] })`), `config` (resolved config), `palette` (markdown-native authoring forms + themed `html preview` embed starters + theme tokens; pass `components` for the canonical component JSX schemas), `preview_url` (browser-reachable preview URL on demand), `share_link` (GitHub-substrate share URL for a doc or folder; read-only against `.git/`, no commits/pushes — returns a clear error when the project has no GitHub remote, since agents do not publish projects).
-- **Writes** — four native CRUD verbs, polymorphic over `document` / `folder` / `template` / `asset` (Pattern B: per-target fields nested inside the address key; pass EXACTLY ONE target):
-  - `write` — create/overwrite a `document` (supports `document.template` instantiation), create a `folder` (with open-shape frontmatter), create a `template`, or upload an `asset`.
-  - `edit` — modify a `document` (body find/replace OR frontmatter merge-patch), a `folder` (frontmatter merge-patch), or a `template`. (No asset — binary has no text body.)
-  - `delete` — remove a `document` (name or array), `folder`, `template`, or `asset`.
-  - `move` — move/rename a `document`, `folder`, or `asset`; rewrites referrers.
-  The OUTPUT mirrors the input: `write`/`edit`/`delete` nest their result under the same target key you passed (`{ document: {…} }` / `{ folder: {…} }` / `{ template: {…} }` / `{ asset: {…} }`, or `{ documents: [...] }` for a batch). The preview envelope (`previewUrl`, `warning`, `previousPreviewUrl`) stays at the top level — same for every tool.
+- **Reads** — `exec` (primary; shell-style `cat`/`ls`/`grep`/`find` with frontmatter + backlink + history enrichment), `search` (ranked, BM25 + recency), `history` (versions for a doc), `links` (`kind: 'backlinks'|'forward'|'dead'|'orphans'|'hubs'|'suggest'`, or an array of those for a one-call audit, e.g. `links({ kind: ["dead", "orphans", "hubs"] })`), `skills` (find + read skills: omit `name` to LIST every skill across Project + Global levels, pass `name` to READ one — addressed by `name`+`scope`, NEVER by path), `config` (resolved config), `palette` (markdown-native authoring forms + themed `html preview` embed starters + theme tokens; pass `components` for the canonical component JSX schemas), `preview_url` (browser-reachable preview URL on demand), `share_link` (GitHub-substrate share URL for a doc or folder; read-only against `.git/`, no commits/pushes — returns a clear error when the project has no GitHub remote, since agents do not publish projects).
+- **Writes** — four native CRUD verbs, polymorphic over `document` / `folder` / `template` / `skill` / `asset` (Pattern B: per-target fields nested inside the address key; pass EXACTLY ONE target):
+  - `write` — create/overwrite a `document` (supports `document.template` instantiation), create a `folder` (with open-shape frontmatter), create a `template`, **author a `skill`** (`skill: { name, description, body, scope? }` → writes `.ok/skills/<name>/SKILL.md` — this is how you create a skill; NEVER a raw `document` path under `.ok/skills/`), or upload an `asset`. A newly authored skill is a **Draft** until you `install` it (see below).
+  - `edit` — modify a `document` (body find/replace OR frontmatter merge-patch), a `folder` (frontmatter merge-patch), a `template`, or a `skill`. (No asset — binary has no text body.)
+  - `delete` — remove a `document` (name or array), `folder`, `template`, `skill`, or `asset`.
+  - `move` — move/rename a `document`, `folder`, `skill`, or `asset`; rewrites referrers. A skill also takes `scope`/`toScope` to move between the Project and Global levels (history resets; the moved skill is a Draft — re-`install`).
+  - `install` — the explicit Draft → Installed step for a `skill`: projects an authored skill into your editors (`targets?` to choose Claude/Cursor/Codex/OpenCode; defaults to the editors this project is set up for). Run after `write({ skill })` so the skill is live, not just authored.
+  - **Authoring or improving a skill?** Invoke the **`open-knowledge-write-skill`** skill (see TL;DR #6) — it walks the SKILL.md frontmatter + structure contract, picks scope (project vs global), evaluates, and installs it. Don't improvise from this skill. Author skills through the `skill` target above, never as a raw `.ok/skills/...` document.
+  The OUTPUT mirrors the input: `write`/`edit`/`delete` nest their result under the same target key you passed (`{ document: {…} }` / `{ folder: {…} }` / `{ template: {…} }` / `{ skill: {…} }` / `{ asset: {…} }`, or `{ documents: [...] }` for a batch). The preview envelope (`previewUrl`, `warning`, `previousPreviewUrl`) stays at the top level — same for every tool.
   Plus `checkpoint` (save a named version) and `restore_version` (roll a doc back to a prior version). A folder's own frontmatter is open-shape exactly like a doc's (self-only, does NOT cascade into child docs); templates are what new docs in a folder start with.
   **Self-correcting on misuse:** the few constraints JSON Schema can't express — "pass exactly one target", "`find` needs a `replace`", body-XOR-frontmatter — are enforced by a *teaching error*: a wrong call returns `isError: true` with a one-line message naming the exact corrective shape. Read it and retry with that shape; don't guess.
 - **GitHub-sync conflicts** — `conflicts` (`kind: 'list'` to enumerate, `kind: 'content'` for 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*.
@@ -52,6 +57,7 @@ When this workspace has OpenKnowledge MCP configured, do **not** use your host's
 - **Glob patterns that target markdown** (`**/*.md`, any dir known to be markdown-heavy like `specs/**`, `reports/**`, `docs/**`) — use `exec` with `find`, or `exec("ls -A <dir>")`.
 - **Dispatching the Explore / general-purpose subagent for markdown-heavy exploration** — subagents use native `Read` / `Grep` / `Glob` internally and bypass OpenKnowledge entirely. Do markdown exploration yourself via `exec` / `search`. Subagents remain appropriate for **source-code** exploration.
 - **Native `Read` / `Grep` on any in-scope markdown inside `.ok/`** — the `.ok/` directory is in-scope; if it carries `.md` / `.mdx`, treat those the same as any other knowledge-base file.
+- **`ls` / `cat` / `find` on `.ok/skills/` to discover or read a skill** — `.ok/` is opaque internal state; skills are addressed by `name`+`scope`, not by path. Use the `skills` tool (omit `name` to list across Project + Global, pass `name` to read one). Never browse `.ok/skills/...` paths.
 
 Why: native tools skip frontmatter, backlinks, shadow-repo activity, and project git history that OK's tools return for every matched knowledge-base file. `exec` is the primary read surface; it runs read-only bash (`cat`, `ls`, `grep`, `find`, `head`, `tail`, `wc`, `sort`, `uniq`, `cut`) and returns raw stdout plus enriched metadata per file. One command or a pipe (`|`) per call — it is NOT a shell, so `&&` / `;` / redirects are rejected; list several dirs with `ls -A a b c` or make separate calls.
 

package/dist/assets/skills/project/references/setup.md

@@ -0,0 +1,26 @@
+# Setting up Open Knowledge
+
+This repository is an Open Knowledge (OK) project: its `.md` / `.mdx` files are CRDT documents, and agents work with them through the Open Knowledge MCP server. If your agent's `mcp__open-knowledge__*` tools aren't available, the project just isn't connected on this machine yet. Connect it at whatever depth you need — each rung adds capability, and you can stop at the first one that covers your task.
+
+**Canonical, always-current instructions:** <https://openknowledge.ai/docs/get-started/quickstart>. The rungs below are a quick orientation; the docs are authoritative (release channels and download links move, so this file deliberately points there rather than pinning them).
+
+## Rung 1 — Agent tooling, no install
+
+Approve the committed `.mcp.json` in your agent client (Claude Code, Cursor, Codex, …). It launches the OK MCP server on demand via `npx`, so there is nothing to install. This gives you the read tools (`exec`, `search`) over the docs plus the fs-direct write tools (`write` / `edit` for markdown and skills).
+
+This rung does **not** start a collaboration server, so it does not give you live CRDT co-editing or the browser preview — those need rung 2.
+
+## Rung 2 — Full editing + live preview, via the CLI
+
+Install the OK CLI and start a local server:
+
+```bash
+npm install -g @inkeep/open-knowledge   # or run it ad hoc with: npx @inkeep/open-knowledge
+ok start
+```
+
+`ok start` runs the collaboration server and serves a browser preview at the URL it prints — no GUI required. Markdown writes now land in the live CRDT and the preview updates as you (or an agent) edit.
+
+## Rung 3 — Desktop app, optional
+
+For a native editor with the file tree, property panel, and built-in preview, install the OK Desktop app. The quickstart link above has the current download — it tracks the latest release, so grab it there rather than from a pinned URL.

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

@@ -0,0 +1,165 @@
+---
+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 Open Knowledge 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: "Open Knowledge 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"
+  author: "Inkeep"
+  repository: "https://github.com/inkeep/open-knowledge"
+---
+
+# Writing an Open Knowledge skill
+
+You are helping the user author an **Agent Skill** — a `SKILL.md` file (plus
+optional `references/` and `scripts/`) that teaches an AI agent how to do a
+recurring task. In Open Knowledge a skill is a first-class, versioned,
+installable artifact: you author it with the `write` / `edit` skill verbs, then
+`install` it into the user's editors.
+
+Skills earn their keep by being **recognized at the right moment** and **followed
+faithfully**. Most of the craft is in two places: a `description` that triggers
+reliably, and a body short and concrete enough that the agent actually does what
+it says. Work the stages below in order, but jump to where the user already is.
+
+## Stage 1 — Capture intent and classify the skill
+
+Ask only what you can't infer:
+
+- **What recurring task** should this skill handle? Get one concrete example.
+- **Skill type**, because it sets how much rigor to apply:
+  - **Reference / technique** (most skills) — "how to do X." Prose body, examples.
+  - **Discipline** — enforces a behavior the agent tends to skip under pressure
+    (e.g. "always write a failing test first"). These need the RED baseline +
+    pressure-testing in Stage 4–6; reference skills don't.
+- **Degrees of freedom** (calibrate body precision to task fragility):
+  *high* (free prose — judgment tasks), *medium* (parameterized steps), *low*
+  (a fixed `scripts/` command — when any deviation breaks the result). Don't
+  over-specify a judgment task or under-specify a fragile one.
+
+## Stage 2 — Resolve scope FIRST (never infer silently)
+
+Scope determines where the skill lives and where `install` projects it. This is
+the user's decision and has different blast radius — make it explicit.
+
+| Scope | Lives in | `install` projects to |
+| --- | --- | --- |
+| **Global** | `~/.ok/skills/<name>/` (your user store) | your editors, in **every** project |
+| **Project** | `<kb>/.ok/skills/<name>/` (this KB, shared via git) | this project's editors; teammates get it on `git pull` |
+
+Default heuristic: inside an OK project and the task is specific to it → **project**;
+"for all my work / globally" → **global**; otherwise ask one question. State the
+choice and its consequence before writing.
+
+## Stage 3 — Plan the contents
+
+- **Body** = the durable, reusable instructions — under ~500 lines. If it's
+  growing past that, move depth into `references/<topic>.md` (loaded only when
+  needed) and point at it from the body. For a **project** skill the reference
+  auto-connects in the graph either way, so a backticked `` `references/<topic>.md` ``
+  path is fine; use a `[[references/<topic>]]` wiki-link only when you want the
+  mention to be a clickable inline link. For a **global** skill use a plain
+  backtick path — global references aren't graph docs, so a wiki-link there
+  dangles. Keep references **one level deep**.
+- **Do NOT include**: a README/CHANGELOG/QUICK_REFERENCE, install instructions
+  for the skill itself, version histories, or anything host-specific. The skill
+  is the instructions, not documentation about the instructions.
+- For a **discipline** skill, plan the failure mode you're correcting and how
+  you'll prove the skill fixes it (Stage 4).
+
+## Stage 4 — RED baseline (discipline skills only)
+
+Before writing the skill, run the scenario WITHOUT it and capture what the agent
+does wrong — verbatim, including its rationalizations ("the test is trivial so I
+skipped it"). Those rationalizations are the exact loopholes the skill body must
+close. If you have a running server, use the agent simulator
+(`cd packages/app && bun run src/server/agent-sim.ts`) as the executor; otherwise
+reason through the baseline transcript with the user. Skip this stage for plain
+reference skills.
+
+## Stage 5 — Draft the skill
+
+Author the source with the skill verb (fs-direct; a live preview updates if a
+server is running):
+
+```
+write({ skill: { name: "<lowercase-hyphen-name>", description: "<triggers>", body: "<markdown>", scope: "project" } })
+```
+
+Frontmatter contract (validated on write — get it right):
+- `name` — lowercase letters, digits, hyphens; ≤64; **equals the directory**.
+- `description` — **≤1024 chars, no XML tags, no `version` field**. See Stage 7.
+- Nothing else. OK never injects its own frontmatter; bookkeeping lives in `.ok/`.
+
+Write the body as direct instructions to the agent (imperative, second person),
+concrete over abstract.
+
+Add depth files — `references/*.md` (loaded on demand) and `scripts/*` (shown as
+text, never executed by OK) — through the skill verbs, never native `Write`/`cat`:
+
+```
+# write one or more bundle files (independent of body — no need to resend SKILL.md)
+write({ skill: { name: "<name>", files: [{ path: "references/tiers.md", content: "..." }] } })
+
+# surgical edit inside one bundle file (mirrors edit({ document }))
+edit({ skill: { name: "<name>", file: "references/tiers.md", find: "...", replace: "..." } })
+
+# list the bundle, then read one file (no native cat)
+skills({ name: "<name>" })                         # → files: [{ path, kind }]
+skills({ name: "<name>", file: "references/tiers.md" })   # → { path, kind, text }
+
+# delete specific bundle files (omit `files` to delete the whole skill)
+delete({ skill: { name: "<name>", files: ["references/tiers.md"] } })
+```
+
+Paths are skill-relative and must live under `references/` or `scripts/` (one
+level deep). A project `.md` reference becomes a live content doc that
+auto-connects to its SKILL in the graph regardless of how the body mentions it —
+a backticked `` `references/<name>.md` `` path joins the graph just like a
+`[[references/<name>]]` wiki-link. Reach for a wiki-link (or
+`[label](references/<name>.md)`) only when you want a clickable inline link.
+Global skills are different: their references aren't graph docs, so use a plain
+backtick path there — a wiki-link would dangle.
+
+## Stage 6 — GREEN eval + refactor
+
+Re-run the scenario WITH the skill. For a discipline skill, **pressure-test**:
+combine 2–3 pressures (time, authority, sunk cost) and confirm the agent still
+follows the rule — then patch any loophole and re-test (`references/pressure-testing.md`).
+For a reference skill, confirm the agent now does the task correctly and the body
+isn't longer than it needs to be. Cut anything the agent already knows.
+
+## Stage 7 — Optimize the description (this is what makes the skill fire)
+
+The `description` is the **only** thing the agent sees when deciding whether to
+load the skill. Get it right (`references/description-optimization.md`):
+- **Triggers, not a summary.** Say WHEN to use it, in the user's words and
+  phrasings — NOT a recap of the body. Summarizing the workflow in the
+  description makes the agent follow the description and skip the body.
+- **Concrete and a little pushy** to fight under-triggering: name the situations,
+  verbs, and phrasings that should activate it.
+- Sanity-check against near-miss queries: phrasings that SHOULD trigger it and
+  adjacent ones that should NOT.
+
+## Stage 8 — Install (the deliberate Draft → Installed step)
+
+Drafting doesn't change the agent's behavior until you project it:
+
+```
+install({ name: "<name>" })
+```
+
+This fans the validated skill into the project's configured editors
+(`.claude/skills/`, `.cursor/skills/`, `.codex/skills/`, `.opencode/skills/`). For a project skill,
+commit `.ok/skills/<name>/` and the projections so teammates get it on pull. Edit
+later with `edit({ skill })` then `install` again; `delete({ skill })` removes it
+and uninstalls. Roll back a **project** skill with `history({ skill })` →
+`restore_version({ skill, version })` — global skills are unversioned in this
+build, so they have no history to restore.
+
+## Reminders
+
+- Prefer ONE good skill over many overlapping ones; split only when triggers diverge.
+- Avoid blanket ALWAYS/NEVER rules without a stated reason — they read as noise and
+  get ignored. Explain the why.
+- A skill that ships executable `scripts/` is projected verbatim into another
+  agent's trust domain — only include scripts the user has reviewed.

package/dist/assets/skills/write-skill/references/description-optimization.md

@@ -0,0 +1,34 @@
+# Optimizing a skill's `description`
+
+The `description` is the **entire** signal the agent uses to decide whether to
+load a skill. The body doesn't exist until the description fires. Optimize it
+last, deliberately.
+
+## Rules
+
+1. **Triggers, not a summary.** Describe WHEN to reach for the skill, in the
+   user's words. Do NOT recap what the body does — empirically, summarizing the
+   workflow in the description makes the model follow the description and skip
+   the body (the classic "did one review instead of the two the body required").
+2. **Be concrete and slightly pushy.** Under-triggering (the skill never loads)
+   is the common failure. Name the situations, the verbs, and the actual
+   phrasings a user would type. List several; don't rely on one abstract clause.
+3. **Stay inside the contract.** ≤1024 characters, no XML/angle-bracket tags, no
+   `version` field. A tag like `<thing>` breaks the loader.
+4. **Disambiguate from neighbors.** If a sibling skill is close, add a line on
+   when to use THIS one vs the other.
+
+## A lightweight near-miss check
+
+1. Write ~10 phrasings that SHOULD trigger the skill and ~5 adjacent ones that
+   should NOT (they belong to a different skill or no skill).
+2. Read the description cold and predict, for each phrasing, whether it would
+   fire. Every should-fire that you'd miss is a gap; every should-not that fires
+   is over-reach.
+3. Edit the description to close the gaps without grabbing the should-nots.
+   Prefer adding concrete trigger phrasings over broadening vague ones.
+
+## Shape
+
+Lead with the dominant trigger ("Use when the user wants to…"), then enumerate
+concrete situations and phrasings, then any disambiguation. Keep it scannable.

package/dist/assets/skills/write-skill/references/pressure-testing.md

@@ -0,0 +1,40 @@
+# Pressure-testing a discipline skill
+
+A **discipline** skill enforces a behavior the agent tends to abandon under
+pressure ("write the failing test first", "get review before merging"). A skill
+that holds in the easy case but folds under pressure hasn't done its job. Test
+the hard case.
+
+## The loop (RED → GREEN → harden)
+
+1. **RED — baseline without the skill.** Run the scenario with no skill loaded.
+   Capture what the agent does AND its **rationalizations**, verbatim ("the
+   change is tiny, so skipping the test is fine"). Those exact rationalizations
+   are the loopholes the skill body must name and close.
+2. **GREEN — minimal skill.** Write the smallest body that defeats those specific
+   rationalizations. Re-run; confirm the behavior changed.
+3. **Harden under combined pressure.** Re-run with **2–3 pressures stacked** and
+   force a concrete choice:
+   - *Time*: "this is urgent, ship it now."
+   - *Authority*: "the lead said it's fine to skip."
+   - *Sunk cost*: "you already wrote 200 lines; redoing it wastes the work."
+   - Then: "What DO you do?" — make it choose, don't accept a hedge.
+4. Any new rationalization that slips through → add it to the body's
+   rationalization table and re-test. Repeat until it holds.
+
+## Rationalization table (put this in the skill body)
+
+A short table the agent reads when tempted:
+
+| The agent thinks… | Reality |
+| --- | --- |
+| "This case is too trivial to test." | Trivial code breaks too; the test is cheap. |
+| "I'm confident it works." | Confidence isn't verification; write the test. |
+
+## Running it
+
+With a server: drive the scenarios through the agent simulator
+(`cd packages/app && bun run src/server/agent-sim.ts`). Without one: walk the
+pressured prompt with the user and read the response for the rule holding.
+Read the full transcript, not just the final answer — discipline fails in the
+reasoning, not always in the output.

package/dist/{banner-DBiyrzNA.mjs → banner-BxCFCyu8.mjs}

@@ -1,3 +1,3 @@
-import{a as e,i as t,n,t as r}from"./colors-CBY1ibtz.mjs";const i={single:{topLeft:`┌`,top:`─`,topRight:`┐`,right:`│`,bottomRight:`┘`,bottom:`─`,bottomLeft:`└`,left:`│`},double:{topLeft:`╔`,top:`═`,topRight:`╗`,right:`║`,bottomRight:`╝`,bottom:`═`,bottomLeft:`╚`,left:`║`},round:{topLeft:`╭`,top:`─`,topRight:`╮`,right:`│`,bottomRight:`╯`,bottom:`─`,bottomLeft:`╰`,left:`│`},bold:{topLeft:`┏`,top:`━`,topRight:`┓`,right:`┃`,bottomRight:`┛`,bottom:`━`,bottomLeft:`┗`,left:`┃`},singleDouble:{topLeft:`╓`,top:`─`,topRight:`╖`,right:`║`,bottomRight:`╜`,bottom:`─`,bottomLeft:`╙`,left:`║`},doubleSingle:{topLeft:`╒`,top:`═`,topRight:`╕`,right:`│`,bottomRight:`╛`,bottom:`═`,bottomLeft:`╘`,left:`│`},classic:{topLeft:`+`,top:`-`,topRight:`+`,right:`|`,bottomRight:`+`,bottom:`-`,bottomLeft:`+`,left:`|`},arrow:{topLeft:`↘`,top:`↓`,topRight:`↙`,right:`←`,bottomRight:`↖`,bottom:`↑`,bottomLeft:`↗`,left:`→`}}.round;function a(a){let o=[],s=`${a.name} v${a.version}`;o.push({plain:s,colored:r(s)}),o.push({plain:``,colored:``});let c=a.apiUrl?`Editor:  `:`Local:   `;if(o.push({plain:`${c}${a.localUrl}`,colored:`${c}${e(t(a.localUrl),a.localUrl)}`}),a.apiUrl){let t=`API:     `;o.push({plain:`${t}${a.apiUrl}`,colored:`${t}${n(e(a.apiUrl,a.apiUrl))}`})}if(a.networkUrl){let n=`Network: `;o.push({plain:`${n}${a.networkUrl}`,colored:`${n}${e(t(a.networkUrl),a.networkUrl)}`})}if(a.nextSteps&&a.nextSteps.length>0){o.push({plain:``,colored:``});for(let e of a.nextSteps)o.push({plain:e,colored:n(e)})}o.push({plain:``,colored:``});let l=`Press Ctrl+C to stop`;o.push({plain:l,colored:n(l)});let u=Math.max(...o.map(e=>e.plain.length)),d=u+4,f=`  ${i.topLeft}${i.top.repeat(d)}${i.topRight}`,p=`  ${i.bottomLeft}${i.bottom.repeat(d)}${i.bottomRight}`;return[``,f,...o.map(e=>{let t=u-e.plain.length;return`  ${i.left}${` `.repeat(2)}${e.colored}${` `.repeat(t+2)}${i.right}`}),p,``].join(`
+import{a as e,i as t,n,t as r}from"./colors-8SzMRIVy.mjs";const i={single:{topLeft:`┌`,top:`─`,topRight:`┐`,right:`│`,bottomRight:`┘`,bottom:`─`,bottomLeft:`└`,left:`│`},double:{topLeft:`╔`,top:`═`,topRight:`╗`,right:`║`,bottomRight:`╝`,bottom:`═`,bottomLeft:`╚`,left:`║`},round:{topLeft:`╭`,top:`─`,topRight:`╮`,right:`│`,bottomRight:`╯`,bottom:`─`,bottomLeft:`╰`,left:`│`},bold:{topLeft:`┏`,top:`━`,topRight:`┓`,right:`┃`,bottomRight:`┛`,bottom:`━`,bottomLeft:`┗`,left:`┃`},singleDouble:{topLeft:`╓`,top:`─`,topRight:`╖`,right:`║`,bottomRight:`╜`,bottom:`─`,bottomLeft:`╙`,left:`║`},doubleSingle:{topLeft:`╒`,top:`═`,topRight:`╕`,right:`│`,bottomRight:`╛`,bottom:`═`,bottomLeft:`╘`,left:`│`},classic:{topLeft:`+`,top:`-`,topRight:`+`,right:`|`,bottomRight:`+`,bottom:`-`,bottomLeft:`+`,left:`|`},arrow:{topLeft:`↘`,top:`↓`,topRight:`↙`,right:`←`,bottomRight:`↖`,bottom:`↑`,bottomLeft:`↗`,left:`→`}}.round;function a(a){let o=[],s=`${a.name} v${a.version}`;o.push({plain:s,colored:r(s)}),o.push({plain:``,colored:``});let c=a.apiUrl?`Editor:  `:`Local:   `;if(o.push({plain:`${c}${a.localUrl}`,colored:`${c}${e(t(a.localUrl),a.localUrl)}`}),a.apiUrl){let t=`API:     `;o.push({plain:`${t}${a.apiUrl}`,colored:`${t}${n(e(a.apiUrl,a.apiUrl))}`})}if(a.networkUrl){let n=`Network: `;o.push({plain:`${n}${a.networkUrl}`,colored:`${n}${e(t(a.networkUrl),a.networkUrl)}`})}if(a.nextSteps&&a.nextSteps.length>0){o.push({plain:``,colored:``});for(let e of a.nextSteps)o.push({plain:e,colored:n(e)})}o.push({plain:``,colored:``});let l=`Press Ctrl+C to stop`;o.push({plain:l,colored:n(l)});let u=Math.max(...o.map(e=>e.plain.length)),d=u+4,f=`  ${i.topLeft}${i.top.repeat(d)}${i.topRight}`,p=`  ${i.bottomLeft}${i.bottom.repeat(d)}${i.bottomRight}`;return[``,f,...o.map(e=>{let t=u-e.plain.length;return`  ${i.left}${` `.repeat(2)}${e.colored}${` `.repeat(t+2)}${i.right}`}),p,``].join(`
 `)}export{a as renderBanner};
-//# sourceMappingURL=banner-DBiyrzNA.mjs.map
+//# sourceMappingURL=banner-BxCFCyu8.mjs.map