@inkeep/open-knowledge 0.9.1-beta.2 → 0.9.2-beta.10

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.1-beta.2"
+  version: "0.9.2-beta.10"
   author: "Inkeep"
   repository: "https://github.com/inkeep/open-knowledge"
 ---

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

@@ -0,0 +1,48 @@
+---
+name: open-knowledge-pack-entity-vault
+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 Open Knowledge MCP server. Installed project-local by `ok seed --pack entity-vault`."
+metadata:
+  pack: "entity-vault"
+  author: "Inkeep"
+  repository: "https://github.com/inkeep/open-knowledge"
+---
+# Entity vault pack (GBrain-compatible) — how to work here
+
+A typed-entity vault inspired by Garry Tan's gbrain. Each entity is a dossier; the agent keeps dossiers current by extracting entities from meeting notes and original thinking. This skill holds those behaviors so templates and folder descriptions stay clean. The Markdown shape is **GBrain-compatible**: if the external `gbrain` CLI is installed, it can import/sync the same vault.
+
+> Pack guidance. The platform `open-knowledge` skill still governs every markdown operation.
+
+## The dossier convention (the load-bearing rule)
+
+Every dossier in `people/`, `companies/`, and `concepts/` has two parts, split by an explicit `--- timeline ---` separator:
+
+1. **Compiled truth** (above `--- timeline ---`) — your current best understanding. Rewrite it as new evidence changes the synthesis.
+2. **Timeline** (below `--- timeline ---`) — append-only dated bullets in the parseable form `- **YYYY-MM-DD** | source | @author — evidence. Confidence: …`. **Never edit existing timeline entries; only append.**
+
+When a new fact arrives, route it: update **compiled truth** if it changes current understanding, or append a timeline bullet if it's raw evidence. The explicit separator and dated-bullet shape are what keep the vault parseable by GBrain's import/sync.
+
+## Folders
+
+- **`people/`**, **`companies/`**, **`concepts/`** — dossiers (compiled truth + timeline). Frontmatter `type: person|company|concept`.
+- **`meetings/`** — meeting notes (`YYYY-MM-DD-<slug>.md`); `attendees:` should match dossier filenames in `people/`. The verbatim record — do NOT rewrite it.
+- **`originals/`** — your own untransformed thinking; authoritative source material. Frontmatter `type: original`.
+- **`media/`** — bulk transcripts, voice notes, large attachments; often `.okignore`-d to keep the index light.
+
+## Links
+
+Prefer path-qualified wikilinks when entity identity matters: `[[companies/acme|Acme]]`, `[[people/jane-founder|Jane Founder]]`, `[[concepts/agent-runtime-observability|agent-runtime observability]]`. Path-qualified links resolve to the right dossier under GBrain's typed extraction.
+
+## Agent behaviors
+
+- After a meeting note lands, extract entity mentions and append timeline bullets to each referenced dossier (cite the meeting by markdown link). Stub any mentioned entity not yet captured.
+- Treat `originals/` as authoritative (the user's own words, not inferences).
+- Surface entity-to-entity edges (person ↔ company, concept hubs) when both ends exist.
+
+## gbrain CLI (optional)
+
+This pack ships the Markdown half (folders + templates + this skill); OK is the cockpit/editor/review layer. If the external `gbrain` CLI is installed (`~/.gbrain/`), it adds scheduled enrichment: `gbrain dream` (nightly maintenance), `gbrain briefing`, `gbrain soul-audit`, and `gbrain import`/`gbrain sync --repo` for DB-backed indexing. The root files (`USER.md`, `SOUL.md`, `ACCESS_POLICY.md`, `HEARTBEAT.md`) are read by those skills; fill them in by hand or via `gbrain soul-audit`. None of it is required to use the vault — interop is plain Markdown + Git.
+
+## Templates
+
+Create with `write_document({ template: "<name>", … })`. Templates carry the structure (including the compiled-truth / `--- timeline ---` separator) plus short inline reminders at the point of use; this skill holds the full convention, so prefer it as the canonical reference if the two ever disagree.

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

@@ -0,0 +1,66 @@
+---
+name: open-knowledge-pack-knowledge-base
+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 ingest / research / consolidate MCP tools. 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 Open Knowledge MCP server. Installed project-local by `ok seed --pack knowledge-base`."
+metadata:
+  pack: "knowledge-base"
+  author: "Inkeep"
+  repository: "https://github.com/inkeep/open-knowledge"
+---
+# Knowledge Base pack — how to work here
+
+This project uses the **source-grounded knowledge-base** layout. The whole point is a closed evidence loop: nothing canonical exists without a traceable chain back to a preserved source. This skill holds the workflow so the templates and `log.md` can stay clean — when you create a doc from a template you get structure, and the *how* lives here.
+
+> This skill is pack guidance. The platform `open-knowledge` skill (read/write/preview/grounding rules) still governs every markdown operation — this layers the KB workflow on top.
+
+## The three layers
+
+```
+external-sources/   raw sources, saved verbatim     (produced by `ingest`)
+      ↓ cite
+research/           provisional analysis            (produced by `research`)
+      ↓ promote
+articles/           canonical, decided knowledge     (produced by `consolidate`)
+```
+
+The loop is **ingest → research → consolidate**. Every downstream claim traces upstream to a preserved source. Cite local paths in `external-sources/`, never bare web URLs — the KB must survive link rot.
+
+## Per-folder rules
+
+**`external-sources/`** — Raw sources saved verbatim, not just cited: the actual fetched text of URLs, extracted text of PDFs, copies of referenced files. Each file's frontmatter carries the original URL, access date, and any author/publisher metadata. Produced by `ingest` (applies whether the user shared the URL or you fetched it yourself to ground a claim). Immutable after capture — update only to refresh a stale fetch. **No analysis here**; that belongs in `research/`.
+
+**`research/`** — Provisional analysis synthesizing external sources. Produced by `research`. Every factual claim cites a specific doc in `external-sources/` (or an inline URL if ingest was skipped); no unsourced assertions. Keep the `sources:` frontmatter list aligned with the docs actually linked in the body. Promote to `articles/` via `consolidate` once the team decides the findings are stable.
+
+**`articles/`** — Canonical knowledge, committed after a team decision. Produced by `consolidate`. Carries a `supersedes:` chain tying back to the `research/` docs it replaces (which in turn cite `external-sources/`) so the full evidence chain is traceable without leaving the repo. Source-of-truth for the domain; update only when a new decision supersedes it.
+
+## Status flow
+
+| Layer | `status` | Set when |
+|---|---|---|
+| `research/` | `provisional` | created |
+| `articles/` | `canonical` | promoted by `consolidate` after a decision |
+
+When a new article supersedes an older one, add the older article's path to the new one's `supersedes:` list.
+
+## Log discipline (MUST)
+
+There is a `log.md` at the project root. **Append one dated entry after any turn that creates, edits, or restructures content** — one entry per turn, not per file. Silent edits break the audit trail.
+
+Log: `ingest` runs (new sources), `research` / `consolidate` runs (provisional or canonical articles), direct `write_document` / `edit_document` / rename / delete outside the three loop tools, `discover` runs, folder restructures, and `.ok/config.yml` changes.
+
+**Reference docs as markdown links, not bare paths** — `[path/to/doc](./path/to/doc.md)`, so the entry shows up in `links({ kind: "backlinks" })` for those docs. A bare path string does not register in the graph.
+
+Entry shape:
+
+```markdown
+## YYYY-MM-DD: <short title>
+
+- <what was done>
+- Files touched: [doc-a](./path/doc-a.md), [doc-b](./path/doc-b.md)
+- Sources ingested: [source-slug](./external-sources/source-slug.md)
+- Open follow-ups: <topic-1>, <topic-2>
+```
+
+## Templates
+
+Each folder has a starter template (`clip`, `research-log`, `article`). Create with `write_document({ template: "<name>", docName, … })`. Templates carry only structure (headings + frontmatter scaffold) — the meaning of each field and section is described above, not repeated inside the document body.

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

@@ -0,0 +1,27 @@
+---
+name: open-knowledge-pack-plain-notes
+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 Open Knowledge MCP server. Installed project-local by `ok seed --pack plain-notes`."
+metadata:
+  pack: "plain-notes"
+  author: "Inkeep"
+  repository: "https://github.com/inkeep/open-knowledge"
+---
+# Plain Notes pack — how to work here
+
+The lightest pack: no posture imposed, just write and link.
+
+## Folders
+
+- **`notes/`** — one file per topic, flat. Promote a note into a more structured layout later if you outgrow this.
+- **`daily/`** — one journal entry per day (`YYYY-MM-DD.md`): morning intentions, capture through the day, evening reflection.
+
+## Agent behaviors
+
+- **Link liberally.** The value of this pack is the graph that emerges from links — when a note or entry mentions something worth its own page, link it (stub the page if it doesn't exist yet). OK's link graph builds itself from those edges.
+- **Daily entries:** on the first entry of a day, link to yesterday's entry (`YYYY-MM-DD-1.md`) and pre-fill the date, so the linear journal is also a navigable graph.
+- The `mood`, `top3`, and `gratitude` frontmatter fields on daily entries let you look back across days; fill them when journaling.
+
+## Templates
+
+`note` and `daily` carry only structure; write freely.

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

@@ -0,0 +1,43 @@
+---
+name: open-knowledge-pack-software-lifecycle
+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 Open Knowledge MCP server. Installed project-local by `ok seed --pack software-lifecycle`."
+metadata:
+  pack: "software-lifecycle"
+  author: "Inkeep"
+  repository: "https://github.com/inkeep/open-knowledge"
+---
+# Software Lifecycle pack — how to work here
+
+This project holds the doc lifecycle for an engineering team or OSS project. The flow is **proposals → decisions → specs → postmortems**, with **guides** as the how-to bucket. This skill holds the workflow so templates and folder descriptions stay clean.
+
+> This is pack guidance. The platform `open-knowledge` skill still governs every markdown operation.
+
+## The flow
+
+```
+proposals/    in-flight RFC-shape design proposals
+   ↓ accepted
+decisions/    frozen ADRs (the record of what was decided)
+   ↓ derived
+specs/        implementation specs for accepted proposals
+   ↓ when things break
+postmortems/  blameless incident write-ups
+guides/       how-to / onboarding / runbooks (referenced throughout)
+```
+
+## Per-folder rules + agent behaviors
+
+**`proposals/`** — One file per proposal (`0001-feature-name.md`). Status flows `draft → fcp → accepted/rejected`. An accepted proposal graduates to a record in `decisions/`. Shape: Motivation / Design / Drawbacks / Alternatives / Unresolved questions. *Agent: when a proposal sits at `status: draft` more than 14 days, surface it for the author to advance, park, or close.*
+
+**`decisions/`** — Architecture Decision Records (MADR / Nygard shape). Frozen once accepted. One file per decision (`NNNN-title.md`); status `proposed/accepted/deprecated/superseded`. A new decision that supersedes an older one links back via `Supersedes:`. *Agent: on a new decision, scan existing records touching the same subsystem and surface `Supersedes:` candidates before commit.*
+
+**`specs/`** — Implementation specs derived from accepted proposals. Prefer the `github/spec-kit` shape: one folder per spec (`specs/NNN-name/`) with `spec.md` + `plan.md` + `tasks.md` (the pack ships all three templates). References the parent proposal. *Agent: when a spec moves to `status: shipped`, suggest a postmortem template if the owner reports an incident in the spec's subsystem.*
+
+**`postmortems/`** — Blameless incident write-ups, one file per incident (`YYYY-MM-DD-name.md`): Summary / Timeline / Root cause / What went well / Action items (Google SRE shape). *Agent: surface a `Related:` block linking prior postmortems that share subsystems.*
+
+**`guides/`** — How-to guides, onboarding docs, and service-bound runbooks (Diátaxis how-to). Ships `guide`, `onboarding-guide`, and `runbook` templates. Carries `last_verified` so stale guides surface in periodic reviews. *Agent: when a postmortem is published, scan its action items for guide-shaped follow-ups and stub a guide pre-filled with the symptom and timeline excerpt.*
+
+## Templates
+
+Create docs with `write_document({ template: "<name>", … })`. Templates carry only structure (headings + frontmatter scaffold); what each section is for is described above, not repeated in the document body.

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

@@ -0,0 +1,33 @@
+---
+name: open-knowledge-pack-worldbuilding
+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 Open Knowledge MCP server. Installed project-local by `ok seed --pack worldbuilding`."
+metadata:
+  pack: "worldbuilding"
+  author: "Inkeep"
+  repository: "https://github.com/inkeep/open-knowledge"
+---
+# Worldbuilding pack — how to work here
+
+This project is a fiction encyclopedia. The graph is the product: characters, settings, themes, factions, and lore that link to each other. The agent's main jobs are auto-stubbing new entities as they're mentioned and flagging contradictions. This skill holds those behaviors so templates and folder descriptions stay clean.
+
+> Pack guidance. The platform `open-knowledge` skill still governs every markdown operation.
+
+## Folders
+
+- **`characters/`** — one file per character (PC + NPC); frontmatter carries type, status, faction, first appearance.
+- **`settings/`** — locations, regions, world-rules; frontmatter carries region, controlling faction, danger level. The "where" of the story.
+- **`themes/`** — recurring narrative concerns (love, betrayal, identity). The "why." Themes work via opposition; each entry captures the theme and its tension.
+- **`factions/`** — political, social, criminal, magical, religious groups. Ships `faction`, `political-faction`, and `religion` templates.
+- **`lore/`** — history, mythology, cosmology, magic systems. Ships `lore`, `magic-system`, and `historical-event` templates.
+
+## Agent behaviors (the core value)
+
+- **Auto-stub on mention.** When a chapter, session log, or existing entry references a name not yet captured, stub a file in the right folder with backlinks to where it was mentioned.
+- **Flag contradictions.** When a character's `faction` (or any field) contradicts their actions in narrative, or a setting is described two ways, surface the conflict — in fiction a contradiction is itself a story-shaping detail worth noting, not silently "fixing."
+- **Thread the graph.** Link characters ↔ factions ↔ settings ↔ lore so each entry becomes a hub for everywhere it appears.
+- Do NOT add TTRPG stat-block fields (`xp_awarded`, etc.) — those belong in a future TTRPG variant.
+
+## Templates
+
+Create with `write_document({ template: "<name>", … })`. Templates carry only structure; section meaning is described here, not inside the document body.

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

@@ -0,0 +1,30 @@
+---
+name: open-knowledge-pack-writing-pipeline
+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 Open Knowledge MCP server. Installed project-local by `ok seed --pack writing-pipeline`."
+metadata:
+  pack: "writing-pipeline"
+  author: "Inkeep"
+  repository: "https://github.com/inkeep/open-knowledge"
+---
+# Writing Pipeline pack — how to work here
+
+A lean three-stage flow for short-to-medium-form writing (essays, newsletters, blog posts):
+
+```
+ideas/      one-line premises, captured before they fade
+   ↓ commit to writing it
+drafts/     active prose; CRDT history covers revisions (no named-revision folders)
+   ↓ ship
+published/  shipped work; treat as immutable
+```
+
+## Per-folder rules + agent behaviors
+
+- **`ideas/`** — premises, headlines, fragments. Kept short on purpose; not a draft folder. Promote into `drafts/` when you commit to the piece. *Agent: review ideas idle more than 30 days and surface them to park or promote.*
+- **`drafts/`** — active prose. Frontmatter tracks `status: drafting/review`, word count, parent idea. *Agent: review drafts idle more than 14 days; for drafts in review, suggest publication targets based on `target_form`. If a piece needs research notes, create `drafts/<slug>/research/` on demand rather than a top-level folder.*
+- **`published/`** — shipped work; carries `published_at`, `canonical_url`, `channel`. Treat as immutable; to revise, copy to a new draft. *Agent: on publish, auto-fill `canonical_url` when a Substack / Ghost / Mirror URL is pasted into the file.*
+
+## Templates
+
+Create with `write_document({ template: "<name>", … })`. Templates carry only structure; section meaning lives here, not in the document body.

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.1-beta.2"
+  version: "0.9.2-beta.10"
   author: "Inkeep"
   repository: "https://github.com/inkeep/open-knowledge"
 ---
@@ -28,7 +28,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).
+- **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 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** — `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).
@@ -102,6 +102,8 @@ Call `write_document` / `edit_document` as soon as you have content. Native `Edi
 
 **Pass a `summary` on every content write (SHOULD).** `write_document`, `edit_document`, and `edit_frontmatter` each take a one-line `summary` (≤80 chars) describing the user-facing outcome of the change — "Add gear list and permit info", not "edited trip doc". It renders as a bullet under your name in the document timeline and is the only human-readable change-note persisted to the shadow-repo history; omit it and the timeline shows *that* you wrote but not *what changed*. Write it from the reader's perspective, keep it specific, and avoid secrets or PII (it lands in git history). Each entry in the batch `docs:` form carries its own `summary`.
 
+**Content-divergence warning (Site A gate).** `write_document` and `edit_document` responses may include a content-divergence warning when the converged Y.Text doesn't match the bytes the payload composed to (concurrent peer left residue, or — rare — a primitive regression). The write still landed; on this signal, re-read the doc (`exec("cat <path>")`) to see what actually converged before continuing. Single-doc shape: `structuredContent.contentDivergence = { kind: "content-divergence", intendedBytes, actualBytes, byteDelta, hint }`. Batch shape: per-doc `structuredContent.documents[].contentDivergence` with the same fields. Distinct from the preview-attach `warning` field (`action: "attach-preview-once" | "start-ui"`) — separate keys, can coexist.
+
 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.