Describe editable SVG files as the default local draft artifact and Publish or Encrypt & Publish as explicit server-persistence actions. Document all five quick actions and each supported file, drop, paste, and URL import path. Specify the versioned metadata and data-* contract, deterministic fail-closed import behavior, the 5 MiB limit, and plaintext implications for locked drafts. Update diagramming and review skills and regenerate llms.txt, llms-full.txt, and published skill copies. Extend documentation checks for the renamed published-state guide and verify the complete Docusaurus production build.
- commit
- cdb57c33341c75087fdbfd1058683fdd7a70786f
- parent
- 3ffc37a5dc85a4fa54c4debaf44c4ddcdacb285d
- author
- Dami <dami.etoile@gmail.com>
@@ -1,6 +1,6 @@
11 # diagram.zip22 3-[diagram.zip](https://diagram.zip) is a browser-first diagram editor with live SVG previews, local drafts, and encrypted, accountless sharing. The repository contains the editor, documentation, persistence API, renderer catalog, and the isolated renderer units behind the service.3+[diagram.zip](https://diagram.zip) is a browser-first diagram editor with live SVG previews, local drafts, editable SVG files, and encrypted, accountless sharing. The repository contains the editor, documentation, persistence API, renderer catalog, and the isolated renderer units behind the service.44 55 ## What is here66 @@ -64,7 +64,11 @@ are not the production release procedure.
6464 6565 The editor runs at `diagram.zip`. Rendering is split into isolated units selected by hostname at `{engine}.render.diagram.zip`; the renderer catalog documents the contract and capabilities for all supported engines. Five renderers run in sandboxed browser frames, while the remaining renderers run in JavaScript, Python, or WebAssembly Workers.6666 67-Saved diagrams use encrypted client-side content, mutable aliases in D1, and immutable content-addressed objects in R2. See [`apps/editor/PERSISTENCE.md`](apps/editor/PERSISTENCE.md) for the persistence and security contract.67+Server persistence is opt-in. **Publish** creates an open alias, while68+**Encrypt & Publish** creates an encrypted alias. Anonymous drafts can use69+**Save as File** to download an editable enriched SVG without server state.70+See [`apps/editor/PERSISTENCE.md`](apps/editor/PERSISTENCE.md) for the71+persistence and security contract.6872 6973 ## Project history and licensing7074 @@ -10,6 +10,11 @@ sidebar_position: 2
1010 Use a password when a diagram must not be readable by people who only have its1111 read link.1212 13+Choose **Encrypt & Publish** to opt into encrypted server persistence. Choose14+**Save as File** when the draft should remain local. An editable SVG export is15+plain text so it can remain a useful image, and it must not be treated as an16+encrypted backup.17+1318 ## What is encrypted1419 1520 When you lock a diagram, the browser encrypts these items before it sends them@@ -19,7 +24,7 @@ to diagram.zip:
1924 - diagram type and renderer options;2025 - presentation settings;2126 - title and description;22-- saved SVG and PNG renders.27+- published SVG and PNG renders.2328 2429 The browser decrypts the diagram after you enter the password. The renderer2530 can receive the source while it creates a preview. Persistent storage receives@@ -35,7 +40,7 @@ does not receive either value.
3540 3641 The password also protects read access. A person with only the read link sees a3742 password prompt. A person with an edit link still needs the password before38-they can read or save the diagram.43+they can read or publish the diagram.3944 4045 ## Password changes4146 @@ -47,7 +52,7 @@ Enter the current password before you change or remove password protection.
4752 ## Password loss4853 4954 There is no password reset or account recovery. If you lose the password, you50-cannot decrypt the source, metadata, or saved renders. Keep a secure copy of55+cannot decrypt the source, metadata, or published renders. Keep a secure copy of5156 the password when the diagram is important.5257 5358 ## Locked drafts@@ -55,12 +60,16 @@ the password when the diagram is important.
5560 The editor keeps an open draft in the browser so you can recover recent work.5661 It does not write a locked draft to browser storage as plaintext.5762 58-For a locked diagram, keep the page open and save the diagram explicitly. A59-locked draft is persisted only after a successful save. If the page closes60-before that save, the browser may not be able to restore the draft.63+For a locked diagram, keep the page open and publish the diagram explicitly. A64+locked draft is persisted only after a successful publish. If the page closes65+before that publish, the browser may not be able to restore the draft.6166 6267 ## Embeds6368 6469 Locked diagrams cannot use public SVG or Markdown embeds. An embed has no safe6570 way to ask for the password. Open the diagram in diagram.zip to enter the6671 password and view it.72+73+An editable SVG imported from a file, pasted text, or a URL creates a local74+draft after validation. The importer rejects ordinary, ambiguous, unsupported,75+or lossy SVG and limits input to 5 MiB.@@ -7,14 +7,24 @@ sidebar_position: 1
77 88 # Share a diagram99 10-Save a diagram before you share it. A saved diagram has a stable read link.10+Publishing is optional. Anonymous drafts remain local until you choose11+**Publish** or **Encrypt & Publish**. A published diagram has a stable alias.1112 12-The Share dialog contains link controls and privacy controls. Lock, password13-change, and password removal actions stay beside the content they affect.13+The Share menu contains these actions:14+15+- **Publish** creates or updates an open server alias.16+- **Encrypt & Publish** creates or updates a password-protected server alias.17+- **Save as File** downloads an editable enriched SVG without server persistence.18+- **Copy SVG URL** copies an image URL for an open published alias.19+- **Copy as Markdown** copies a Markdown image using that SVG URL.20+21+Lock, password change, and password removal actions stay beside the content22+they affect. Save as File is available for a local draft and does not require23+an account or network persistence.1424 1525 ## Read links1626 17-A read link lets a person open the saved diagram. The link has this form:27+A read link lets a person open the published diagram. The link has this form:1828 1929 ```text2030 https://diagram.zip/d/{alias}@@ -23,14 +33,17 @@ https://diagram.zip/d/{alias}
2333 Anyone who has an open read link can view the diagram. Anyone who has an open2434 read link can also use the SVG or Markdown embed link.2535 26-A read link does not let a person save changes to the saved diagram.36+A read link does not let a person update the published diagram.37+38+An editable SVG file is separate from a read link. It remains useful as an SVG39+image, while its versioned Diagram.zip document supports a later import.2740 2841 For a locked diagram, the person must also enter the password. The password is2942 not part of the read link.3043 3144 ## Edit links3245 33-An edit link gives permission to save changes to the alias. It has this form:46+An edit link gives permission to publish changes to the alias. It has this form:3447 3548 ```text3649 https://diagram.zip/d/{alias}#w={write-capability}@@ -40,7 +53,7 @@ The edit capability is a bearer credential. Anyone who has the complete edit
4053 link can update the diagram. Share it only with people who should have write4154 access.4255 43-The browser reads the capability from the URL fragment. The browser then saves56+The browser reads the capability from the URL fragment. The browser then stores4457 it for that alias and removes it from the address bar. A copied page URL is4558 therefore normally a read link. Copy the edit link from the Share dialog when4659 you need to share write access.@@ -58,36 +71,47 @@ locked diagram, you cannot decrypt it.
5871 ## Read-only edits and forks5972 6073 You can edit a diagram after opening a read link. These edits stay local until61-you save them.74+you publish them.6275 6376 If this browser already has unsaved changes for the link, a local-changes bar64-offers **Restore saved** and **Make a copy**. Restore returns to the shared77+offers **Restore published** and **Make a copy**. Restore returns to the shared6578 revision. Make a copy forks the local state to a new alias, even when this6679 browser also holds write access to the original.6780 68-The Save button becomes **Save copy** because you do not have write access to69-the original alias. Save the copy to create a new alias and a new edit link.70-The original diagram does not change.81+The Publish button becomes **Publish a Copy** because you do not have write82+access to the original alias. Publish the copy to create a new alias and a new83+edit link. The original diagram does not change.7184 72-## Save conflicts85+## Publish conflicts7386 74-Each saved alias has a revision. The editor checks the revision when it saves.87+Each published alias has a revision. The editor checks the revision when it88+publishes.7589 76-If another person saved a newer revision first, diagram.zip reports a save77-conflict. Choose one of these actions:90+If another person published a newer revision first, diagram.zip reports a91+publish conflict. Choose one of these actions:7892 79-- **Reload saved** discards your local edits and opens the newer saved version.80-- **Save as new** keeps your edits and creates a separate alias.93+- **Reload published** discards local edits and opens the newer published version.94+- **Publish as new** keeps your edits and creates a separate alias.8195 82-The editor does not overwrite a newer saved revision without your choice.96+The editor does not overwrite a newer published revision without your choice.8397 8498 ## Embeds8599 86100 The Share dialog provides an SVG image link and a Markdown image link for an87-open saved diagram. These links point to the saved render.101+open published diagram. These links point to the published render.88102 89103 Locked diagrams cannot be embedded. An embed request cannot ask for a password,90104 so the server does not return encrypted diagram renders as public images.91105 92-Save the diagram again before you share if the Share dialog says that the links93-show an older saved version.106+Publish the diagram again before you share if the Share dialog says that the107+links show an older published version.108+109+## Importing an editable SVG110+111+Open an editable SVG from a file picker, drag and drop it, paste SVG text, or112+provide an HTTP(S) or data URL. This flow creates a local draft first. It does113+not publish the draft automatically.114+115+The importer accepts only a valid, versioned Diagram.zip document. It rejects116+ordinary SVG, ambiguous metadata, unsupported schema versions, and inputs that117+would lose source or presentation information. Input is limited to 5 MiB.@@ -1,14 +1,14 @@
11 ---22 id: working-and-saved-state3-title: Working state and saved state4-description: Understand editor drafts, saved revisions, and persistent diagram data.3+title: Working state and published state4+description: Understand editor drafts, published revisions, and persistent diagram data.55 sidebar_position: 366 ---77 8-# Working state and saved state8+# Working state and published state99 10-The editor has a working state and a saved state. They can be different until11-you save.10+The editor has a working state and a published state. They can be different11+until you publish.1212 1313 ## Working state1414 @@ -19,42 +19,53 @@ Source and Details use separate editor tabs. Details is a JSON document that
1919 contains the title, description, and presentation settings.2020 2121 Invalid Details JSON remains in the local draft. The editor keeps the last22-valid preview and blocks save, share, privacy, and type changes until it is valid.22+valid preview and blocks file export, publishing, sharing, privacy, and type23+changes until it is valid.2324 24-When you edit a saved diagram, the working state changes first. The saved25-diagram does not change until you choose **Save**.25+When you edit a published diagram, the working state changes first. The26+published diagram does not change until you choose **Publish**.2627 2728 For an open diagram, diagram.zip stores the working state as a local browser28-draft. This draft supports recovery on the same browser. It is not a saved29+draft. This draft supports recovery on the same browser. It is not a published2930 diagram and other people cannot read it.3031 32+Anonymous drafts default to local work. **Save as File** exports the working33+state as an editable enriched SVG. The file remains useful as a visible SVG34+image and contains a versioned Diagram.zip document for later import.35+36+Importing an editable SVG creates a local draft. The input can come from a37+file, drag and drop, pasted SVG text, or an HTTP(S) or data URL. The importer38+rejects ordinary, ambiguous, unsupported, or lossy SVG instead of guessing.39+Imported input has a 5 MiB limit.40+3141 An edited anonymous example shows a reset icon. Reset removes its local draft3242 and restores the bundled example after confirmation.3343 34-When a saved link opens with a different local draft, the editor marks that35-draft as a device-only overlay. Choose **Restore saved** to discard the overlay36-and return to the alias revision, or **Make a copy** to preserve it under a new37-alias. Neither action silently changes the original share link.44+When a published link opens with a different local draft, the editor marks45+that draft as a device-only overlay. Choose **Restore published** to discard46+the overlay and return to the alias revision, or **Make a copy** to preserve it47+under a new alias. Neither action silently changes the original share link.3848 3949 For a locked diagram, the editor does not store the working state as plaintext40-in browser storage. Save a locked diagram explicitly to persist it.50+in browser storage. Publish a locked diagram explicitly to persist it.4151 42-Zoom and pan are preview session state, not saved diagram state. Appearance52+Zoom and pan are preview session state, not published diagram state. Appearance4353 changes and Edit or Preview tab switches preserve the current view position.4454 45-## Saved state55+## Published state4656 47-The saved state is the last version that you saved successfully. It has an48-alias, a revision, and a stable read link.57+The published state is the last version that you published successfully. It58+has an alias, a revision, and a stable read link.4959 50-The Share dialog uses the saved state. If the working state has changes, the51-dialog tells you to save before you share. This prevents you from sharing an52-older version by mistake.60+The Share dialog uses the published state. If the working state has changes,61+the dialog tells you to publish before you share. This prevents you from62+sharing an older version by mistake.5363 5464 ## Persistent data5565 56-After a successful save, diagram.zip persists the diagram content and its57-metadata. It can also persist SVG and PNG renders for that saved revision.66+After a successful Publish or Encrypt & Publish, diagram.zip persists the67+diagram content and its metadata. It can also persist SVG and PNG renders for68+that published revision.5869 5970 Open content is stored as readable diagram data. Locked content and locked6071 renders are stored as encrypted data. See [Password encryption](/collaboration/encryption/)@@ -63,25 +74,25 @@ for the locked diagram rules.
6374 The persisted data belongs to the alias and its current revision. A local draft6475 does not replace the persisted data.6576 66-## Save flow77+## Publish flow6778 6879 The normal flow is:6980 7081 1. Edit the working state.71-2. Choose **Save**.82+2. Choose **Publish** or **Encrypt & Publish**.7283 3. diagram.zip stores a new revision.73-4. The saved state becomes the working state.84+4. The published state becomes the working state.7485 75-Saving a new diagram creates an alias and an edit capability. Saving an open76-diagram with an edit capability updates its alias. Saving a read-only diagram77-creates a new alias instead.86+Publishing a new diagram creates an alias and an edit capability. Publishing87+an open diagram with an edit capability updates its alias. Publishing a88+read-only diagram creates a new alias instead.7889 7990 ## Conflicts8091 81-The editor saves against the revision that it last loaded. If that revision is82-no longer current, another person saved the alias first.92+The editor publishes against the revision that it last loaded. If that revision93+is no longer current, another person published the alias first.8394 84-The editor then offers **Reload saved** or **Save as new**. Reload replaces the85-working state with the current saved state. Save as new preserves the working86-state in a new alias. diagram.zip does not silently overwrite the other87-person's saved version.95+The editor then offers **Reload published** or **Publish as new**. Reload96+replaces the working state with the current published state. Publish as new97+preserves the working state in a new alias. diagram.zip does not silently98+overwrite the other person's published version.@@ -16,7 +16,22 @@ Start with a diagram type. Each type page shows the source format, a small examp
1616 4. Replace the example labels and connections.1717 5. Edit metadata or presentation in the **Details** tab when needed.1818 6. Check the preview.19-7. Save the diagram when you want a stable link.19+7. Choose **Save as File** for a portable editable SVG, or **Publish** for a stable server alias.20+21+## Open an existing diagram22+23+You can reopen an editable SVG from a local file, including a file selected on24+mobile, or by dragging it into the editor. You can also paste SVG text into the25+open flow. The editor accepts an HTTP(S) or data URL when the response is an26+SVG document.27+28+An editable SVG remains a useful visible image. It also contains a versioned29+Diagram.zip document in SVG metadata and `data-*` attributes. The document30+restores the source, type, options, presentation, title, and description.31+32+The editor validates the embedded document before creating a draft. Ordinary33+SVG, ambiguous SVG, unsupported SVG, and lossy SVG are rejected instead of34+being guessed or silently converted. Imported input is limited to 5 MiB.2035 2136 ## Choose a type2237 @@ -46,10 +61,20 @@ Read [General presentation settings](/style/presentation/) for the Details docum
4661 4762 Open diagrams keep unsaved changes in local browser storage. An edited example shows a reset icon that restores its bundled source and details.4863 49-Saved links use a separate device-only overlay for local changes. Read [Working state and saved state](/collaboration/working-and-saved-state/) before restoring or copying that overlay.64+Anonymous drafts default to local work. **Save as File** downloads an editable65+SVG without creating a server alias. The downloaded file can be reopened on66+another device through the same import flow.67+68+Published links use a separate device-only overlay for local changes. Read69+[Working state and published state](/collaboration/working-and-saved-state/)70+before restoring or copying that overlay.5071 51-## Save or share72+## Save, publish, or share5273 53-Use **Save** to create a saved revision. Use a read link when people only need to view the diagram.74+Use **Publish** to create or update a server alias. Use **Encrypt & Publish**75+when the server copy requires password protection. Both actions opt into server76+persistence.5477 55-Use an edit link when people must save changes. Read [Share a diagram](/collaboration/sharing/) before you send an edit link.78+Use an edit link when people must save changes. The Share menu also provides79+**Copy SVG URL** and **Copy as Markdown** for image embeds. Read [Share a80+diagram](/collaboration/sharing/) before you send an edit link.@@ -19,6 +19,26 @@ renderer SVG
1919 2020 The renderer owns source interpretation and layout. Later stages preserve diagram geometry while adding safety, semantic paint roles, and optional presentation bounds.2121 22+## Editable SVG contract23+24+An editable export is still a normal visible SVG. It embeds a versioned25+Diagram.zip document in `<metadata>` and uses `data-*` attributes for compact26+per-element and root bindings. The document records the source type, source,27+renderer options, presentation, title, and description.28+29+The metadata contract is versioned independently from rendering contracts. An30+importer must validate the schema, required fields, size limit, and deterministic31+reconstruction before it creates a draft. The current input limit is 5 MiB.32+33+The importer accepts a validated enriched SVG from a local file, drag and drop,34+pasted SVG text, or an HTTP(S) or data URL. It rejects ordinary SVG, ambiguous35+metadata, unsupported schema versions, and any input that would lose source or36+presentation information. It does not infer a source language from visible37+shapes.38+39+**Save as File** exports the enriched SVG without server persistence. **Publish**40+and **Encrypt & Publish** persist aliases separately from the file export.41+2242 ## Artifact stages2343 2444 | Stage | Contract |@@ -122,7 +122,7 @@ const llmsFull = await source(join(site, 'static', 'llms-full.txt'))
122122 assert(llms.includes('https://docs.diagram.zip/create/'), 'llms.txt does not link the editor workspace guide.')123123 assert(llms.includes('https://docs.diagram.zip/style/presentation/'), 'llms.txt does not link the Details presentation guide.')124124 assert(llmsFull.includes('# General presentation settings'), 'llms-full.txt does not include the presentation guide.')125-assert(llmsFull.includes('# Working state and saved state'), 'llms-full.txt does not include the working-state guide.')125+assert(llmsFull.includes('# Working state and published state'), 'llms-full.txt does not include the working-state guide.')126126 127127 const expectedSkillIds = [...diagramSkillIds].sort()128128 const skillEntries = await readdir(skills, { withFileTypes: true })@@ -158,7 +158,10 @@ await Promise.all(diagramTypes.flatMap((type) => [
158158 await Promise.all(diagramSkills.map(({ id }) => cp(join(skillsDir, id), join(publicSkillsDir, id), { recursive: true })))159159 await writeFile(join(staticDir, 'diagram-types.json'), `${JSON.stringify({ version: 1, diagramTypes: catalog }, null, 2)}\n`)160160 await writeFile(join(staticDir, 'diagram-skills.json'), `${JSON.stringify({ version: 1, groups: skillGroups, skills: skillCatalog, standards: standardsSupport }, null, 2)}\n`)161-await writeFile(join(staticDir, 'llms.txt'), `# diagram.zip documentation\n\n> Choose the semantic story first. Use Source for notation and Details for metadata and presentation.\n\n- [Diagram routing skill](https://docs.diagram.zip/skills/diagramming/SKILL.md): Select a diagram family from the reader's question.\n- [Machine-readable semantic catalog](https://docs.diagram.zip/diagram-skills.json): Inspect every skill, use case, exclusion, role, and invocation constraint.\n\n${skillIndex()}\n\n## Renderer and source formats\n\n${diagramTypes.map((type) => `- [${type.label} syntax](https://docs.diagram.zip${syntaxPath(type.id)}/): Create ${articleFor(type.label)} ${type.label} diagram. [Style](https://docs.diagram.zip${stylePath(type.id)}/).`).join('\n')}\n\n## General pages\n\n- [Editor workspace](https://docs.diagram.zip/create/)\n- [Details JSON and presentation](https://docs.diagram.zip/style/presentation/)\n- [SVG normalization and version contracts](https://docs.diagram.zip/style/svg-normalization/)\n- [Share a diagram](https://docs.diagram.zip/collaboration/sharing/)\n- [Password encryption](https://docs.diagram.zip/collaboration/encryption/)\n- [Working state and saved state](https://docs.diagram.zip/collaboration/working-and-saved-state/)\n\n## Structured catalogs\n\n- [diagram-skills.json](https://docs.diagram.zip/diagram-skills.json)\n- [diagram-types.json](https://docs.diagram.zip/diagram-types.json)\n- [Full documentation text](https://docs.diagram.zip/llms-full.txt)\n- [Source repository](https://github.com/FelineStateMachine/diagramzip)\n`)161+await writeFile(join(staticDir, 'llms.txt'), `# diagram.zip documentation\n\n> Choose the semantic story first. Use Source for notation and Details for metadata and presentation.\n\n- [Diagram routing skill](https://docs.diagram.zip/skills/diagramming/SKILL.md): Select a diagram family from the reader's question.\n- [Machine-readable semantic catalog](https://docs.diagram.zip/diagram-skills.json): Inspect every skill, use case, exclusion, role, and invocation constraint.\n\n${skillIndex()}\n\n## Renderer and source formats\n\n${diagramTypes.map((type) => `- [${type.label} syntax](https://docs.diagram.zip${syntaxPath(type.id)}/): Create ${articleFor(type.label)} ${type.label} diagram. [Style](https://docs.diagram.zip${stylePath(type.id)}/).`).join('\n')}\n\n## General pages\n\n- [Editor workspace](https://docs.diagram.zip/create/)\n- [Editable SVG files and local drafts](https://docs.diagram.zip/create/): Reopen validated enriched SVG files without publishing.\n- [Details JSON and presentation](https://docs.diagram.zip/style/presentation/)\n- [SVG normalization and version contracts](https://docs.diagram.zip/style/svg-normalization/)\n- [Share a diagram](https://docs.diagram.zip/collaboration/sharing/)\n- [Password encryption](https://docs.diagram.zip/collaboration/encryption/)\n- [Working state and saved state](https://docs.diagram.zip/collaboration/working-and-saved-state/)\n\n## Structured catalogs\n\n- [diagram-skills.json](https://docs.diagram.zip/diagram-skills.json)\n- [diagram-types.json](https://docs.diagram.zip/diagram-types.json)\n- [Full documentation text](https://docs.diagram.zip/llms-full.txt)\n- [Source repository](https://github.com/FelineStateMachine/diagramzip)\n`)162+const llmsPath = join(staticDir, 'llms.txt')163+const llmsIndex = await readFile(llmsPath, 'utf8')164+await writeFile(llmsPath, llmsIndex.replace('Working state and saved state', 'Working state and published state'))162165 await writeFile(join(staticDir, 'llms-full.txt'), `# diagram.zip documentation\n\n${await fullText()}`)163166 164167 console.log(`Generated ${diagramTypes.length} renderer guides, ${diagramSkills.length} semantic skill packages, and machine-readable indexes.`)@@ -18,7 +18,22 @@ Start with a diagram type. Each type page shows the source format, a small examp
1818 4. Replace the example labels and connections.1919 5. Edit metadata or presentation in the **Details** tab when needed.2020 6. Check the preview.21-7. Save the diagram when you want a stable link.21+7. Choose **Save as File** for a portable editable SVG, or **Publish** for a stable server alias.22+23+## Open an existing diagram24+25+You can reopen an editable SVG from a local file, including a file selected on26+mobile, or by dragging it into the editor. You can also paste SVG text into the27+open flow. The editor accepts an HTTP(S) or data URL when the response is an28+SVG document.29+30+An editable SVG remains a useful visible image. It also contains a versioned31+Diagram.zip document in SVG metadata and `data-*` attributes. The document32+restores the source, type, options, presentation, title, and description.33+34+The editor validates the embedded document before creating a draft. Ordinary35+SVG, ambiguous SVG, unsupported SVG, and lossy SVG are rejected instead of36+being guessed or silently converted. Imported input is limited to 5 MiB.2237 2338 ## Choose a type2439 @@ -48,13 +63,23 @@ Read [General presentation settings](/style/presentation/) for the Details docum
4863 4964 Open diagrams keep unsaved changes in local browser storage. An edited example shows a reset icon that restores its bundled source and details.5065 51-Saved links use a separate device-only overlay for local changes. Read [Working state and saved state](/collaboration/working-and-saved-state/) before restoring or copying that overlay.66+Anonymous drafts default to local work. **Save as File** downloads an editable67+SVG without creating a server alias. The downloaded file can be reopened on68+another device through the same import flow.69+70+Published links use a separate device-only overlay for local changes. Read71+[Working state and published state](/collaboration/working-and-saved-state/)72+before restoring or copying that overlay.5273 53-## Save or share74+## Save, publish, or share5475 55-Use **Save** to create a saved revision. Use a read link when people only need to view the diagram.76+Use **Publish** to create or update a server alias. Use **Encrypt & Publish**77+when the server copy requires password protection. Both actions opt into server78+persistence.5679 57-Use an edit link when people must save changes. Read [Share a diagram](/collaboration/sharing/) before you send an edit link.80+Use an edit link when people must save changes. The Share menu also provides81+**Copy SVG URL** and **Copy as Markdown** for image embeds. Read [Share a82+diagram](/collaboration/sharing/) before you send an edit link.5883 5984 ---6085 @@ -166,6 +191,26 @@ renderer SVG
166191 167192 The renderer owns source interpretation and layout. Later stages preserve diagram geometry while adding safety, semantic paint roles, and optional presentation bounds.168193 194+## Editable SVG contract195+196+An editable export is still a normal visible SVG. It embeds a versioned197+Diagram.zip document in `<metadata>` and uses `data-*` attributes for compact198+per-element and root bindings. The document records the source type, source,199+renderer options, presentation, title, and description.200+201+The metadata contract is versioned independently from rendering contracts. An202+importer must validate the schema, required fields, size limit, and deterministic203+reconstruction before it creates a draft. The current input limit is 5 MiB.204+205+The importer accepts a validated enriched SVG from a local file, drag and drop,206+pasted SVG text, or an HTTP(S) or data URL. It rejects ordinary SVG, ambiguous207+metadata, unsupported schema versions, and any input that would lose source or208+presentation information. It does not infer a source language from visible209+shapes.210+211+**Save as File** exports the enriched SVG without server persistence. **Publish**212+and **Encrypt & Publish** persist aliases separately from the file export.213+169214 ## Artifact stages170215 171216 | Stage | Contract |@@ -320,14 +365,24 @@ sidebar_position: 1
320365 321366 # Share a diagram322367 323-Save a diagram before you share it. A saved diagram has a stable read link.368+Publishing is optional. Anonymous drafts remain local until you choose369+**Publish** or **Encrypt & Publish**. A published diagram has a stable alias.324370 325-The Share dialog contains link controls and privacy controls. Lock, password326-change, and password removal actions stay beside the content they affect.371+The Share menu contains these actions:372+373+- **Publish** creates or updates an open server alias.374+- **Encrypt & Publish** creates or updates a password-protected server alias.375+- **Save as File** downloads an editable enriched SVG without server persistence.376+- **Copy SVG URL** copies an image URL for an open published alias.377+- **Copy as Markdown** copies a Markdown image using that SVG URL.378+379+Lock, password change, and password removal actions stay beside the content380+they affect. Save as File is available for a local draft and does not require381+an account or network persistence.327382 328383 ## Read links329384 330-A read link lets a person open the saved diagram. The link has this form:385+A read link lets a person open the published diagram. The link has this form:331386 332387 ```text333388 https://diagram.zip/d/{alias}@@ -336,14 +391,17 @@ https://diagram.zip/d/{alias}
336391 Anyone who has an open read link can view the diagram. Anyone who has an open337392 read link can also use the SVG or Markdown embed link.338393 339-A read link does not let a person save changes to the saved diagram.394+A read link does not let a person update the published diagram.395+396+An editable SVG file is separate from a read link. It remains useful as an SVG397+image, while its versioned Diagram.zip document supports a later import.340398 341399 For a locked diagram, the person must also enter the password. The password is342400 not part of the read link.343401 344402 ## Edit links345403 346-An edit link gives permission to save changes to the alias. It has this form:404+An edit link gives permission to publish changes to the alias. It has this form:347405 348406 ```text349407 https://diagram.zip/d/{alias}#w={write-capability}@@ -353,7 +411,7 @@ The edit capability is a bearer credential. Anyone who has the complete edit
353411 link can update the diagram. Share it only with people who should have write354412 access.355413 356-The browser reads the capability from the URL fragment. The browser then saves414+The browser reads the capability from the URL fragment. The browser then stores357415 it for that alias and removes it from the address bar. A copied page URL is358416 therefore normally a read link. Copy the edit link from the Share dialog when359417 you need to share write access.@@ -371,39 +429,50 @@ locked diagram, you cannot decrypt it.
371429 ## Read-only edits and forks372430 373431 You can edit a diagram after opening a read link. These edits stay local until374-you save them.432+you publish them.375433 376434 If this browser already has unsaved changes for the link, a local-changes bar377-offers **Restore saved** and **Make a copy**. Restore returns to the shared435+offers **Restore published** and **Make a copy**. Restore returns to the shared378436 revision. Make a copy forks the local state to a new alias, even when this379437 browser also holds write access to the original.380438 381-The Save button becomes **Save copy** because you do not have write access to382-the original alias. Save the copy to create a new alias and a new edit link.383-The original diagram does not change.439+The Publish button becomes **Publish a Copy** because you do not have write440+access to the original alias. Publish the copy to create a new alias and a new441+edit link. The original diagram does not change.384442 385-## Save conflicts443+## Publish conflicts386444 387-Each saved alias has a revision. The editor checks the revision when it saves.445+Each published alias has a revision. The editor checks the revision when it446+publishes.388447 389-If another person saved a newer revision first, diagram.zip reports a save390-conflict. Choose one of these actions:448+If another person published a newer revision first, diagram.zip reports a449+publish conflict. Choose one of these actions:391450 392-- **Reload saved** discards your local edits and opens the newer saved version.393-- **Save as new** keeps your edits and creates a separate alias.451+- **Reload published** discards local edits and opens the newer published version.452+- **Publish as new** keeps your edits and creates a separate alias.394453 395-The editor does not overwrite a newer saved revision without your choice.454+The editor does not overwrite a newer published revision without your choice.396455 397456 ## Embeds398457 399458 The Share dialog provides an SVG image link and a Markdown image link for an400-open saved diagram. These links point to the saved render.459+open published diagram. These links point to the published render.401460 402461 Locked diagrams cannot be embedded. An embed request cannot ask for a password,403462 so the server does not return encrypted diagram renders as public images.404463 405-Save the diagram again before you share if the Share dialog says that the links406-show an older saved version.464+Publish the diagram again before you share if the Share dialog says that the465+links show an older published version.466+467+## Importing an editable SVG468+469+Open an editable SVG from a file picker, drag and drop it, paste SVG text, or470+provide an HTTP(S) or data URL. This flow creates a local draft first. It does471+not publish the draft automatically.472+473+The importer accepts only a valid, versioned Diagram.zip document. It rejects474+ordinary SVG, ambiguous metadata, unsupported schema versions, and inputs that475+would lose source or presentation information. Input is limited to 5 MiB.407476 408477 ---409478 @@ -419,6 +488,11 @@ sidebar_position: 2
419488 Use a password when a diagram must not be readable by people who only have its420489 read link.421490 491+Choose **Encrypt & Publish** to opt into encrypted server persistence. Choose492+**Save as File** when the draft should remain local. An editable SVG export is493+plain text so it can remain a useful image, and it must not be treated as an494+encrypted backup.495+422496 ## What is encrypted423497 424498 When you lock a diagram, the browser encrypts these items before it sends them@@ -428,7 +502,7 @@ to diagram.zip:
428502 - diagram type and renderer options;429503 - presentation settings;430504 - title and description;431-- saved SVG and PNG renders.505+- published SVG and PNG renders.432506 433507 The browser decrypts the diagram after you enter the password. The renderer434508 can receive the source while it creates a preview. Persistent storage receives@@ -444,7 +518,7 @@ does not receive either value.
444518 445519 The password also protects read access. A person with only the read link sees a446520 password prompt. A person with an edit link still needs the password before447-they can read or save the diagram.521+they can read or publish the diagram.448522 449523 ## Password changes450524 @@ -456,7 +530,7 @@ Enter the current password before you change or remove password protection.
456530 ## Password loss457531 458532 There is no password reset or account recovery. If you lose the password, you459-cannot decrypt the source, metadata, or saved renders. Keep a secure copy of533+cannot decrypt the source, metadata, or published renders. Keep a secure copy of460534 the password when the diagram is important.461535 462536 ## Locked drafts@@ -464,9 +538,9 @@ the password when the diagram is important.
464538 The editor keeps an open draft in the browser so you can recover recent work.465539 It does not write a locked draft to browser storage as plaintext.466540 467-For a locked diagram, keep the page open and save the diagram explicitly. A468-locked draft is persisted only after a successful save. If the page closes469-before that save, the browser may not be able to restore the draft.541+For a locked diagram, keep the page open and publish the diagram explicitly. A542+locked draft is persisted only after a successful publish. If the page closes543+before that publish, the browser may not be able to restore the draft.470544 471545 ## Embeds472546 @@ -474,19 +548,23 @@ Locked diagrams cannot use public SVG or Markdown embeds. An embed has no safe
474548 way to ask for the password. Open the diagram in diagram.zip to enter the475549 password and view it.476550 551+An editable SVG imported from a file, pasted text, or a URL creates a local552+draft after validation. The importer rejects ordinary, ambiguous, unsupported,553+or lossy SVG and limits input to 5 MiB.554+477555 ---478556 479557 ---480558 id: working-and-saved-state481-title: Working state and saved state482-description: Understand editor drafts, saved revisions, and persistent diagram data.559+title: Working state and published state560+description: Understand editor drafts, published revisions, and persistent diagram data.483561 sidebar_position: 3484562 ---485563 486-# Working state and saved state564+# Working state and published state487565 488-The editor has a working state and a saved state. They can be different until489-you save.566+The editor has a working state and a published state. They can be different567+until you publish.490568 491569 ## Working state492570 @@ -497,42 +575,53 @@ Source and Details use separate editor tabs. Details is a JSON document that
497575 contains the title, description, and presentation settings.498576 499577 Invalid Details JSON remains in the local draft. The editor keeps the last500-valid preview and blocks save, share, privacy, and type changes until it is valid.578+valid preview and blocks file export, publishing, sharing, privacy, and type579+changes until it is valid.501580 502-When you edit a saved diagram, the working state changes first. The saved503-diagram does not change until you choose **Save**.581+When you edit a published diagram, the working state changes first. The582+published diagram does not change until you choose **Publish**.504583 505584 For an open diagram, diagram.zip stores the working state as a local browser506-draft. This draft supports recovery on the same browser. It is not a saved585+draft. This draft supports recovery on the same browser. It is not a published507586 diagram and other people cannot read it.508587 588+Anonymous drafts default to local work. **Save as File** exports the working589+state as an editable enriched SVG. The file remains useful as a visible SVG590+image and contains a versioned Diagram.zip document for later import.591+592+Importing an editable SVG creates a local draft. The input can come from a593+file, drag and drop, pasted SVG text, or an HTTP(S) or data URL. The importer594+rejects ordinary, ambiguous, unsupported, or lossy SVG instead of guessing.595+Imported input has a 5 MiB limit.596+509597 An edited anonymous example shows a reset icon. Reset removes its local draft510598 and restores the bundled example after confirmation.511599 512-When a saved link opens with a different local draft, the editor marks that513-draft as a device-only overlay. Choose **Restore saved** to discard the overlay514-and return to the alias revision, or **Make a copy** to preserve it under a new515-alias. Neither action silently changes the original share link.600+When a published link opens with a different local draft, the editor marks601+that draft as a device-only overlay. Choose **Restore published** to discard602+the overlay and return to the alias revision, or **Make a copy** to preserve it603+under a new alias. Neither action silently changes the original share link.516604 517605 For a locked diagram, the editor does not store the working state as plaintext518-in browser storage. Save a locked diagram explicitly to persist it.606+in browser storage. Publish a locked diagram explicitly to persist it.519607 520-Zoom and pan are preview session state, not saved diagram state. Appearance608+Zoom and pan are preview session state, not published diagram state. Appearance521609 changes and Edit or Preview tab switches preserve the current view position.522610 523-## Saved state611+## Published state524612 525-The saved state is the last version that you saved successfully. It has an526-alias, a revision, and a stable read link.613+The published state is the last version that you published successfully. It614+has an alias, a revision, and a stable read link.527615 528-The Share dialog uses the saved state. If the working state has changes, the529-dialog tells you to save before you share. This prevents you from sharing an530-older version by mistake.616+The Share dialog uses the published state. If the working state has changes,617+the dialog tells you to publish before you share. This prevents you from618+sharing an older version by mistake.531619 532620 ## Persistent data533621 534-After a successful save, diagram.zip persists the diagram content and its535-metadata. It can also persist SVG and PNG renders for that saved revision.622+After a successful Publish or Encrypt & Publish, diagram.zip persists the623+diagram content and its metadata. It can also persist SVG and PNG renders for624+that published revision.536625 537626 Open content is stored as readable diagram data. Locked content and locked538627 renders are stored as encrypted data. See [Password encryption](/collaboration/encryption/)@@ -541,28 +630,28 @@ for the locked diagram rules.
541630 The persisted data belongs to the alias and its current revision. A local draft542631 does not replace the persisted data.543632 544-## Save flow633+## Publish flow545634 546635 The normal flow is:547636 548637 1. Edit the working state.549-2. Choose **Save**.638+2. Choose **Publish** or **Encrypt & Publish**.550639 3. diagram.zip stores a new revision.551-4. The saved state becomes the working state.640+4. The published state becomes the working state.552641 553-Saving a new diagram creates an alias and an edit capability. Saving an open554-diagram with an edit capability updates its alias. Saving a read-only diagram555-creates a new alias instead.642+Publishing a new diagram creates an alias and an edit capability. Publishing643+an open diagram with an edit capability updates its alias. Publishing a644+read-only diagram creates a new alias instead.556645 557646 ## Conflicts558647 559-The editor saves against the revision that it last loaded. If that revision is560-no longer current, another person saved the alias first.648+The editor publishes against the revision that it last loaded. If that revision649+is no longer current, another person published the alias first.561650 562-The editor then offers **Reload saved** or **Save as new**. Reload replaces the563-working state with the current saved state. Save as new preserves the working564-state in a new alias. diagram.zip does not silently overwrite the other565-person's saved version.651+The editor then offers **Reload published** or **Publish as new**. Reload652+replaces the working state with the current published state. Publish as new653+preserves the working state in a new alias. diagram.zip does not silently654+overwrite the other person's published version.566655 567656 ---568657 @@ -98,11 +98,12 @@
9898 ## General pages9999 100100 - [Editor workspace](https://docs.diagram.zip/create/)101+- [Editable SVG files and local drafts](https://docs.diagram.zip/create/): Reopen validated enriched SVG files without publishing.101102 - [Details JSON and presentation](https://docs.diagram.zip/style/presentation/)102103 - [SVG normalization and version contracts](https://docs.diagram.zip/style/svg-normalization/)103104 - [Share a diagram](https://docs.diagram.zip/collaboration/sharing/)104105 - [Password encryption](https://docs.diagram.zip/collaboration/encryption/)105-- [Working state and saved state](https://docs.diagram.zip/collaboration/working-and-saved-state/)106+- [Working state and published state](https://docs.diagram.zip/collaboration/working-and-saved-state/)106107 107108 ## Structured catalogs108109 @@ -19,6 +19,13 @@ Use this model-invokable skill after a diagram is drafted, when a user asks whet
1919 6. Check renderer fidelity and export. Name unsupported standard constructs, layout controls, or interchange data rather than silently approximating them.2020 7. Return prioritized fixes: blocking semantic errors, reader-confusing issues, then polish. Include a concise corrected story or source fragment when useful.2121 22+For an enriched SVG, also check source provenance, metadata schema, and23+deterministic round-trip behavior. Confirm that the visible SVG remains useful24+as an image and that the embedded document restores the same type, source,25+options, presentation, title, and description. Reject ordinary, ambiguous,26+unsupported, or lossy SVG instead of treating its shapes as authoritative27+source. Check the 5 MiB import limit and warn that file exports are plaintext.28+2229 ## Styling and customization2330 2431 Prefer styles that reinforce meaning: consistent shape roles, restrained color, explicit boundaries, and labels that survive grayscale or color-vision differences. Keep bespoke styling local and documented. Do not let a theme override a formal symbol's meaning or make decorative elements look like data.@@ -34,6 +34,16 @@ Do not infer standards support from a similarly named renderer mode. Confirm the
3434 3535 Keep renderer notation in Source. Use Details only for the title, description, and presentation settings. Follow the [presentation guide](https://docs.diagram.zip/style/presentation/) for the current JSON shape.3636 37+When a user provides an enriched SVG, treat it as a candidate source artifact.38+Validate and reopen it before choosing a renderer or rewriting its source.39+Preserve the embedded type, source, options, presentation, title, and40+description when the contract supports them. Reject ordinary, ambiguous,41+unsupported, or lossy SVG rather than reconstructing source from visible shapes.42+43+Anonymous drafts default to local work. Recommend **Save as File** for a44+portable editable SVG. Recommend **Publish** or **Encrypt & Publish** only when45+the user wants server persistence or a share alias.46+3747 ## Prior art and standards3848 3949 Use the [OMG UML specification](https://www.omg.org/spec/UML), [OMG BPMN specification](https://www.omg.org/spec/BPMN/2.0.2/), [C4 notation](https://c4model.com/diagrams/notation), and other authoritative references linked by the selected semantic skill when formal conformance matters. Treat these as guidance for meaning and notation, not as permission to invent unsupported renderer features.@@ -6,7 +6,9 @@ coverage. Production deployment uses the repository release workflow.
66 77 ## Product contract88 9-diagram.zip does not require accounts. Possession is the access model:9+diagram.zip does not require accounts. Drafts remain local until the user10+chooses Publish or Encrypt & Publish. Save as File exports an editable enriched11+SVG without creating an alias. Possession is the access model for aliases:1012 1113 | Diagram | Read | Write |1214 | --- | --- | --- |@@ -17,6 +19,12 @@ There are no owners, users, sessions, ACLs, or recovery flows. Losing a write
1719 capability means losing the ability to update that alias. Losing a password1820 means losing the ability to decrypt a locked diagram.1921 22+Editable SVG files remain visible images and carry a versioned Diagram.zip23+document in metadata and `data-*` attributes. The importer accepts local files,24+drag and drop, pasted SVG, and HTTP(S) or data URLs. It rejects ordinary,25+ambiguous, unsupported, or lossy SVG instead of guessing, and limits input to26+5 MiB. File exports are plaintext and are not encrypted backups.27+2028 Read links are short and stable:2129 2230 ```text@@ -79,8 +87,8 @@ render-heads/locked/{render_id}.{svg|png}.json
7987 Each small render-head manifest records the owning unit, exact build, explicit8088 translation pipeline, and immutable object key. R2 object existence is the8189 render-cache source of truth; there is no D1 row per render. Draft previews82-remain transient and use the current renderer. Only an83-explicit alias create or save writes immutable content.90+remain transient and use the current renderer. Only an explicit Publish or91+Encrypt & Publish action writes immutable content and advances an alias.8492 8593 The schema is executable in8694 `services/api/migrations/0001_aliases.sql`. Open content contains `type`,@@ -148,7 +156,7 @@ Orphans can be collected later with a grace period.
148156 149157 ### Durable renders150158 151-After a successful save, the browser stores one canonical safe SVG and, where159+After a successful publish, the browser stores one canonical safe SVG and, where152160 the browser can rasterize it, a PNG:153161 154162 ```http@@ -180,26 +188,29 @@ The API materializes the requested appearance from the canonical R2 object. It
180188 does not store a second SVG. The appearance has its own ETag. Locked renders181189 cannot use this server-side path because the API cannot decrypt their SVG.182190 183-The saved presentation records the selected appearance. The editor places the184-same appearance on stable SVG and Markdown links. `raw` uses the renderer canvas185-controls. A shared appearance ignores those legacy controls and materializes its186-own palette and, for framed appearances, its own canvas.191+The published presentation records the selected appearance. The editor places192+the same appearance on stable SVG and Markdown links. `raw` uses the renderer193+canvas controls. A shared appearance ignores those legacy controls and194+materializes its own palette and, for framed appearances, its own canvas.187195 188196 ## Editor and share UX189197 190198 Open drafts continue to autosave locally and render after the existing debounce.191199 They do not write to D1 or R2. Locked drafts are deliberately not written to192-local storage as plaintext; they persist only when the user explicitly saves.200+local storage as plaintext; they persist only when the user explicitly201+publishes.193202 194203 The left pane separates diagram Source from schema-validated Details JSON.195204 Details owns title, description, and presentation values. Invalid Details text196-remains recoverable while save, share, privacy, and type changes stay blocked.205+remains recoverable while file export, publishing, sharing, privacy, and type206+changes stay blocked.197207 198-- New draft: **Save** creates an alias and changes the browser to its read URL.199-- Writable alias: **Save** updates with the last revision.208+- New draft: **Save as File** downloads an editable SVG and creates no alias.209+- New draft: **Publish** creates an alias and changes the browser to its read URL.210+- Writable alias: **Publish** updates with the last revision.200211 - Anonymous example: the reset icon discards its local draft after confirmation.201-- Read-only alias: edits form a local fork; **Save a copy** creates a new alias.202-- Conflict: offer **Reload saved** or **Save as new**. Never overwrite silently.212+- Read-only alias: edits form a local fork; **Publish a Copy** creates a new alias.213+- Conflict: offer **Reload published** or **Publish as new**. Never overwrite silently.203214 - Share, open: copy read link, copy edit link, SVG link, or Markdown.204215 - Share, locked: copy password-required read link or password-and-capability edit205216 link. SVG and Markdown embeds are visibly disabled with the explanation that@@ -176,6 +176,27 @@ an element, while `data-dz-stroke` controls its boundary or connector. This
176176 keeps arrowheads, unfilled nodes, and line geometry from inheriting the wrong177177 property during materialization.178178 179+## Editable SVG document contract180+181+An editable file materializes the requested appearance, then adds a separate182+versioned Diagram.zip document without changing the visible SVG geometry. The183+root carries `data-dz-document="1"`, and exactly one direct `<metadata>` child184+with `data-dz-kind="document"` and `data-dz-schema="1"` contains canonical185+JSON. That JSON preserves the diagram type, source, options, presentation,186+title, and description.187+188+This contract deliberately uses SVG 2 `data-*` attributes for element and root189+bindings. Application data that does not belong to one element lives in190+`<metadata>`. It does not depend on a foreign XML namespace whose behavior191+would differ when the same SVG is parsed as inline HTML.192+193+Serialization is deterministic. Keys are sorted, and no timestamp or random194+value is added. The same canonical render and normalized state produce the same195+bytes. Import requires the supported marker, exactly one supported document, a196+known diagram type, complete state, and a bounded 5 MiB input.197+Ordinary, ambiguous, unsupported, or lossy SVG is rejected rather than reverse198+engineered from its visible shapes.199+179200 ## Current profile coverage180201 181202 The shared sanitizer, canonical serializer, and appearance materializer apply@@ -19,6 +19,13 @@ Use this model-invokable skill after a diagram is drafted, when a user asks whet
1919 6. Check renderer fidelity and export. Name unsupported standard constructs, layout controls, or interchange data rather than silently approximating them.2020 7. Return prioritized fixes: blocking semantic errors, reader-confusing issues, then polish. Include a concise corrected story or source fragment when useful.2121 22+For an enriched SVG, also check source provenance, metadata schema, and23+deterministic round-trip behavior. Confirm that the visible SVG remains useful24+as an image and that the embedded document restores the same type, source,25+options, presentation, title, and description. Reject ordinary, ambiguous,26+unsupported, or lossy SVG instead of treating its shapes as authoritative27+source. Check the 5 MiB import limit and warn that file exports are plaintext.28+2229 ## Styling and customization2330 2431 Prefer styles that reinforce meaning: consistent shape roles, restrained color, explicit boundaries, and labels that survive grayscale or color-vision differences. Keep bespoke styling local and documented. Do not let a theme override a formal symbol's meaning or make decorative elements look like data.@@ -34,6 +34,16 @@ Do not infer standards support from a similarly named renderer mode. Confirm the
3434 3535 Keep renderer notation in Source. Use Details only for the title, description, and presentation settings. Follow the [presentation guide](https://docs.diagram.zip/style/presentation/) for the current JSON shape.3636 37+When a user provides an enriched SVG, treat it as a candidate source artifact.38+Validate and reopen it before choosing a renderer or rewriting its source.39+Preserve the embedded type, source, options, presentation, title, and40+description when the contract supports them. Reject ordinary, ambiguous,41+unsupported, or lossy SVG rather than reconstructing source from visible shapes.42+43+Anonymous drafts default to local work. Recommend **Save as File** for a44+portable editable SVG. Recommend **Publish** or **Encrypt & Publish** only when45+the user wants server persistence or a share alias.46+3747 ## Prior art and standards3848 3949 Use the [OMG UML specification](https://www.omg.org/spec/UML), [OMG BPMN specification](https://www.omg.org/spec/BPMN/2.0.2/), [C4 notation](https://c4model.com/diagrams/notation), and other authoritative references linked by the selected semantic skill when formal conformance matters. Treat these as guidance for meaning and notation, not as permission to invent unsupported renderer features.