RDF/XML serialization is deferred.
{
"@context": {
"schema": "https://schema.org/",
"wiki": "https://wazootech.github.io/wiki/",
"foaf": "http://xmlns.com/foaf/0.1/",
"rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
"rdfs": "http://www.w3.org/2000/01/rdf-schema#",
"xsd": "http://www.w3.org/2001/XMLSchema#",
"owl": "http://www.w3.org/2002/07/owl#",
"dc": "http://purl.org/dc/elements/1.1/",
"dcterms": "http://purl.org/dc/terms/",
"sh": "http://www.w3.org/ns/shacl#",
"wazoo": "https://schema.wazoo.dev/"
},
"@id": "wiki:wiki_edit",
"@type": "schema:TechArticle",
"schema:articleBody": "# `wiki edit`\n\nApply a batch of page changes as one edit: validate it against the wiki's shapes, routes, and links before anything is written, then write every file or none. `wiki edit` takes the edit as JSON; [wiki file new](wiki_file_new.md), [wiki file set](wiki_file_set.md), [wiki file patch](wiki_file_patch.md), [wiki file mv](wiki_file_mv.md), and [wiki file rm](wiki_file_rm.md) build a one-op edit for you and share its flags, report, and exit codes. [wiki file show](wiki_file_show.md) and [wiki file refs](wiki_file_refs.md) are the read side.\n\n## Why\n\nWithout it, an agent changes a wiki the way a person does in an editor: read whole files, hand-assemble YAML frontmatter, write body text, fix links by hand, then run `wiki check` and `wiki lint` and iterate on the diff. The engine already knows every invariant that loop re-derives (shapes, routes, the link graph), so `wiki edit` checks them at write time instead of after the fact ([wiki#353](https://github.com/wazootech/wiki/issues/353)).\n\nThese are guarded semantic writes, not an editor: there are no app-control verbs, and the CLI never commits. Git history stays with the caller's worktree.\n\n## Usage\n\n```bash\nwiki edit --from plan.json # validate and report; writes nothing\nwiki edit --from plan.json --apply # validate, then write atomically\ncat plan.json | wiki edit --json # read the edit from stdin\n```\n\n## The edit format\n\nAn edit is `{\"ops\": [...]}`. Paths are relative to the config root (or absolute), never to the working directory, so a plan can be handed between agents unchanged.\n\n| Op | Fields | What it does |\n| --------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `create` | `path`, `content` or `type`/`frontmatter`/`body`, `expect` | Create a page from full `content`, or scaffold it from a class `type` (such as `schema:Purchase`): the type's required fields first, then the rest of `frontmatter`, then an H1 and `body`. |\n| `replace` | `path`, `content`, `expect` | Replace a file's whole content. |\n| `set` | `path`, `field`, `value` or `yaml`, `expect` | Set one top-level frontmatter field; `value: null` removes it. `yaml` passes the value as YAML source, kept verbatim (`\"12.00\"` stays `12.00`, where the JSON number `12.00` becomes `12`). See [wiki file set](wiki_file_set.md). |\n| `patch` | `path`, `target`, `mode`, `content`, `expect` | `target` is `{\"heading\": \"Change log\"}`, `{\"frontmatter\": true}`, or `{\"body\": true}`; `mode` is `append`, `prepend`, or `replace`. See [wiki file patch](wiki_file_patch.md). |\n| `move` | `from`, `to`, `expect` | Move a page and repoint every link and metadata reference to it. `expect` applies to `from`; `to` must not exist. See [wiki file mv](wiki_file_mv.md). |\n| `delete` | `path`, `pruneLinks`, `expect` | Delete a page. Refused while other pages link to it, unless `pruneLinks` turns those links into plain text. See [wiki file rm](wiki_file_rm.md). |\n\n`expect` is the SHA-256 of the file's raw bytes, as [wiki file show](wiki_file_show.md) reports it, or `\"absent\"` for a create. It is checked against the file on disk before the edit, even when an earlier op in the same edit touched that file.\n\n## The `expect` loop\n\n1. `wiki file show PATH --json` and keep its `hash`.\n2. Build the edit with `\"expect\": \"<hash>\"` on each op and dry-run it.\n3. Apply it with `--apply`. Each file in the report carries its new `after` hash, which is the `expect` for the next edit.\n\nIf another agent changed the file in between, the edit exits `3` and writes nothing. Re-read the page with `wiki file show`, rebuild the edit against what is there now, and retry. Never `--force` past a conflict: `--force` overrides validation errors, not stale reads.\n\n## Validation\n\nThe edit is staged in memory and the ordinary `check` and `lint` passes run twice over the same scope, once on the wiki as it is and once on the wiki as it would be. Only findings the edit **introduces** reject it, so a wiki that is already broken elsewhere does not block an unrelated change. A move re-anchors the moved page's existing findings, so they are not blamed on the move.\n\nValidation is scoped, not whole-wiki: it covers the pages the edit touches and the pages that link to deleted or moved ones. A page whose SHACL result depends on a touched page without linking to it (for example an `sh:class` constraint on an IRI that page defines) is not re-validated, so an accepted edit can still break it. `wiki check` over the whole wiki remains the full gate; keep it in CI.\n\n## Writing\n\nNothing is written without `--apply`. With it, every new file content goes to a sibling temp file first, then each is renamed over its target, and deletes go last. If any step fails, every file already written is restored to its exact original bytes, new files and directories are removed, and the error is reported. Just before writing, each file is compared with what was read once more, so a change that landed during validation is still a conflict.\n\nRollback happens inside the running process. If the process is killed partway through writing a multi-file edit (a hard crash, power loss, `kill -9`), files already renamed into place stay written and the rest do not; rerun `wiki edit` (or check the files) after an interruption.\n\nWrites land only on wiki documents under `wiki.input`. Installed sources and the `.wiki/` cache are read-only, and so are symlinks and excluded paths.\n\n## Options\n\n| Flag | Default | Description |\n| ---------------- | ------- | ------------------------------------------------------------------- |\n| `--from FILE` | `-` | Read the edit from `FILE`, or `-` for stdin. |\n| `--apply` | off | Write the edit. Without it, validate and report only. |\n| `--force` | off | Write even if the edit introduces errors (they are still reported). |\n| `-f`, `--format` | `text` | `text` or `json` (the edit report on stdout). |\n| `--json` | — | Shorthand for `--format json`. |\n\n## Exit codes\n\n| Code | Meaning |\n| ---- | -------------------------------------------------------------------------------- |\n| `0` | The edit is valid (dry run), or written (`--apply`). |\n| `1` | Rejected: the edit introduces check or lint errors, or would leave links broken. |\n| `2` | Usage error: malformed JSON, an unknown op, or a path outside `wiki.input`. |\n| `3` | Conflict: an `expect` hash no longer matches the file. Nothing was written. |\n\n## Report\n\n`--json` writes one object (`version` 1):\n\n| Field | Description |\n| ------------ | ----------------------------------------------------------------------------------------------------------------- |\n| `status` | `dry_run`, `applied`, `rejected`, or `conflict`. |\n| `ok` | `true` for `dry_run` and `applied`. |\n| `files` | Per file: `path`, `action` (`create`, `modify`, `delete`), and `before`/`after` hashes (`null` when absent). |\n| `conflicts` | Per stale `expect`: `path`, `expected`, and `actual` (`null` when the file does not exist). |\n| `introduced` | Findings present after the edit and absent before it, in the [wiki check](wiki_check.md#json-output) issue shape. |\n| `check` | The scoped `check -f json` report of the edited pages, or `null` on a conflict. |\n\n## Example\n\nRecord a new spend in a budget ledger and note it in the ledger's change log, as one edit:\n\n```json\n{\n \"ops\": [\n {\n \"op\": \"create\",\n \"path\": \"wiki/Neon_(payment).md\",\n \"expect\": \"absent\",\n \"type\": \"schema:Purchase\",\n \"frontmatter\": {\n \"schema:name\": \"Neon plan\",\n \"schema:orderDate\": \"2026-10-10\",\n \"schema:priceCurrency\": \"USD\",\n \"schema:seller\": \"https://memory.wazoo.dev/Neon\",\n \"schema:customer\": \"https://memory.wazoo.dev/Ethan_Davidson\"\n },\n \"body\": \"Monthly Neon plan for the hosted world.\"\n },\n {\n \"op\": \"set\",\n \"path\": \"wiki/Neon_(payment).md\",\n \"field\": \"schema:price\",\n \"yaml\": \"19.00\"\n },\n {\n \"op\": \"patch\",\n \"path\": \"wiki/Budget_Ledger.md\",\n \"expect\": \"9d97…\",\n \"target\": { \"heading\": \"Change log\" },\n \"mode\": \"append\",\n \"content\": \"- 2026-10-10 — Added the Neon plan.\"\n }\n ]\n}\n```\n\nA dry run reports `status: \"dry_run\"` and the three files' `after` hashes, or `status: \"rejected\"` naming any required field the shape still misses. Adding `--apply` writes all of it or none of it.\n\n## See also\n\n- [wiki file show](wiki_file_show.md) and [wiki file refs](wiki_file_refs.md) — read a page and its links before editing\n- [wiki check](wiki_check.md) — the whole-wiki gate\n- [Wiki Programmatic API](Wiki_Programmatic_API.md) — `Wiki.edit()` in process",
"schema:dateCreated": {
"@type": "xsd:dateTime",
"@value": "2026-10-31T23:19:03Z"
},
"schema:dateModified": {
"@type": "xsd:dateTime",
"@value": "2026-10-31T23:19:03Z"
},
"schema:description": "Change a wiki through validated, atomic edits instead of hand-written Markdown.",
"schema:headline": "wiki edit"
}
@prefix schema: <https://schema.org/>.
@prefix wiki: <https://wazootech.github.io/wiki/>.
@prefix foaf: <http://xmlns.com/foaf/0.1/>.
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
@prefix owl: <http://www.w3.org/2002/07/owl#>.
@prefix dc: <http://purl.org/dc/elements/1.1/>.
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix sh: <http://www.w3.org/ns/shacl#>.
@prefix wazoo: <https://schema.wazoo.dev/>.
wiki:wiki_edit a schema:TechArticle;
schema:description "Change a wiki through validated, atomic edits instead of hand-written Markdown.";
schema:articleBody "# `wiki edit`\n\nApply a batch of page changes as one edit: validate it against the wiki's shapes, routes, and links before anything is written, then write every file or none. `wiki edit` takes the edit as JSON; [wiki file new](wiki_file_new.md), [wiki file set](wiki_file_set.md), [wiki file patch](wiki_file_patch.md), [wiki file mv](wiki_file_mv.md), and [wiki file rm](wiki_file_rm.md) build a one-op edit for you and share its flags, report, and exit codes. [wiki file show](wiki_file_show.md) and [wiki file refs](wiki_file_refs.md) are the read side.\n\n## Why\n\nWithout it, an agent changes a wiki the way a person does in an editor: read whole files, hand-assemble YAML frontmatter, write body text, fix links by hand, then run `wiki check` and `wiki lint` and iterate on the diff. The engine already knows every invariant that loop re-derives (shapes, routes, the link graph), so `wiki edit` checks them at write time instead of after the fact ([wiki#353](https://github.com/wazootech/wiki/issues/353)).\n\nThese are guarded semantic writes, not an editor: there are no app-control verbs, and the CLI never commits. Git history stays with the caller's worktree.\n\n## Usage\n\n```bash\nwiki edit --from plan.json # validate and report; writes nothing\nwiki edit --from plan.json --apply # validate, then write atomically\ncat plan.json | wiki edit --json # read the edit from stdin\n```\n\n## The edit format\n\nAn edit is `{\"ops\": [...]}`. Paths are relative to the config root (or absolute), never to the working directory, so a plan can be handed between agents unchanged.\n\n| Op | Fields | What it does |\n| --------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `create` | `path`, `content` or `type`/`frontmatter`/`body`, `expect` | Create a page from full `content`, or scaffold it from a class `type` (such as `schema:Purchase`): the type's required fields first, then the rest of `frontmatter`, then an H1 and `body`. |\n| `replace` | `path`, `content`, `expect` | Replace a file's whole content. |\n| `set` | `path`, `field`, `value` or `yaml`, `expect` | Set one top-level frontmatter field; `value: null` removes it. `yaml` passes the value as YAML source, kept verbatim (`\"12.00\"` stays `12.00`, where the JSON number `12.00` becomes `12`). See [wiki file set](wiki_file_set.md). |\n| `patch` | `path`, `target`, `mode`, `content`, `expect` | `target` is `{\"heading\": \"Change log\"}`, `{\"frontmatter\": true}`, or `{\"body\": true}`; `mode` is `append`, `prepend`, or `replace`. See [wiki file patch](wiki_file_patch.md). |\n| `move` | `from`, `to`, `expect` | Move a page and repoint every link and metadata reference to it. `expect` applies to `from`; `to` must not exist. See [wiki file mv](wiki_file_mv.md). |\n| `delete` | `path`, `pruneLinks`, `expect` | Delete a page. Refused while other pages link to it, unless `pruneLinks` turns those links into plain text. See [wiki file rm](wiki_file_rm.md). |\n\n`expect` is the SHA-256 of the file's raw bytes, as [wiki file show](wiki_file_show.md) reports it, or `\"absent\"` for a create. It is checked against the file on disk before the edit, even when an earlier op in the same edit touched that file.\n\n## The `expect` loop\n\n1. `wiki file show PATH --json` and keep its `hash`.\n2. Build the edit with `\"expect\": \"<hash>\"` on each op and dry-run it.\n3. Apply it with `--apply`. Each file in the report carries its new `after` hash, which is the `expect` for the next edit.\n\nIf another agent changed the file in between, the edit exits `3` and writes nothing. Re-read the page with `wiki file show`, rebuild the edit against what is there now, and retry. Never `--force` past a conflict: `--force` overrides validation errors, not stale reads.\n\n## Validation\n\nThe edit is staged in memory and the ordinary `check` and `lint` passes run twice over the same scope, once on the wiki as it is and once on the wiki as it would be. Only findings the edit **introduces** reject it, so a wiki that is already broken elsewhere does not block an unrelated change. A move re-anchors the moved page's existing findings, so they are not blamed on the move.\n\nValidation is scoped, not whole-wiki: it covers the pages the edit touches and the pages that link to deleted or moved ones. A page whose SHACL result depends on a touched page without linking to it (for example an `sh:class` constraint on an IRI that page defines) is not re-validated, so an accepted edit can still break it. `wiki check` over the whole wiki remains the full gate; keep it in CI.\n\n## Writing\n\nNothing is written without `--apply`. With it, every new file content goes to a sibling temp file first, then each is renamed over its target, and deletes go last. If any step fails, every file already written is restored to its exact original bytes, new files and directories are removed, and the error is reported. Just before writing, each file is compared with what was read once more, so a change that landed during validation is still a conflict.\n\nRollback happens inside the running process. If the process is killed partway through writing a multi-file edit (a hard crash, power loss, `kill -9`), files already renamed into place stay written and the rest do not; rerun `wiki edit` (or check the files) after an interruption.\n\nWrites land only on wiki documents under `wiki.input`. Installed sources and the `.wiki/` cache are read-only, and so are symlinks and excluded paths.\n\n## Options\n\n| Flag | Default | Description |\n| ---------------- | ------- | ------------------------------------------------------------------- |\n| `--from FILE` | `-` | Read the edit from `FILE`, or `-` for stdin. |\n| `--apply` | off | Write the edit. Without it, validate and report only. |\n| `--force` | off | Write even if the edit introduces errors (they are still reported). |\n| `-f`, `--format` | `text` | `text` or `json` (the edit report on stdout). |\n| `--json` | — | Shorthand for `--format json`. |\n\n## Exit codes\n\n| Code | Meaning |\n| ---- | -------------------------------------------------------------------------------- |\n| `0` | The edit is valid (dry run), or written (`--apply`). |\n| `1` | Rejected: the edit introduces check or lint errors, or would leave links broken. |\n| `2` | Usage error: malformed JSON, an unknown op, or a path outside `wiki.input`. |\n| `3` | Conflict: an `expect` hash no longer matches the file. Nothing was written. |\n\n## Report\n\n`--json` writes one object (`version` 1):\n\n| Field | Description |\n| ------------ | ----------------------------------------------------------------------------------------------------------------- |\n| `status` | `dry_run`, `applied`, `rejected`, or `conflict`. |\n| `ok` | `true` for `dry_run` and `applied`. |\n| `files` | Per file: `path`, `action` (`create`, `modify`, `delete`), and `before`/`after` hashes (`null` when absent). |\n| `conflicts` | Per stale `expect`: `path`, `expected`, and `actual` (`null` when the file does not exist). |\n| `introduced` | Findings present after the edit and absent before it, in the [wiki check](wiki_check.md#json-output) issue shape. |\n| `check` | The scoped `check -f json` report of the edited pages, or `null` on a conflict. |\n\n## Example\n\nRecord a new spend in a budget ledger and note it in the ledger's change log, as one edit:\n\n```json\n{\n \"ops\": [\n {\n \"op\": \"create\",\n \"path\": \"wiki/Neon_(payment).md\",\n \"expect\": \"absent\",\n \"type\": \"schema:Purchase\",\n \"frontmatter\": {\n \"schema:name\": \"Neon plan\",\n \"schema:orderDate\": \"2026-10-10\",\n \"schema:priceCurrency\": \"USD\",\n \"schema:seller\": \"https://memory.wazoo.dev/Neon\",\n \"schema:customer\": \"https://memory.wazoo.dev/Ethan_Davidson\"\n },\n \"body\": \"Monthly Neon plan for the hosted world.\"\n },\n {\n \"op\": \"set\",\n \"path\": \"wiki/Neon_(payment).md\",\n \"field\": \"schema:price\",\n \"yaml\": \"19.00\"\n },\n {\n \"op\": \"patch\",\n \"path\": \"wiki/Budget_Ledger.md\",\n \"expect\": \"9d97…\",\n \"target\": { \"heading\": \"Change log\" },\n \"mode\": \"append\",\n \"content\": \"- 2026-10-10 — Added the Neon plan.\"\n }\n ]\n}\n```\n\nA dry run reports `status: \"dry_run\"` and the three files' `after` hashes, or `status: \"rejected\"` naming any required field the shape still misses. Adding `--apply` writes all of it or none of it.\n\n## See also\n\n- [wiki file show](wiki_file_show.md) and [wiki file refs](wiki_file_refs.md) — read a page and its links before editing\n- [wiki check](wiki_check.md) — the whole-wiki gate\n- [Wiki Programmatic API](Wiki_Programmatic_API.md) — `Wiki.edit()` in process";
schema:headline "wiki edit";
schema:dateCreated "2026-10-31T23:19:03Z"^^xsd:dateTime;
schema:dateModified "2026-10-31T23:19:03Z"^^xsd:dateTime.
@prefix schema: <https://schema.org/>.
@prefix wiki: <https://wazootech.github.io/wiki/>.
@prefix foaf: <http://xmlns.com/foaf/0.1/>.
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
@prefix owl: <http://www.w3.org/2002/07/owl#>.
@prefix dc: <http://purl.org/dc/elements/1.1/>.
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix sh: <http://www.w3.org/ns/shacl#>.
@prefix wazoo: <https://schema.wazoo.dev/>.
wiki:wiki_edit a schema:TechArticle;
schema:description "Change a wiki through validated, atomic edits instead of hand-written Markdown.";
schema:articleBody "# `wiki edit`\n\nApply a batch of page changes as one edit: validate it against the wiki's shapes, routes, and links before anything is written, then write every file or none. `wiki edit` takes the edit as JSON; [wiki file new](wiki_file_new.md), [wiki file set](wiki_file_set.md), [wiki file patch](wiki_file_patch.md), [wiki file mv](wiki_file_mv.md), and [wiki file rm](wiki_file_rm.md) build a one-op edit for you and share its flags, report, and exit codes. [wiki file show](wiki_file_show.md) and [wiki file refs](wiki_file_refs.md) are the read side.\n\n## Why\n\nWithout it, an agent changes a wiki the way a person does in an editor: read whole files, hand-assemble YAML frontmatter, write body text, fix links by hand, then run `wiki check` and `wiki lint` and iterate on the diff. The engine already knows every invariant that loop re-derives (shapes, routes, the link graph), so `wiki edit` checks them at write time instead of after the fact ([wiki#353](https://github.com/wazootech/wiki/issues/353)).\n\nThese are guarded semantic writes, not an editor: there are no app-control verbs, and the CLI never commits. Git history stays with the caller's worktree.\n\n## Usage\n\n```bash\nwiki edit --from plan.json # validate and report; writes nothing\nwiki edit --from plan.json --apply # validate, then write atomically\ncat plan.json | wiki edit --json # read the edit from stdin\n```\n\n## The edit format\n\nAn edit is `{\"ops\": [...]}`. Paths are relative to the config root (or absolute), never to the working directory, so a plan can be handed between agents unchanged.\n\n| Op | Fields | What it does |\n| --------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `create` | `path`, `content` or `type`/`frontmatter`/`body`, `expect` | Create a page from full `content`, or scaffold it from a class `type` (such as `schema:Purchase`): the type's required fields first, then the rest of `frontmatter`, then an H1 and `body`. |\n| `replace` | `path`, `content`, `expect` | Replace a file's whole content. |\n| `set` | `path`, `field`, `value` or `yaml`, `expect` | Set one top-level frontmatter field; `value: null` removes it. `yaml` passes the value as YAML source, kept verbatim (`\"12.00\"` stays `12.00`, where the JSON number `12.00` becomes `12`). See [wiki file set](wiki_file_set.md). |\n| `patch` | `path`, `target`, `mode`, `content`, `expect` | `target` is `{\"heading\": \"Change log\"}`, `{\"frontmatter\": true}`, or `{\"body\": true}`; `mode` is `append`, `prepend`, or `replace`. See [wiki file patch](wiki_file_patch.md). |\n| `move` | `from`, `to`, `expect` | Move a page and repoint every link and metadata reference to it. `expect` applies to `from`; `to` must not exist. See [wiki file mv](wiki_file_mv.md). |\n| `delete` | `path`, `pruneLinks`, `expect` | Delete a page. Refused while other pages link to it, unless `pruneLinks` turns those links into plain text. See [wiki file rm](wiki_file_rm.md). |\n\n`expect` is the SHA-256 of the file's raw bytes, as [wiki file show](wiki_file_show.md) reports it, or `\"absent\"` for a create. It is checked against the file on disk before the edit, even when an earlier op in the same edit touched that file.\n\n## The `expect` loop\n\n1. `wiki file show PATH --json` and keep its `hash`.\n2. Build the edit with `\"expect\": \"<hash>\"` on each op and dry-run it.\n3. Apply it with `--apply`. Each file in the report carries its new `after` hash, which is the `expect` for the next edit.\n\nIf another agent changed the file in between, the edit exits `3` and writes nothing. Re-read the page with `wiki file show`, rebuild the edit against what is there now, and retry. Never `--force` past a conflict: `--force` overrides validation errors, not stale reads.\n\n## Validation\n\nThe edit is staged in memory and the ordinary `check` and `lint` passes run twice over the same scope, once on the wiki as it is and once on the wiki as it would be. Only findings the edit **introduces** reject it, so a wiki that is already broken elsewhere does not block an unrelated change. A move re-anchors the moved page's existing findings, so they are not blamed on the move.\n\nValidation is scoped, not whole-wiki: it covers the pages the edit touches and the pages that link to deleted or moved ones. A page whose SHACL result depends on a touched page without linking to it (for example an `sh:class` constraint on an IRI that page defines) is not re-validated, so an accepted edit can still break it. `wiki check` over the whole wiki remains the full gate; keep it in CI.\n\n## Writing\n\nNothing is written without `--apply`. With it, every new file content goes to a sibling temp file first, then each is renamed over its target, and deletes go last. If any step fails, every file already written is restored to its exact original bytes, new files and directories are removed, and the error is reported. Just before writing, each file is compared with what was read once more, so a change that landed during validation is still a conflict.\n\nRollback happens inside the running process. If the process is killed partway through writing a multi-file edit (a hard crash, power loss, `kill -9`), files already renamed into place stay written and the rest do not; rerun `wiki edit` (or check the files) after an interruption.\n\nWrites land only on wiki documents under `wiki.input`. Installed sources and the `.wiki/` cache are read-only, and so are symlinks and excluded paths.\n\n## Options\n\n| Flag | Default | Description |\n| ---------------- | ------- | ------------------------------------------------------------------- |\n| `--from FILE` | `-` | Read the edit from `FILE`, or `-` for stdin. |\n| `--apply` | off | Write the edit. Without it, validate and report only. |\n| `--force` | off | Write even if the edit introduces errors (they are still reported). |\n| `-f`, `--format` | `text` | `text` or `json` (the edit report on stdout). |\n| `--json` | — | Shorthand for `--format json`. |\n\n## Exit codes\n\n| Code | Meaning |\n| ---- | -------------------------------------------------------------------------------- |\n| `0` | The edit is valid (dry run), or written (`--apply`). |\n| `1` | Rejected: the edit introduces check or lint errors, or would leave links broken. |\n| `2` | Usage error: malformed JSON, an unknown op, or a path outside `wiki.input`. |\n| `3` | Conflict: an `expect` hash no longer matches the file. Nothing was written. |\n\n## Report\n\n`--json` writes one object (`version` 1):\n\n| Field | Description |\n| ------------ | ----------------------------------------------------------------------------------------------------------------- |\n| `status` | `dry_run`, `applied`, `rejected`, or `conflict`. |\n| `ok` | `true` for `dry_run` and `applied`. |\n| `files` | Per file: `path`, `action` (`create`, `modify`, `delete`), and `before`/`after` hashes (`null` when absent). |\n| `conflicts` | Per stale `expect`: `path`, `expected`, and `actual` (`null` when the file does not exist). |\n| `introduced` | Findings present after the edit and absent before it, in the [wiki check](wiki_check.md#json-output) issue shape. |\n| `check` | The scoped `check -f json` report of the edited pages, or `null` on a conflict. |\n\n## Example\n\nRecord a new spend in a budget ledger and note it in the ledger's change log, as one edit:\n\n```json\n{\n \"ops\": [\n {\n \"op\": \"create\",\n \"path\": \"wiki/Neon_(payment).md\",\n \"expect\": \"absent\",\n \"type\": \"schema:Purchase\",\n \"frontmatter\": {\n \"schema:name\": \"Neon plan\",\n \"schema:orderDate\": \"2026-10-10\",\n \"schema:priceCurrency\": \"USD\",\n \"schema:seller\": \"https://memory.wazoo.dev/Neon\",\n \"schema:customer\": \"https://memory.wazoo.dev/Ethan_Davidson\"\n },\n \"body\": \"Monthly Neon plan for the hosted world.\"\n },\n {\n \"op\": \"set\",\n \"path\": \"wiki/Neon_(payment).md\",\n \"field\": \"schema:price\",\n \"yaml\": \"19.00\"\n },\n {\n \"op\": \"patch\",\n \"path\": \"wiki/Budget_Ledger.md\",\n \"expect\": \"9d97…\",\n \"target\": { \"heading\": \"Change log\" },\n \"mode\": \"append\",\n \"content\": \"- 2026-10-10 — Added the Neon plan.\"\n }\n ]\n}\n```\n\nA dry run reports `status: \"dry_run\"` and the three files' `after` hashes, or `status: \"rejected\"` naming any required field the shape still misses. Adding `--apply` writes all of it or none of it.\n\n## See also\n\n- [wiki file show](wiki_file_show.md) and [wiki file refs](wiki_file_refs.md) — read a page and its links before editing\n- [wiki check](wiki_check.md) — the whole-wiki gate\n- [Wiki Programmatic API](Wiki_Programmatic_API.md) — `Wiki.edit()` in process";
schema:headline "wiki edit";
schema:dateCreated "2026-10-31T23:19:03Z"^^xsd:dateTime;
schema:dateModified "2026-10-31T23:19:03Z"^^xsd:dateTime.
<https://wazootech.github.io/wiki/wiki_edit> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://schema.org/TechArticle> .
<https://wazootech.github.io/wiki/wiki_edit> <https://schema.org/description> "Change a wiki through validated, atomic edits instead of hand-written Markdown." .
<https://wazootech.github.io/wiki/wiki_edit> <https://schema.org/articleBody> "# `wiki edit`\n\nApply a batch of page changes as one edit: validate it against the wiki's shapes, routes, and links before anything is written, then write every file or none. `wiki edit` takes the edit as JSON; [wiki file new](wiki_file_new.md), [wiki file set](wiki_file_set.md), [wiki file patch](wiki_file_patch.md), [wiki file mv](wiki_file_mv.md), and [wiki file rm](wiki_file_rm.md) build a one-op edit for you and share its flags, report, and exit codes. [wiki file show](wiki_file_show.md) and [wiki file refs](wiki_file_refs.md) are the read side.\n\n## Why\n\nWithout it, an agent changes a wiki the way a person does in an editor: read whole files, hand-assemble YAML frontmatter, write body text, fix links by hand, then run `wiki check` and `wiki lint` and iterate on the diff. The engine already knows every invariant that loop re-derives (shapes, routes, the link graph), so `wiki edit` checks them at write time instead of after the fact ([wiki#353](https://github.com/wazootech/wiki/issues/353)).\n\nThese are guarded semantic writes, not an editor: there are no app-control verbs, and the CLI never commits. Git history stays with the caller's worktree.\n\n## Usage\n\n```bash\nwiki edit --from plan.json # validate and report; writes nothing\nwiki edit --from plan.json --apply # validate, then write atomically\ncat plan.json | wiki edit --json # read the edit from stdin\n```\n\n## The edit format\n\nAn edit is `{\"ops\": [...]}`. Paths are relative to the config root (or absolute), never to the working directory, so a plan can be handed between agents unchanged.\n\n| Op | Fields | What it does |\n| --------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `create` | `path`, `content` or `type`/`frontmatter`/`body`, `expect` | Create a page from full `content`, or scaffold it from a class `type` (such as `schema:Purchase`): the type's required fields first, then the rest of `frontmatter`, then an H1 and `body`. |\n| `replace` | `path`, `content`, `expect` | Replace a file's whole content. |\n| `set` | `path`, `field`, `value` or `yaml`, `expect` | Set one top-level frontmatter field; `value: null` removes it. `yaml` passes the value as YAML source, kept verbatim (`\"12.00\"` stays `12.00`, where the JSON number `12.00` becomes `12`). See [wiki file set](wiki_file_set.md). |\n| `patch` | `path`, `target`, `mode`, `content`, `expect` | `target` is `{\"heading\": \"Change log\"}`, `{\"frontmatter\": true}`, or `{\"body\": true}`; `mode` is `append`, `prepend`, or `replace`. See [wiki file patch](wiki_file_patch.md). |\n| `move` | `from`, `to`, `expect` | Move a page and repoint every link and metadata reference to it. `expect` applies to `from`; `to` must not exist. See [wiki file mv](wiki_file_mv.md). |\n| `delete` | `path`, `pruneLinks`, `expect` | Delete a page. Refused while other pages link to it, unless `pruneLinks` turns those links into plain text. See [wiki file rm](wiki_file_rm.md). |\n\n`expect` is the SHA-256 of the file's raw bytes, as [wiki file show](wiki_file_show.md) reports it, or `\"absent\"` for a create. It is checked against the file on disk before the edit, even when an earlier op in the same edit touched that file.\n\n## The `expect` loop\n\n1. `wiki file show PATH --json` and keep its `hash`.\n2. Build the edit with `\"expect\": \"<hash>\"` on each op and dry-run it.\n3. Apply it with `--apply`. Each file in the report carries its new `after` hash, which is the `expect` for the next edit.\n\nIf another agent changed the file in between, the edit exits `3` and writes nothing. Re-read the page with `wiki file show`, rebuild the edit against what is there now, and retry. Never `--force` past a conflict: `--force` overrides validation errors, not stale reads.\n\n## Validation\n\nThe edit is staged in memory and the ordinary `check` and `lint` passes run twice over the same scope, once on the wiki as it is and once on the wiki as it would be. Only findings the edit **introduces** reject it, so a wiki that is already broken elsewhere does not block an unrelated change. A move re-anchors the moved page's existing findings, so they are not blamed on the move.\n\nValidation is scoped, not whole-wiki: it covers the pages the edit touches and the pages that link to deleted or moved ones. A page whose SHACL result depends on a touched page without linking to it (for example an `sh:class` constraint on an IRI that page defines) is not re-validated, so an accepted edit can still break it. `wiki check` over the whole wiki remains the full gate; keep it in CI.\n\n## Writing\n\nNothing is written without `--apply`. With it, every new file content goes to a sibling temp file first, then each is renamed over its target, and deletes go last. If any step fails, every file already written is restored to its exact original bytes, new files and directories are removed, and the error is reported. Just before writing, each file is compared with what was read once more, so a change that landed during validation is still a conflict.\n\nRollback happens inside the running process. If the process is killed partway through writing a multi-file edit (a hard crash, power loss, `kill -9`), files already renamed into place stay written and the rest do not; rerun `wiki edit` (or check the files) after an interruption.\n\nWrites land only on wiki documents under `wiki.input`. Installed sources and the `.wiki/` cache are read-only, and so are symlinks and excluded paths.\n\n## Options\n\n| Flag | Default | Description |\n| ---------------- | ------- | ------------------------------------------------------------------- |\n| `--from FILE` | `-` | Read the edit from `FILE`, or `-` for stdin. |\n| `--apply` | off | Write the edit. Without it, validate and report only. |\n| `--force` | off | Write even if the edit introduces errors (they are still reported). |\n| `-f`, `--format` | `text` | `text` or `json` (the edit report on stdout). |\n| `--json` | — | Shorthand for `--format json`. |\n\n## Exit codes\n\n| Code | Meaning |\n| ---- | -------------------------------------------------------------------------------- |\n| `0` | The edit is valid (dry run), or written (`--apply`). |\n| `1` | Rejected: the edit introduces check or lint errors, or would leave links broken. |\n| `2` | Usage error: malformed JSON, an unknown op, or a path outside `wiki.input`. |\n| `3` | Conflict: an `expect` hash no longer matches the file. Nothing was written. |\n\n## Report\n\n`--json` writes one object (`version` 1):\n\n| Field | Description |\n| ------------ | ----------------------------------------------------------------------------------------------------------------- |\n| `status` | `dry_run`, `applied`, `rejected`, or `conflict`. |\n| `ok` | `true` for `dry_run` and `applied`. |\n| `files` | Per file: `path`, `action` (`create`, `modify`, `delete`), and `before`/`after` hashes (`null` when absent). |\n| `conflicts` | Per stale `expect`: `path`, `expected`, and `actual` (`null` when the file does not exist). |\n| `introduced` | Findings present after the edit and absent before it, in the [wiki check](wiki_check.md#json-output) issue shape. |\n| `check` | The scoped `check -f json` report of the edited pages, or `null` on a conflict. |\n\n## Example\n\nRecord a new spend in a budget ledger and note it in the ledger's change log, as one edit:\n\n```json\n{\n \"ops\": [\n {\n \"op\": \"create\",\n \"path\": \"wiki/Neon_(payment).md\",\n \"expect\": \"absent\",\n \"type\": \"schema:Purchase\",\n \"frontmatter\": {\n \"schema:name\": \"Neon plan\",\n \"schema:orderDate\": \"2026-10-10\",\n \"schema:priceCurrency\": \"USD\",\n \"schema:seller\": \"https://memory.wazoo.dev/Neon\",\n \"schema:customer\": \"https://memory.wazoo.dev/Ethan_Davidson\"\n },\n \"body\": \"Monthly Neon plan for the hosted world.\"\n },\n {\n \"op\": \"set\",\n \"path\": \"wiki/Neon_(payment).md\",\n \"field\": \"schema:price\",\n \"yaml\": \"19.00\"\n },\n {\n \"op\": \"patch\",\n \"path\": \"wiki/Budget_Ledger.md\",\n \"expect\": \"9d97…\",\n \"target\": { \"heading\": \"Change log\" },\n \"mode\": \"append\",\n \"content\": \"- 2026-10-10 — Added the Neon plan.\"\n }\n ]\n}\n```\n\nA dry run reports `status: \"dry_run\"` and the three files' `after` hashes, or `status: \"rejected\"` naming any required field the shape still misses. Adding `--apply` writes all of it or none of it.\n\n## See also\n\n- [wiki file show](wiki_file_show.md) and [wiki file refs](wiki_file_refs.md) — read a page and its links before editing\n- [wiki check](wiki_check.md) — the whole-wiki gate\n- [Wiki Programmatic API](Wiki_Programmatic_API.md) — `Wiki.edit()` in process" .
<https://wazootech.github.io/wiki/wiki_edit> <https://schema.org/headline> "wiki edit" .
<https://wazootech.github.io/wiki/wiki_edit> <https://schema.org/dateCreated> "2026-10-31T23:19:03Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
<https://wazootech.github.io/wiki/wiki_edit> <https://schema.org/dateModified> "2026-10-31T23:19:03Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
@prefix schema: <https://schema.org/>.
@prefix wiki: <https://wazootech.github.io/wiki/>.
@prefix foaf: <http://xmlns.com/foaf/0.1/>.
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
@prefix owl: <http://www.w3.org/2002/07/owl#>.
@prefix dc: <http://purl.org/dc/elements/1.1/>.
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix sh: <http://www.w3.org/ns/shacl#>.
@prefix wazoo: <https://schema.wazoo.dev/>.
wiki:wiki_edit a schema:TechArticle;
schema:description "Change a wiki through validated, atomic edits instead of hand-written Markdown.";
schema:articleBody "# `wiki edit`\n\nApply a batch of page changes as one edit: validate it against the wiki's shapes, routes, and links before anything is written, then write every file or none. `wiki edit` takes the edit as JSON; [wiki file new](wiki_file_new.md), [wiki file set](wiki_file_set.md), [wiki file patch](wiki_file_patch.md), [wiki file mv](wiki_file_mv.md), and [wiki file rm](wiki_file_rm.md) build a one-op edit for you and share its flags, report, and exit codes. [wiki file show](wiki_file_show.md) and [wiki file refs](wiki_file_refs.md) are the read side.\n\n## Why\n\nWithout it, an agent changes a wiki the way a person does in an editor: read whole files, hand-assemble YAML frontmatter, write body text, fix links by hand, then run `wiki check` and `wiki lint` and iterate on the diff. The engine already knows every invariant that loop re-derives (shapes, routes, the link graph), so `wiki edit` checks them at write time instead of after the fact ([wiki#353](https://github.com/wazootech/wiki/issues/353)).\n\nThese are guarded semantic writes, not an editor: there are no app-control verbs, and the CLI never commits. Git history stays with the caller's worktree.\n\n## Usage\n\n```bash\nwiki edit --from plan.json # validate and report; writes nothing\nwiki edit --from plan.json --apply # validate, then write atomically\ncat plan.json | wiki edit --json # read the edit from stdin\n```\n\n## The edit format\n\nAn edit is `{\"ops\": [...]}`. Paths are relative to the config root (or absolute), never to the working directory, so a plan can be handed between agents unchanged.\n\n| Op | Fields | What it does |\n| --------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `create` | `path`, `content` or `type`/`frontmatter`/`body`, `expect` | Create a page from full `content`, or scaffold it from a class `type` (such as `schema:Purchase`): the type's required fields first, then the rest of `frontmatter`, then an H1 and `body`. |\n| `replace` | `path`, `content`, `expect` | Replace a file's whole content. |\n| `set` | `path`, `field`, `value` or `yaml`, `expect` | Set one top-level frontmatter field; `value: null` removes it. `yaml` passes the value as YAML source, kept verbatim (`\"12.00\"` stays `12.00`, where the JSON number `12.00` becomes `12`). See [wiki file set](wiki_file_set.md). |\n| `patch` | `path`, `target`, `mode`, `content`, `expect` | `target` is `{\"heading\": \"Change log\"}`, `{\"frontmatter\": true}`, or `{\"body\": true}`; `mode` is `append`, `prepend`, or `replace`. See [wiki file patch](wiki_file_patch.md). |\n| `move` | `from`, `to`, `expect` | Move a page and repoint every link and metadata reference to it. `expect` applies to `from`; `to` must not exist. See [wiki file mv](wiki_file_mv.md). |\n| `delete` | `path`, `pruneLinks`, `expect` | Delete a page. Refused while other pages link to it, unless `pruneLinks` turns those links into plain text. See [wiki file rm](wiki_file_rm.md). |\n\n`expect` is the SHA-256 of the file's raw bytes, as [wiki file show](wiki_file_show.md) reports it, or `\"absent\"` for a create. It is checked against the file on disk before the edit, even when an earlier op in the same edit touched that file.\n\n## The `expect` loop\n\n1. `wiki file show PATH --json` and keep its `hash`.\n2. Build the edit with `\"expect\": \"<hash>\"` on each op and dry-run it.\n3. Apply it with `--apply`. Each file in the report carries its new `after` hash, which is the `expect` for the next edit.\n\nIf another agent changed the file in between, the edit exits `3` and writes nothing. Re-read the page with `wiki file show`, rebuild the edit against what is there now, and retry. Never `--force` past a conflict: `--force` overrides validation errors, not stale reads.\n\n## Validation\n\nThe edit is staged in memory and the ordinary `check` and `lint` passes run twice over the same scope, once on the wiki as it is and once on the wiki as it would be. Only findings the edit **introduces** reject it, so a wiki that is already broken elsewhere does not block an unrelated change. A move re-anchors the moved page's existing findings, so they are not blamed on the move.\n\nValidation is scoped, not whole-wiki: it covers the pages the edit touches and the pages that link to deleted or moved ones. A page whose SHACL result depends on a touched page without linking to it (for example an `sh:class` constraint on an IRI that page defines) is not re-validated, so an accepted edit can still break it. `wiki check` over the whole wiki remains the full gate; keep it in CI.\n\n## Writing\n\nNothing is written without `--apply`. With it, every new file content goes to a sibling temp file first, then each is renamed over its target, and deletes go last. If any step fails, every file already written is restored to its exact original bytes, new files and directories are removed, and the error is reported. Just before writing, each file is compared with what was read once more, so a change that landed during validation is still a conflict.\n\nRollback happens inside the running process. If the process is killed partway through writing a multi-file edit (a hard crash, power loss, `kill -9`), files already renamed into place stay written and the rest do not; rerun `wiki edit` (or check the files) after an interruption.\n\nWrites land only on wiki documents under `wiki.input`. Installed sources and the `.wiki/` cache are read-only, and so are symlinks and excluded paths.\n\n## Options\n\n| Flag | Default | Description |\n| ---------------- | ------- | ------------------------------------------------------------------- |\n| `--from FILE` | `-` | Read the edit from `FILE`, or `-` for stdin. |\n| `--apply` | off | Write the edit. Without it, validate and report only. |\n| `--force` | off | Write even if the edit introduces errors (they are still reported). |\n| `-f`, `--format` | `text` | `text` or `json` (the edit report on stdout). |\n| `--json` | — | Shorthand for `--format json`. |\n\n## Exit codes\n\n| Code | Meaning |\n| ---- | -------------------------------------------------------------------------------- |\n| `0` | The edit is valid (dry run), or written (`--apply`). |\n| `1` | Rejected: the edit introduces check or lint errors, or would leave links broken. |\n| `2` | Usage error: malformed JSON, an unknown op, or a path outside `wiki.input`. |\n| `3` | Conflict: an `expect` hash no longer matches the file. Nothing was written. |\n\n## Report\n\n`--json` writes one object (`version` 1):\n\n| Field | Description |\n| ------------ | ----------------------------------------------------------------------------------------------------------------- |\n| `status` | `dry_run`, `applied`, `rejected`, or `conflict`. |\n| `ok` | `true` for `dry_run` and `applied`. |\n| `files` | Per file: `path`, `action` (`create`, `modify`, `delete`), and `before`/`after` hashes (`null` when absent). |\n| `conflicts` | Per stale `expect`: `path`, `expected`, and `actual` (`null` when the file does not exist). |\n| `introduced` | Findings present after the edit and absent before it, in the [wiki check](wiki_check.md#json-output) issue shape. |\n| `check` | The scoped `check -f json` report of the edited pages, or `null` on a conflict. |\n\n## Example\n\nRecord a new spend in a budget ledger and note it in the ledger's change log, as one edit:\n\n```json\n{\n \"ops\": [\n {\n \"op\": \"create\",\n \"path\": \"wiki/Neon_(payment).md\",\n \"expect\": \"absent\",\n \"type\": \"schema:Purchase\",\n \"frontmatter\": {\n \"schema:name\": \"Neon plan\",\n \"schema:orderDate\": \"2026-10-10\",\n \"schema:priceCurrency\": \"USD\",\n \"schema:seller\": \"https://memory.wazoo.dev/Neon\",\n \"schema:customer\": \"https://memory.wazoo.dev/Ethan_Davidson\"\n },\n \"body\": \"Monthly Neon plan for the hosted world.\"\n },\n {\n \"op\": \"set\",\n \"path\": \"wiki/Neon_(payment).md\",\n \"field\": \"schema:price\",\n \"yaml\": \"19.00\"\n },\n {\n \"op\": \"patch\",\n \"path\": \"wiki/Budget_Ledger.md\",\n \"expect\": \"9d97…\",\n \"target\": { \"heading\": \"Change log\" },\n \"mode\": \"append\",\n \"content\": \"- 2026-10-10 — Added the Neon plan.\"\n }\n ]\n}\n```\n\nA dry run reports `status: \"dry_run\"` and the three files' `after` hashes, or `status: \"rejected\"` naming any required field the shape still misses. Adding `--apply` writes all of it or none of it.\n\n## See also\n\n- [wiki file show](wiki_file_show.md) and [wiki file refs](wiki_file_refs.md) — read a page and its links before editing\n- [wiki check](wiki_check.md) — the whole-wiki gate\n- [Wiki Programmatic API](Wiki_Programmatic_API.md) — `Wiki.edit()` in process";
schema:headline "wiki edit";
schema:dateCreated "2026-10-31T23:19:03Z"^^xsd:dateTime;
schema:dateModified "2026-10-31T23:19:03Z"^^xsd:dateTime.
<https://wazootech.github.io/wiki/wiki_edit> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://schema.org/TechArticle> .
<https://wazootech.github.io/wiki/wiki_edit> <https://schema.org/description> "Change a wiki through validated, atomic edits instead of hand-written Markdown." .
<https://wazootech.github.io/wiki/wiki_edit> <https://schema.org/articleBody> """# `wiki edit`
Apply a batch of page changes as one edit: validate it against the wiki's shapes, routes, and links before anything is written, then write every file or none. `wiki edit` takes the edit as JSON; [wiki file new](wiki_file_new.md), [wiki file set](wiki_file_set.md), [wiki file patch](wiki_file_patch.md), [wiki file mv](wiki_file_mv.md), and [wiki file rm](wiki_file_rm.md) build a one-op edit for you and share its flags, report, and exit codes. [wiki file show](wiki_file_show.md) and [wiki file refs](wiki_file_refs.md) are the read side.
## Why
Without it, an agent changes a wiki the way a person does in an editor: read whole files, hand-assemble YAML frontmatter, write body text, fix links by hand, then run `wiki check` and `wiki lint` and iterate on the diff. The engine already knows every invariant that loop re-derives (shapes, routes, the link graph), so `wiki edit` checks them at write time instead of after the fact ([wiki#353](https://github.com/wazootech/wiki/issues/353)).
These are guarded semantic writes, not an editor: there are no app-control verbs, and the CLI never commits. Git history stays with the caller's worktree.
## Usage
```bash
wiki edit --from plan.json # validate and report; writes nothing
wiki edit --from plan.json --apply # validate, then write atomically
cat plan.json | wiki edit --json # read the edit from stdin
```
## The edit format
An edit is `{"ops": [...]}`. Paths are relative to the config root (or absolute), never to the working directory, so a plan can be handed between agents unchanged.
| Op | Fields | What it does |
| --------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create` | `path`, `content` or `type`/`frontmatter`/`body`, `expect` | Create a page from full `content`, or scaffold it from a class `type` (such as `schema:Purchase`): the type's required fields first, then the rest of `frontmatter`, then an H1 and `body`. |
| `replace` | `path`, `content`, `expect` | Replace a file's whole content. |
| `set` | `path`, `field`, `value` or `yaml`, `expect` | Set one top-level frontmatter field; `value: null` removes it. `yaml` passes the value as YAML source, kept verbatim (`"12.00"` stays `12.00`, where the JSON number `12.00` becomes `12`). See [wiki file set](wiki_file_set.md). |
| `patch` | `path`, `target`, `mode`, `content`, `expect` | `target` is `{"heading": "Change log"}`, `{"frontmatter": true}`, or `{"body": true}`; `mode` is `append`, `prepend`, or `replace`. See [wiki file patch](wiki_file_patch.md). |
| `move` | `from`, `to`, `expect` | Move a page and repoint every link and metadata reference to it. `expect` applies to `from`; `to` must not exist. See [wiki file mv](wiki_file_mv.md). |
| `delete` | `path`, `pruneLinks`, `expect` | Delete a page. Refused while other pages link to it, unless `pruneLinks` turns those links into plain text. See [wiki file rm](wiki_file_rm.md). |
`expect` is the SHA-256 of the file's raw bytes, as [wiki file show](wiki_file_show.md) reports it, or `"absent"` for a create. It is checked against the file on disk before the edit, even when an earlier op in the same edit touched that file.
## The `expect` loop
1. `wiki file show PATH --json` and keep its `hash`.
2. Build the edit with `"expect": "<hash>"` on each op and dry-run it.
3. Apply it with `--apply`. Each file in the report carries its new `after` hash, which is the `expect` for the next edit.
If another agent changed the file in between, the edit exits `3` and writes nothing. Re-read the page with `wiki file show`, rebuild the edit against what is there now, and retry. Never `--force` past a conflict: `--force` overrides validation errors, not stale reads.
## Validation
The edit is staged in memory and the ordinary `check` and `lint` passes run twice over the same scope, once on the wiki as it is and once on the wiki as it would be. Only findings the edit **introduces** reject it, so a wiki that is already broken elsewhere does not block an unrelated change. A move re-anchors the moved page's existing findings, so they are not blamed on the move.
Validation is scoped, not whole-wiki: it covers the pages the edit touches and the pages that link to deleted or moved ones. A page whose SHACL result depends on a touched page without linking to it (for example an `sh:class` constraint on an IRI that page defines) is not re-validated, so an accepted edit can still break it. `wiki check` over the whole wiki remains the full gate; keep it in CI.
## Writing
Nothing is written without `--apply`. With it, every new file content goes to a sibling temp file first, then each is renamed over its target, and deletes go last. If any step fails, every file already written is restored to its exact original bytes, new files and directories are removed, and the error is reported. Just before writing, each file is compared with what was read once more, so a change that landed during validation is still a conflict.
Rollback happens inside the running process. If the process is killed partway through writing a multi-file edit (a hard crash, power loss, `kill -9`), files already renamed into place stay written and the rest do not; rerun `wiki edit` (or check the files) after an interruption.
Writes land only on wiki documents under `wiki.input`. Installed sources and the `.wiki/` cache are read-only, and so are symlinks and excluded paths.
## Options
| Flag | Default | Description |
| ---------------- | ------- | ------------------------------------------------------------------- |
| `--from FILE` | `-` | Read the edit from `FILE`, or `-` for stdin. |
| `--apply` | off | Write the edit. Without it, validate and report only. |
| `--force` | off | Write even if the edit introduces errors (they are still reported). |
| `-f`, `--format` | `text` | `text` or `json` (the edit report on stdout). |
| `--json` | — | Shorthand for `--format json`. |
## Exit codes
| Code | Meaning |
| ---- | -------------------------------------------------------------------------------- |
| `0` | The edit is valid (dry run), or written (`--apply`). |
| `1` | Rejected: the edit introduces check or lint errors, or would leave links broken. |
| `2` | Usage error: malformed JSON, an unknown op, or a path outside `wiki.input`. |
| `3` | Conflict: an `expect` hash no longer matches the file. Nothing was written. |
## Report
`--json` writes one object (`version` 1):
| Field | Description |
| ------------ | ----------------------------------------------------------------------------------------------------------------- |
| `status` | `dry_run`, `applied`, `rejected`, or `conflict`. |
| `ok` | `true` for `dry_run` and `applied`. |
| `files` | Per file: `path`, `action` (`create`, `modify`, `delete`), and `before`/`after` hashes (`null` when absent). |
| `conflicts` | Per stale `expect`: `path`, `expected`, and `actual` (`null` when the file does not exist). |
| `introduced` | Findings present after the edit and absent before it, in the [wiki check](wiki_check.md#json-output) issue shape. |
| `check` | The scoped `check -f json` report of the edited pages, or `null` on a conflict. |
## Example
Record a new spend in a budget ledger and note it in the ledger's change log, as one edit:
```json
{
"ops": [
{
"op": "create",
"path": "wiki/Neon_(payment).md",
"expect": "absent",
"type": "schema:Purchase",
"frontmatter": {
"schema:name": "Neon plan",
"schema:orderDate": "2026-10-10",
"schema:priceCurrency": "USD",
"schema:seller": "https://memory.wazoo.dev/Neon",
"schema:customer": "https://memory.wazoo.dev/Ethan_Davidson"
},
"body": "Monthly Neon plan for the hosted world."
},
{
"op": "set",
"path": "wiki/Neon_(payment).md",
"field": "schema:price",
"yaml": "19.00"
},
{
"op": "patch",
"path": "wiki/Budget_Ledger.md",
"expect": "9d97…",
"target": { "heading": "Change log" },
"mode": "append",
"content": "- 2026-10-10 — Added the Neon plan."
}
]
}
```
A dry run reports `status: "dry_run"` and the three files' `after` hashes, or `status: "rejected"` naming any required field the shape still misses. Adding `--apply` writes all of it or none of it.
## See also
- [wiki file show](wiki_file_show.md) and [wiki file refs](wiki_file_refs.md) — read a page and its links before editing
- [wiki check](wiki_check.md) — the whole-wiki gate
- [Wiki Programmatic API](Wiki_Programmatic_API.md) — `Wiki.edit()` in process""" .
<https://wazootech.github.io/wiki/wiki_edit> <https://schema.org/headline> "wiki edit" .
<https://wazootech.github.io/wiki/wiki_edit> <https://schema.org/dateCreated> "2026-10-31T23:19:03Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
<https://wazootech.github.io/wiki/wiki_edit> <https://schema.org/dateModified> "2026-10-31T23:19:03Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .