writeDocument
Create or replace a markdown document at a vault path, keeping full version history and turning [[wikilinks]] into graph edges. Add optional frontmatter and scope to control metadata and visibility.
Instructions
Create or replace a markdown document at path with body (stored verbatim, event-sourced — full history is kept). [[Wikilinks]] in the body resolve to canonical entities and other documents as graph edges; dangling links reconcile automatically when their target appears. Optional title/pinned/tags/frontmatter synthesize a YAML frontmatter block when the body has none. Frontmatter about: <name|entities/{uid}> records the document's primary subject as a high-confidence describes edge (distinct from body [[wikilinks]], which are mentions); resolve it by uid where you can, since a renamed subject keeps the link. Frontmatter canonical: true lets this document win name resolution over a same-named non-document entity, so a later-created entity cannot silently steal the name. The document materializes as an editable file in the vault. Idempotent: rewriting identical content is a no-op. scope picks who sees the document (personal by default; team requires membership, else E_PERMISSION) and is fixed at creation — the same path in a different scope is a separate document. Result counts (edges, unresolved, reconciled) are whole-document snapshots after the write, not deltas. A non-fatal warnings field appears when the title shadows a same-named non-document entity.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | The full markdown body, stored verbatim. May include its own YAML frontmatter block. | |
| path | Yes | Vault-relative path, e.g. notes/project-alpha.md (.md appended when no extension). | |
| tags | No | Tags, synthesized into frontmatter. | |
| scope | No | Storage scope, fixed at creation. personal (default) = only you; project = a shared project; team = every team member (requires membership, else E_PERMISSION); draft = private staging. The same path in a different scope is a SEPARATE document. | |
| title | No | Optional title, synthesized into frontmatter. Only when body has no frontmatter of its own. | |
| pinned | No | Pin the document (synthesized into frontmatter). Pinned documents surface first in context packs. | |
| frontmatter | No | Additional frontmatter keys (JSON object), synthesized into a YAML block. Only when body has no frontmatter of its own. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | Absolute path of the materialized vault file. | |
| name | Yes | entities/{uid} resource name of the document-as-entity. | |
| path | Yes | ||
| edges | No | Total resolved wikilink and frontmatter edges the whole document holds after this write (snapshot, not a delta — counts all [[links]] in the current body that resolved, regardless of how many were already in the graph). | |
| changed | Yes | False when the content matched the latest revision (no-op). | |
| warnings | No | Non-fatal advisory messages — e.g. a title-collision warning when the document's display name shadows a non-document entity. Does not affect the written content; the document body is stored byte-for-byte as supplied. Omitted when empty. | |
| reconciled | No | Count of wikilinks in OTHER vault documents that this write newly made resolvable (cross-document reconcile pass; separate from the document's own edge snapshot above). | |
| unresolved | No | Count of [[wikilinks]] left dangling in the whole document after this write (snapshot, not a delta). | |
| documentUid | Yes | ||
| pendingEdit | No | True when the vault file holds an un-ingested manual edit and was left untouched. | |
| revisionUid | No | ||
| unresolvedTargets | No | The dangling wikilink targets by name (text inside [[…]] that matched nothing) — fix a typo or create the target. Omitted when none dangle. |