Docs Edit¶
Edit or create any knowledge unit by editing its Markdown file directly, with Workflow identity scaffolding, kind-aware validation, and index propagation bracketing the edit.
Workflow name: docs-edit
Workflow ID: wfd_16dc10a6e5eb496ca192ef5fd677085a
Execution: main
Override not allowed
Steps¶
| # | ID | Name | Type | Depends on |
|---|---|---|---|---|
| 1 | resolve |
Validate the request and resolve the file path | code |
|
| 2 | edit |
Edit the unit's Markdown file with your native Edit tool | reasoning |
resolve |
| 3 | commit |
Validate the edit, propagate to the store + index, and report | code |
edit |
Step instructions¶
resolve¶
Auto-run. Validates the request and returns the absolute .md file to edit. With create=true it scaffolds a minimal valid unit of the given kind first and returns that file. A Workflow scaffold receives a fresh opaque workflow_id; do not copy or edit it. You take no action here — read the returned file path for the next step.
edit¶
Edit the unit file at the file path the resolve step returned, using your native Edit tool. The YAML frontmatter carries the unit's structured fields; the Markdown body is content.full. For a Workflow unit, preserve its workflow_id, never author workflow_revision, retain the former workflow_name in workflow_aliases on a raw rename, and keep the frontmatter Step IDs synchronized with the ## <step-id> body sections. Use docs_move rather than a raw file move so identity and path-based Directions bindings remain correct. When the edit is done, advance with {"edited": true}.
commit¶
Auto-run. Re-reads the file and runs the kind-aware validation suite — DAG integrity, duplicate placeholders, required and kind-specific fields, Skill Op resolution, Directions→Workflow binding resolution, Workflow identity/address collisions, and Step-DAG cycles / dangling dependencies plus ## heading ↔ Step-ID consistency — then reconciles the store cache and search index. The resolve result carries the original Workflow ID, so this full Workflow rejects replacement as well as missing, malformed, duplicate, or colliding IDs. A native edit performed outside the resolve→commit flow has no pre-edit ID to compare and must preserve the value itself. If the step returns status: "error", fix the reported issues in the file and run docs_edit again; the reported unit_errors are scoped to the unit you edited.
Context¶
docs_edit is how an agent edits or creates a knowledge unit. The system store is one Markdown file per unit, so editing a unit is editing its file — this workflow brackets that native Edit with a resolve step (validate the request, hand back the file path) and a commit step (validate the result, reconcile the store cache + search index) so the change is correct and immediately visible to agent_docs / knowledge queries.
It handles every unit kind — prose (directions, system, concept, reference, integration, service), skill declarations, and workflow units alike; the commit step's validation is kind-aware. Operations that are not content edits — deleting or moving a unit — stay on the docs_delete / docs_move skills.