@inkeep/open-knowledge 0.9.0-beta.32 → 0.9.0-beta.34

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.9.0-beta.32"
+  version: "0.9.0-beta.34"
   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.9.0-beta.32"
+  version: "0.9.0-beta.34"
   author: "Inkeep"
   repository: "https://github.com/inkeep/open-knowledge"
 ---
@@ -29,7 +29,7 @@ Everything below is depth. Read on demand.
 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 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), `share_link` (GitHub-substrate share URL for a doc; 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** — `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'|'declare-field'|'remove-field'`). `declare-field` declares a named field of a given type on every doc in a folder without supplying a value — each doc fills in its own; `remove-field` deletes the declaration.
+- **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'`). `set-rule` writes a folder's own frontmatter (open-shape, like a doc's); `write-template`/`delete-template` manage the folder's templates (what new docs start with).
 - **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).
 
@@ -56,7 +56,7 @@ Why: native tools skip frontmatter, backlinks, shadow-repo activity, and project
 ## Reads — examples
 
 - Read a file: `exec("cat <path>.md")` — contents + full rich enrichment.
-- List a directory: `exec("ls -A <dir>")` — per-child frontmatter, recursive markdown counts, most-recently-updated doc per subdir, folder-level `frontmatter_defaults` + `templates_available`. Prefer `-A` over plain `ls` to surface dot-prefixed entries (`.ok/`, `.okignore`) without the noisy `.`/`..` rows that `-a` adds.
+- List a directory: `exec("ls -A <dir>")` — per-child frontmatter, recursive markdown counts, most-recently-updated doc per subdir, the folder's own `title`/`description`/`tags` + `templates_available`. Prefer `-A` over plain `ls` to surface dot-prefixed entries (`.ok/`, `.okignore`) without the noisy `.`/`..` rows that `-a` adds.
 - Literal search: `exec("grep -rn <term> <dir> | head -5")` — matches + enrichment on matched files.
 - Ranked search: `search({ query })` — cmd-K parity (title boost + body BM25 + recency); use when picking the best doc, not when listing every occurrence.
 
@@ -100,6 +100,8 @@ OK Electron and `ok ui` share `ui.lock`; when a second UI binds a different port
 
 Call `write_document` / `edit_document` as soon as you have content. Native `Edit` / `sed` / direct `Write` on in-scope markdown is forbidden — it bypasses the CRDT and loses agent attribution in the shadow repo.
 
+To author an MDX doc (the KB renders MDX/JSX components), pass a `.mdx` `docName` on the create: `write_document({ docName: "guides/widget.mdx", markdown, position: "replace" })` lands `guides/widget.mdx`. A `.md` or extension-less `docName` lands `.md`. An existing doc keeps its on-disk extension regardless of the suffix you pass — changing it in place isn't available via the MCP today.
+
 To delete a doc, call `delete_document` — never `rm` / `unlink` / native `Bash` removal on in-scope markdown. The MCP path closes open agent sessions and unloads the doc from Hocuspocus before unlinking; native `rm` desynchronizes those. Deletion is irreversible — call `version({ action: "save" })` first if you may need to roll back (restore via `version({ action: "rollback" })`; list snapshots via `get_history`), and `links({ kind: "backlinks", docName })` first if you want to fix referrers that will become redlinks. To move or rename a doc instead of delete + rewrite, use `rename({ from, to })` — it auto-detects file vs folder and rewrites incoming references atomically.
 
 **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.
@@ -238,32 +240,31 @@ tags: [relevant, tags]
 ---
 ```
 
-Folder defaults live in opt-in nested `<folder>/.ok/frontmatter.yml` (values that cascade down to every doc); schema declarations live in `<folder>/.ok/schema.yml` (named fields without values — every doc in the folder gets the slot, each doc fills in its own value); templates live in `<folder>/.ok/templates/`. **Most folders have NO `.ok/`** — sparse, lazy-create, auto-clean. A folder gets one only when it declares defaults, declares fields, or carries templates.
+Two folder mechanisms, both opt-in and nested: **folder frontmatter** in `<folder>/.ok/frontmatter.yml` (the folder's own properties — open-shape like a doc's, with `title` / `description` / `tags` as conventional keys the UI surfaces; describes the folder, self-only, does NOT flow into child docs) and **templates** in `<folder>/.ok/templates/` (the single mechanism for what new docs in a folder start with). **Most folders have NO `.ok/`** — sparse, lazy-create, auto-clean. A folder gets one only when it carries its own frontmatter or a template.
 
 ```
 content-root/
 ├── .ok/                        ← project root .ok/ (config.yml, cache)
 ├── meetings/
 │   ├── .ok/
