--- name: docujoint-vault-authoring description: Write and maintain documents in a docujoint vault — concept anatomy, evidence URIs, open questions, diagrams as data, and the lint/index/dashboard loop. Use when creating or editing documentation governed by a docujoint format. --- # Working in a docujoint vault The vault is parsed, not just read: what you write becomes rows, links, refs and derived state. Write for the parser and the human at once. ## Concept anatomy One concept = one file; **path is identity** (renames break inbound links — avoid them). Frontmatter carries `type`, `title`, a one-sentence honest `description` (it becomes the index entry and every preview), `tags`, and any fields the format declares (`app`, `database`, `status`, …) — those become badges, filters and graph joins, so fill them. Sections: `# Title` once, `## Section` per topic. Sections the format doesn't claim are free-form prose — tables, callouts (`> [!note]`), code fences all render. Sections claimed by a block (e.g. `## Features`, `## Scenarios`, `## Open questions`) must follow the block's columns exactly; keep the prose intro above the table, it is preserved and rendered. ## The rules that derive state (don't fight them) - **No status columns.** State derives from what you write: Implemented + Gap (+ evidence resolution) for features; test evidence for scenarios. To change a state, change the truth it derives from. - **Evidence or it didn't happen.** A row claiming completion cites scheme URIs (`repo://app/path`, `api://svc/route`, `db://db/table`, `test://…`). With an inventory connected, dead citations flip to `drift` automatically. - **Tests are evidence, not documents.** Put `test://` URIs on the exact feature/scenario rows they prove; never write prose docs about tests. - **Doubts become open questions**, in the doc they belong to, with `About` pointing at the exact row they block (`f3`, `s2`). An open question about an empty row derives `unspecified` — visible, honest, unblocked by nobody's memory. ## Diagrams are data Use ```mermaid fences; flowchart/graph, sequenceDiagram, stateDiagram(-v2) and erDiagram are parsed into the IR (nodes + edges), then rendered. Name diagram nodes after documented concepts and canonical enum values — the diagram then mirrors the system instead of decorating it. Unknown diagram kinds are a lint finding. ## Flow documents are nodes Treat every flow document as a NODE in its process — a step, a stage, or a complement. A node that hands over to other nodes declares that in a `## Transitions` table (`To` · `When`): `To` names the next node — link the cell when the target has a document, plain text for an outcome that has none yet — and `When` carries the business rule that fires the move. The engine chains a document and its `parent_flow` children into one process graph from these rows (see the block's `display.graph` declaration). Wire only what the documents already state; where the sequence is unwritten, raise an open question instead of guessing the target. Complement documents (playbooks, reference material) legitimately carry no Transitions. A scenario is, at bottom, a chain of transitions — give each node its own Scenarios whose `Result` names the node or outcome it hands over to, and the path tree and the process graph tell the same story from two angles. ## Links Markdown paths from the vault root, angle-bracketed when they contain spaces: `[orders]()`. Never `[[wikilinks]]`. Broken links warn — fix or remove them. ## The loop ```sh dj lint --all --vault vault --format format.yaml # after every edit dj index --vault vault --format format.yaml --write # after adding concepts dj dashboard --vault vault --format format.yaml \ --dashboard dashboard.yaml --out dashboard.html # see the effect ``` Errors mean the parser broke or the doc asserts something false — fix before committing. Warnings are the incompleteness report — burn them down, and gate merges with `--warnings-as-errors` when the vault is mature. `dj index` maintains the catalogue surgically; never hand-edit generated entries. ## Starting from a template Scaffolded files carry a `✂ docujoint template` watermark comment — replace the sample content with your system's and delete the watermark line as you claim each file. The samples exist to show one lint-clean example of every mechanism; keep them until yours cover the same ground.