xdrs-core 0.46.0 → 0.46.1

package/.xdrs/_core/adrs/principles/020-media-and-asset-standards.md

@@ -15,7 +15,7 @@ Question: What is the canonical preference order for representing visual informa
 
 ## Decision Outcome
 
-**Markdown-first preference order, with centralized asset placement rules**
+**Markdown-first preference order: Markdown → ASCII → Mermaid → draw.io → SVG → PNG**
 
 All diagram format preferences and non-Markdown asset rules are defined here as individually citable rule blocks. Individual document-type policies and skills reference this policy instead of repeating these rules.
 
@@ -31,15 +31,21 @@ ASCII art MAY be used for very simple spatial layouts or shapes where plain Mark
 Mermaid.js SHOULD be used for diagrams that require explicit visual representation: flows, sequences, state machines, entity relationships, class diagrams, and activity diagrams. Mermaid is preferred over draw.io when it can adequately express the needed diagram.
 
 #### 04-drawio-when-mermaid-insufficient
-draw.io SHOULD be used when Mermaid cannot adequately express the needed diagram — for example, custom visual layouts, freehand annotations, or combined view types that Mermaid does not support natively.
+draw.io SHOULD be used when Mermaid cannot adequately express the needed diagram — for example, custom visual layouts, freehand annotations, or combined view types that Mermaid does not support natively. draw.io diagrams MUST be saved as `.drawio` files in the sibling `.assets/` folder and referenced directly from the Markdown document.
 
-#### 05-drawio-storage
-draw.io diagrams MUST be saved as editable vector: File → Save As → Editable Vector. The resulting `.svg` file MUST be stored in the sibling `.assets/` folder. This embeds the draw.io source in the SVG so the diagram remains editable without a separate `.drawio` file.
+#### 05-svg-for-custom-vector
+Plain SVG MAY be used instead of draw.io when greater visual freedom is needed than draw.io provides, or when the diagram originates from tooling other than draw.io. SVG files MUST be stored in the sibling `.assets/` folder.
 
-#### 06-assets-materially-necessary
+#### 06-png-as-last-resort
+PNG (or other raster formats) MAY be used only when no vector or text-based format can adequately represent the content — for example, screenshots or photographs. PNG files MUST be stored in the sibling `.assets/` folder.
+
+#### 07-assets-no-policy-content
+Asset files MUST NOT contain policy content. Diagrams and images do not carry mandatory or advisory language — they cannot express MUST, SHOULD, or MAY obligations with the precision that prose requires. Assets MAY be used only to support the understanding of policy already stated in Markdown text; a visual that merely illustrates what the prose already says is acceptable, but any rule or constraint that exists only inside an asset file is invisible to policy and has no normative force. When in doubt, keep the content in Markdown.
+
+#### 08-assets-materially-necessary
 Non-Markdown files (images, diagrams, schemas, JSON examples, binaries, or any other data files) SHOULD be referenced only when they are materially necessary to preserve clarity, fidelity, or evidence. Assets that duplicate information already expressible in Markdown SHOULD NOT be added.
 
-#### 07-assets-placement
+#### 09-assets-placement
 Non-Markdown files MUST live in the sibling `.assets/` folder next to the referencing document. The canonical per-document-type `.assets/` paths are defined in `_core-adr-policy-001`.
 
 ## References

package/.xdrs/_core/adrs/principles/skills/001-review/SKILL.md

@@ -107,4 +107,5 @@ Scope: [scope identifier]
 - [_core-adr-policy-001 - XDRS standards](../../001-xdrs-standards.md)
 - [_core-adr-policy-002 - Policy standards](../../002-policy-standards.md)
 - [_core-adr-policy-003 - Skill standards](../../003-skill-standards.md)
+- [_core-adr-policy-020 - Media and asset standards](../../020-media-and-asset-standards.md)
 

package/.xdrs/_core/adrs/principles/skills/007-write-presentation/SKILL.md

@@ -44,9 +44,7 @@ Identify the target scope from the parent document's path or the user's request;
    - **Problem**: what needs to be decided, addressed, or understood
    - **Solution/Decision**: what was decided and why
    - **Actions/Next Steps**: what happens now, who is responsible
-3. For each slide, identify the best format:
-   - Mermaid diagrams for flows, relationships, architecture; draw.io `.svg` files saved as Editable Vector (File → Save As → Editable Vector, stored in `.assets/`) when Mermaid is not sufficient
-   - ASCII art for very simple spatial layouts where Markdown is insufficient (see `_core-adr-policy-020`)
+3. For each slide, identify the best format. For diagrams and non-Markdown assets, follow `_core-adr-policy-020`: prefer plain Markdown tables/lists first, then ASCII art for very simple cases, then Mermaid.js (sequence, state, activity, entity diagrams) for complex ones, then draw.io when Mermaid is insufficient — save as Editable Vector (File → Save As → Editable Vector) and store as `.svg` in the sibling `.assets/` folder. For slide content more broadly:
    - Short bullet points for key decisions and trade-offs
    - Tables for comparisons, options, criteria
    - Key short statements for emphasis
@@ -167,3 +165,4 @@ Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.asset
 - [_core-adr-policy-001 - XDRS standards](../../001-xdrs-standards.md)
 - [_core-adr-policy-004 - Article standards](../../004-article-standards.md)
 - [_core-adr-policy-003 - Skill standards](../../003-skill-standards.md)
+- [_core-adr-policy-020 - Media and asset standards](../../020-media-and-asset-standards.md)

package/.xdrs/_core/index.md

@@ -45,6 +45,10 @@ Each artifact type has its own writing standard:
 
 Slide presentations that support XDRS documents follow [_core-adr-policy-009](adrs/principles/009-presentation-standards.md). Slides use the Marp Markdown format, live in `.assets/` next to the document they support, and must maintain bidirectional links with the parent document.
 
+### Media and asset standards
+
+[_core-adr-policy-020](adrs/principles/020-media-and-asset-standards.md) defines the canonical preference order for representing visual information across all XDRS document types: Markdown → ASCII → Mermaid → draw.io → SVG → PNG. It also defines where non-Markdown files must be stored (`.assets/` sibling folder) and prohibits policy content from living inside asset files. All document-type policies and write-* skills reference this policy instead of repeating these rules independently.
+
 ### Standard scope meta governance
 
 [_core-adr-policy-010](adrs/principles/010-scope-governance.md) defines the full scope governance model: how to define a custom scope type using `{scope-type}-scope-type` policies, how to define scope-local content standards using local meta-policies (`NNN-core.md` or `NNN-core-{qualifier}.md` in `principles/`), and how all governance mechanisms (`follows:`, scope-type standards, local meta-policies) apply with their precedence chain.

package/README.md

@@ -12,6 +12,10 @@ Policies capture Architectural (ADR), Business (BDR), and Engineering (EDR) deci
 
 This project defines a standard for organizing XDRS that satisfies the following requirements.
 
+## Overview
+
+![XDRS Overview Diagram](.xdrs/_core/adrs/principles/articles/.assets/001-xdrs-overview.svg)
+
 ## XDRS elements
 
 A traditional Decision Record normally combines several concerns in the same document:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.46.0",
+  "version": "0.46.1",
   "description": "A framework to structure, compile and distribute Architectural (ADR), Business (BDR), and Engineering (EDR) decision records contents so that AI agents and humans can reliably find and use them with hierarchical scopes and controlled rollout in the format of distributable versioned packages.",
   "repository": {
     "type": "git",