Define what the identity represents
Write a short identity statement covering the subject, owner, reader task, and evidence boundary. Use it to decide whether a change belongs in the same publication.
Append instead of overwrite
A formal update advances the canonical current revision while preserving fixed version links and their package or PDF representations.
ow publish ./artifact/document.mdw --update <document_id> --review --no-openUse each URL for its promise
- Canonical URL: latest formal state of a living work.
- Version permalink: approval, audit, citation, or release evidence.
- Versioned PDF: fixed offline attachment.
- Typed .mdw: reproducible Agent continuation and recovery.
Start a new identity when meaning changes
Create a new document when ownership, subject, audience, decision, or evidence boundary changes materially. Do not reuse an established URL merely to inherit attention.
FAQ
Frequently asked questions
Should a recurring report use a new URL every time?
Usually no. Keep one canonical identity and append formal revisions when the subject and reader contract remain the same.
Can a later revision change an old version permalink?
No. A version permalink identifies one immutable published revision.
Use the real workflow
Publish what your agent creates.
Give every report, document, or plan its own reader-ready page. Comments, review decisions, and formal revisions can flow back from there.