-│   │   ├── frontmatter.yml     ← folder defaults
-│   │   ├── schema.yml          ← field declarations (each doc fills in its own value)
+│   │   ├── frontmatter.yml     ← this folder's own title/description/tags
 │   │   └── templates/
-│   │       └── prep-notes.md
+│   │       └── prep-notes.md   ← what new meeting docs start with
 │   └── 2026-05-01.md
-└── research/                   ← no .ok/ — inherits root cascade
+└── research/                   ← no .ok/
     └── auth-providers.md
 ```
 
-**Cascade merge:** scalars (`title`, `description`) replace last-wins root → leaf; arrays (`tags`) union-and-dedup; file frontmatter wins per-scalar over folder defaults, tags union with the cascade.
+A doc's frontmatter is exactly its own on-disk YAML — folder frontmatter never overlays values onto it. Give new docs starting properties with a template, not with folder frontmatter.
 
 ### Read the folder before writing (MUST)
 
-Before creating or editing docs in a folder, **always** call `exec("ls -A <folder>")` once. The response carries `frontmatter_defaults` (the merged cascade) + `templates_available` (the template menu for `write_document({ template })`). Skipping this is how agents land docs that violate folder discipline.
+Before creating or editing docs in a folder, **always** call `exec("ls -A <folder>")` once. The response carries the folder's own `title`/`description`/`tags` + `templates_available` (the template menu for `write_document({ template })`). Skipping this is how agents land docs that violate folder discipline.
 
 Pre-write checklist:
 
-0. **First-contact check.** If `frontmatter_defaults` AND `templates_available` are empty AND `exec("ls -A")` shows substantial content elsewhere, the project hasn't been onboarded — STOP and invoke `discover` (Workflow tools below). Skip on subsequent writes once confirmed.
-1. **Read `frontmatter_defaults`** — don't redeclare keys the cascade already provides; let inheritance carry them.
+0. **First-contact check.** If the folder has no frontmatter of its own AND `templates_available` is empty AND `exec("ls -A")` shows substantial content elsewhere, the project hasn't been onboarded — STOP and invoke `discover` (Workflow tools below). Skip on subsequent writes once confirmed.
+1. **Read the folder's description** — its `title`/`description`/`tags` tell you what the folder is for. (These describe the folder; they are NOT defaults the doc inherits.)
 2. **Read `templates_available`** — each entry has `name`, `title`, `description`, `scope` (`local` / `inherited`). If one matches, **prefer it** over free-form markdown (it's the folder's contract — templates carry frontmatter + body structure hand-authored docs routinely miss).
 3. **Read recent siblings** — new docs should match the shape of existing ones (filename, frontmatter, body structure).
 4. **Confirm content scope** — `content.dir` (`.ok/config.yml`) defines the root. `.gitignore` / `.okignore` (nested at any depth) define exclusions.
@@ -285,23 +286,22 @@ Templates make folder structure durable. Create them proactively:
 
 Note new templates in chat ("saved as a template at `meetings/.ok/templates/prep-notes.md` for next time") so the user sees the discipline grew.
 
-### When to declare folder defaults (MUST when a pattern emerges)
+### When recurring per-doc properties emerge (MUST when a pattern emerges)
 
-If you're writing the same frontmatter (tags, title prefix) on multiple siblings, call `folder_config({ action: "set-rule" })` once and let the cascade do it. Pair with a template when the body skeleton also repeats.
+If you're writing the same frontmatter (tags, status, a title prefix) on multiple siblings, bake those starting values into a **template** (`folder_config({ action: "write-template" })`) — that's the single mechanism for new-doc starting properties. Folder frontmatter does not cascade values into docs.
 
-### Editing folder defaults
+### Editing a folder's own description
 
 ```ts
 folder_config({
   action: "set-rule",
   rules: [
-    { match: "meetings/**", frontmatter: { title: "Meetings", tags: ["meeting"] } },
-    { match: "meetings/prep-notes/**", frontmatter: { tags: ["meeting", "prep"] } },
+    { match: "meetings/**", frontmatter: { title: "Meetings", description: "Meeting notes", tags: ["meeting"] } },
   ],
 })
 ```
 
-Each `match` resolves to a SINGLE target folder. Multi-folder globs (`specs/*/evidence/**`) are rejected with `MULTI_FOLDER_GLOB` — split per folder. Remove a rule by passing empty `frontmatter: {}` — file deletes and `.ok/` auto-cleans if no other tenant remains.
+`frontmatter` is open-shape — any key about the folder itself, exactly like a doc's frontmatter (`title` / `description` / `tags` are conventional keys the UI surfaces). It's self-only: it describes the folder and does NOT flow into child docs — put per-doc starting values in a template instead. Each `match` resolves to a SINGLE target folder. Multi-folder globs (`specs/*/evidence/**`) are rejected with `MULTI_FOLDER_GLOB` — split per folder. Remove a rule by passing empty `frontmatter: {}` — file deletes and `.ok/` auto-cleans if no other tenant remains.
 
 ### Creating templates
 
@@ -404,11 +404,11 @@ The skill carries the trigger ("KB content changed this turn — go look"). The
 | Finish a turn that changed KB content           | move on without checking for a log                                                 | check for a `log.md` and follow its contract per Log discipline                    |
 | Add an image                                    | empty alt `![](./x.png)` or generic alt `![image](./x)`                            | meaningful alt + source caption below                                             |
 | Catalog folder contents                         | create `INDEX.md` hub file                                                         | `folder_config({ action: "set-rule", rules: [...] })` writes `<folder>/.ok/frontmatter.yml` |
-| Write a doc in an unfamiliar folder             | go straight to `write_document` with hand-authored markdown                        | `exec("ls -A <folder>")` first — read `frontmatter_defaults` + `templates_available` before writing |
+| Write a doc in an unfamiliar folder             | go straight to `write_document` with hand-authored markdown                        | `exec("ls -A <folder>")` first — read the folder description + `templates_available` before writing |
 | Land in an existing repo without orienting      | go straight to `write_document` when no folder frontmatter / templates exist       | invoke `discover` once for the project — extracts conventions from siblings, sets folder frontmatter + templates, activates the link graph |
 | Author a doc when a matching template exists    | `write_document({ markdown: "..." })` from scratch                                 | `write_document({ template, position: "replace" })` — templates carry the folder's frontmatter + body discipline |
 | Change a doc's title / tags                     | `edit_document` to swap the YAML (rejected — HTTP 400 frontmatter-intersect)       | `edit_frontmatter({ docName, patch })` for 1-2 keys; `write_document({ position: "replace", markdown })` for full rewrites |
-| Repeat the same frontmatter on sibling docs     | hand-set identical `tags` / `title` prefix on every new file                       | `folder_config({ action: "set-rule" })` once — the cascade carries it to every child |
+| Repeat the same frontmatter on sibling docs     | hand-set identical `tags` / `title` prefix on every new file                       | `folder_config({ action: "write-template" })` once — new docs start from the template |
 | Re-derive the same body skeleton repeatedly     | copy-paste the structure from a sibling each time                                  | `folder_config({ action: "write-template" })` once, then pick from `templates_available` thereafter |
 | Scaffold a new folder for a doc category        | set folder rule for frontmatter and stop there                                     | pair `folder_config({ action: "set-rule" })` with `folder_config({ action: "write-template" })` in the same turn |
 | Delete a markdown doc                           | `Bash: rm` / `unlink` / native deletion on in-scope `.md`                          | `delete_document` — `version({ action: "save" })` first if rollback may be needed |
@@ -445,8 +445,8 @@ If `write_document` or `edit_document` returns a "Hocuspocus server is not runni
 
 ## Scope recap
 
-Open Knowledge looks for documents under the resolved `content.dir` (discoverable at runtime via `get_config({ path: ['content', 'dir'] })`). `.gitignore` and `.okignore` (at the project root and at any folder depth) define exclusions. Folder defaults + templates live in nested `<folder>/.ok/frontmatter.yml` + `<folder>/.ok/templates/` files — NOT in `.ok/config.yml`.
+Open Knowledge looks for documents under the resolved `content.dir` (discoverable at runtime via `get_config({ path: ['content', 'dir'] })`). `.gitignore` and `.okignore` (at the project root and at any folder depth) define exclusions. A folder's own metadata + templates live in nested `<folder>/.ok/frontmatter.yml` + `<folder>/.ok/templates/` — NOT in `.ok/config.yml`.
 
 Default mental model (no jargon): **every `.md` and `.mdx` under `content.dir`** not excluded by `.gitignore` or `.okignore` is an Open Knowledge document — including under `specs/`, `reports/`, `docs/`, etc. Read `.okignore` (and any nested `.okignore` files) once per turn to know what's excluded.
 
-**First session in this project?** If `frontmatter_defaults` and `templates_available` are empty for substantial folders, the project hasn't been onboarded yet — invoke `discover` (Workflow tools table) before writing. Once onboarded, the cascade carries the discipline.
+**First session in this project?** If substantial folders have no frontmatter of their own and no `templates_available`, the project isn't onboarded — invoke `discover` (Workflow tools table) before writing.