xdrs-core 0.45.0 → 0.46.1

package/.xdrs/_core/adrs/index.md

@@ -25,6 +25,7 @@ Foundational standards, principles, and guidelines.
 - [_core-adr-policy-017](principles/017-policy-numbering-ranges.md) - **Policy numbering ranges** — Subject-based 100-number block ranges for policy numbering and the freeze-reference exemption
 - [_core-adr-policy-018](principles/018-external-path-symlinks.md) - **External path symlinks** — How to make XDRS files accessible from paths outside the .xdrs/ root using symlinks
 - [_core-adr-policy-019](principles/019-compiled-scope-type.md) - **compiled scope type** — Defines the `compiled` scope type: scopes whose policies are compiled from external authoritative sources with strict source traceability and no invented content
+- [_core-adr-policy-020](principles/020-media-and-asset-standards.md) - **Media and asset standards** — Canonical diagram format preference order and non-Markdown asset rules for all XDRS document types
 
 ## Skills
 

package/.xdrs/_core/adrs/principles/001-xdrs-standards.md

@@ -62,11 +62,11 @@ ADR and EDR share the same six technical subject names (see [`_core-adr-policy-0
   - `_core-adr-policy-004` defines article standards
   - `_core-adr-policy-006` defines research standards
   - `_core-adr-policy-007` defines plan standards
-- For simple structures, flows, layout, or relationship indications, documents SHOULD prefer plain Markdown, tables, Mermaid.js (sequence, state, activity, entity diagrams) or ASCII art instead of external assets.
-- Any non-Markdown supporting files referenced by a document (schemas, JSON examples, images, diagrams, binaries, or any other data files) SHOULD be used only when they are materially necessary to preserve clarity, fidelity, or evidence. When used, they MUST live in a sibling `.assets/` folder next to the document.
+- For diagram format preferences and non-Markdown asset rules, see [`_core-adr-policy-020`](020-media-and-asset-standards.md). **Per-document-type `.assets/` paths:**
   - Policies in the subject root use `[xdrs-root]/[scope]/[type]/[subject]/.assets/`
   - Articles use `[xdrs-root]/[scope]/[type]/[subject]/articles/.assets/`
   - Research uses `[xdrs-root]/[scope]/[type]/[subject]/researches/.assets/`
+  - Plans use `[xdrs-root]/[scope]/[type]/[subject]/plans/.assets/`
   - Skills use `[xdrs-root]/[scope]/[type]/[subject]/skills/[number]-[skill-name]/.assets/`
 - **Scopes:** 
   - Short name that defines a group or a package of XDRS
@@ -152,3 +152,4 @@ subject/
 - [_core-adr-policy-004 - Article standards](004-article-standards.md)
 - [_core-adr-policy-006 - Research standards](006-research-standards.md)
 - [_core-adr-policy-007 - Plan standards](007-plan-standards.md)
+- [_core-adr-policy-020 - Media and asset standards](020-media-and-asset-standards.md) - Diagram format preferences and non-Markdown asset rules

package/.xdrs/_core/adrs/principles/002-policy-standards.md

@@ -81,7 +81,7 @@ Policy documents are the authoritative source of truth for their scope, type, an
 - When research exists for a decision, the Policy SHOULD mention the related research documents after the `## Considered Options` list.
 - MUST NOT use emojis in contents.
 - File names MUST be lowercase.
-- Any non-Markdown files referenced by a Policy (schemas, JSON examples, images, diagrams, binaries, or any other data files) SHOULD be used only when they are materially necessary and MUST live in `[xdrs-root]/[scope]/[type]/[subject]/.assets/`.
+- For diagram format preferences and non-Markdown asset rules, see [`_core-adr-policy-020`](020-media-and-asset-standards.md).
 - Avoid using lengthy instructions on the Policy. If there are long and detailed instructions related to the Policy, or instructions that are outside the decision, create another file with a guide. If the guide is small, keep it in the Policy itself.
 - Policies SHOULD be under 1300 words long as a rule of thumb.
   - This is important to make them focused on a clear decision

package/.xdrs/_core/adrs/principles/003-skill-standards.md

@@ -116,8 +116,7 @@ Rules:
 - The directory name MUST follow the format `[number]-[skill-name]` (e.g., `001-code-review`), matching the `name:` field.
 - `## Overview` SHOULD state the task objective, expected outcome, and relevant prerequisites or tools when they matter.
 - `## Instructions` SHOULD include verification steps or acceptance criteria at the end of the task, or at the end of major phases when partial validation matters.
-- For simple structure, flow, layout, or relationship indications, `SKILL.md` SHOULD prefer plain Markdown, tables, or ASCII art instead of external assets.
-- Any non-Markdown files referenced from `SKILL.md` SHOULD be used only when they are materially necessary and MUST live in `.assets/` inside the same skill package. See `_core-adr-policy-001` for the canonical `.assets/` path conventions.
+- For diagram format preferences and non-Markdown asset rules, see [`_core-adr-policy-020`](020-media-and-asset-standards.md).
 - Keep `SKILL.md` under 6500 words. Move lengthy reference material to `references/`.
 - Use relative paths for all links; MUST NOT use absolute paths starting with `/`.
 - File names MUST be lowercase.

package/.xdrs/_core/adrs/principles/004-article-standards.md

@@ -38,8 +38,7 @@ Articles are Markdown documents placed inside a subject folder alongside policie
 - When an article tells readers which decisions to follow, it SHOULD check `valid-from:` first to determine the convergence date, `apply-to:` second to determine context fit, and the decision text itself last. All documents present in the collection are considered active; articles MUST NOT present out-of-window or out-of-scope Policies as current rules for the discussed context.
 - Articles MUST remain consistent with the Policies, Research documents, and Skills they reference. When a referenced artifact changes, the article MUST be reviewed and updated.
 - Place an article in the subject folder that best matches its topic using the required list of subjects per type defined in `_core-adr-policy-001`. If an article spans more than one subject, place it in `principles`.
-- For simple structure, flow, layout, or relationship indications, articles SHOULD prefer plain Markdown, tables, or ASCII art instead of external assets.
-- Any non-Markdown files referenced by an article SHOULD be used only when they are materially necessary and MUST live in `articles/.assets/` next to the article files. See `_core-adr-policy-001` for the canonical `.assets/` path conventions.
+- For diagram format preferences and non-Markdown asset rules, see [`_core-adr-policy-020`](020-media-and-asset-standards.md). Articles SHOULD use diagrams to illustrate concepts, overviews, and relationships; draw.io SHOULD be used for conceptual and relationship diagrams (e.g., component maps, context views, architecture overviews) when Mermaid cannot adequately express them.
 - File names MUST be lowercase.
 - MUST NOT use emojis in article content.
 

package/.xdrs/_core/adrs/principles/006-research-standards.md

@@ -37,9 +37,9 @@ Research documents are Markdown files placed inside a subject folder alongside p
 - Research documents MUST describe the methods, tools, sources, and conditions with enough detail that an experienced professional could at least minimally reproduce the important parts of the study, especially the aspects that materially affected the conclusion.
 - The short title portion after the research id MUST stay under 20 words.
 - `## Abstract` MUST be a single paragraph under 200 words summarizing the goal, methods, results, and conclusion. It SHOULD let a quick technical reader understand the question, method, main result, and takeaway.
-- `## Introduction` MUST define the problem, context, constraints, known facts, experiences, gaps, assumptions, and objectives. It SHOULD prefer plain Markdown, bullet points, tables, or ASCII art for simple explanations, and SHOULD use external visuals only when they are materially necessary to improve understanding. It MUST stay under 700 words and MUST end with `Question: [central question]?`.
+- `## Introduction` MUST define the problem, context, constraints, known facts, experiences, gaps, assumptions, and objectives. It SHOULD prefer plain Markdown, bullet points, and tables for simple explanations, and SHOULD use diagrams to illustrate concepts and relationships when they improve clarity over plain text (see [`_core-adr-policy-020`](020-media-and-asset-standards.md) for format preference; draw.io SHOULD be used for conceptual and relationship diagrams such as context maps, component relationships, and architecture overviews). It MUST stay under 700 words and MUST end with `Question: [central question]?`.
 - `## Methods` MUST explain how the study was conducted, including design, tools, data sources, and test conditions, with a reproducibility goal. It MUST stay under 1200 words.
-- `## Results` MUST present findings, data, trends, quantitative results, produced code, and option comparisons when relevant. It SHOULD prefer tables, bullet lists, or ASCII art for simple comparisons, and SHOULD use external figures only when they are materially necessary. Keep interpretation to a minimum. It MUST stay under 1800 words.
+- `## Results` MUST present findings, data, trends, quantitative results, produced code, and option comparisons when relevant. It SHOULD prefer tables and bullet lists for simple comparisons, and SHOULD use diagrams to illustrate concepts and relationships when they improve clarity over plain text (see [`_core-adr-policy-020`](020-media-and-asset-standards.md) for format preference; draw.io SHOULD be used for conceptual and relationship diagrams). Keep interpretation to a minimum. It MUST stay under 1800 words.
 - When different options for the same problem are being analyzed, `## Results` SHOULD include comparison tables and explicit pros and cons for each option so the trade-offs are directly inspectable.
 - `## Discussion` MUST interpret the results, explain significance, trade-offs, performance considerations, limitations, and implications for technical readers. It MUST stay under 1000 words.
 - `## Conclusion` MUST summarize the main findings, practical takeaway, applicability boundaries, and important open questions. It MUST stay under 400 words.
@@ -50,7 +50,7 @@ Research documents are Markdown files placed inside a subject folder alongside p
 - Research documents SHOULD link in `## References` to the Policies, skills, articles, discussions, and external references relevant to the subject or that later cite the work.
 - A 1:1 relationship between one research document and one decision will likely be common in practice, but it is not REQUIRED.
 - One research document MAY also be referenced by multiple Policies, including a mix of ADRs, BDRs, and EDRs, when the same investigation remains relevant across several decisions.
-- Any non-Markdown files referenced by a research document SHOULD be used only when they are materially necessary and MUST live in `researches/.assets/` next to the research files. See `_core-adr-policy-001` for the canonical `.assets/` path conventions.
+- For diagram format preferences and non-Markdown asset rules, see [`_core-adr-policy-020`](020-media-and-asset-standards.md). Research documents SHOULD use diagrams to illustrate concepts and relationships; draw.io SHOULD be used for conceptual and relationship diagrams (e.g., context maps, component relationships, architecture overviews) when Mermaid cannot adequately express them.
 - Research file names MUST be lowercase. MUST NOT use emojis.
 - A research document MAY exist before the related Policy is written, or remain after the Policy changes, as long as its status and references stay clear.
 
@@ -91,7 +91,7 @@ All research documents MUST follow this template:
 ## Introduction
 
 [Describe the problem, context, constraints, known facts, experiences, gaps, assumptions, and objectives.
-Prefer bullets, tables, or ASCII art for simple explanations. Use external visuals only when they are materially necessary. Goal: explain the investigated problem, operating context, constraints, and why the subject matters. Under 700 words.]
+Prefer markdown structures (bullets, tables, headings) first; for diagrams see _core-adr-policy-020. Goal: explain the investigated problem, operating context, constraints, and why the subject matters. Under 700 words.]
 
 Question: [Central question of the research]?
 
@@ -103,7 +103,7 @@ Include enough detail for an experienced professional to reproduce the relevant
 ## Results
 
 [Report findings, data, trends, quantitative results, code artifacts, and option comparisons.
-Prefer tables, bullets, or ASCII art for simple comparisons. Use external figures only when they are materially necessary. If multiple options solve the same problem, add comparison tables and explicit pros and cons for each option. Focus on raw findings, not interpretation. Goal: present the raw findings with minimal interpretation. Under 1800 words.]
+Prefer tables and bullet lists for simple comparisons; for diagrams see _core-adr-policy-020. If multiple options solve the same problem, add comparison tables and explicit pros and cons for each option. Focus on raw findings, not interpretation. Goal: present the raw findings with minimal interpretation. Under 1800 words.]
 
 ## Discussion
 
@@ -135,4 +135,5 @@ Prefer tables, bullets, or ASCII art for simple comparisons. Use external figure
 - [_core-adr-policy-001 - XDRS standards](001-xdrs-standards.md)
 - [_core-adr-policy-003 - Skill standards](003-skill-standards.md)
 - [_core-adr-policy-004 - Article standards](004-article-standards.md)
+- [_core-adr-policy-020 - Media and asset standards](020-media-and-asset-standards.md) - Diagram format preferences and non-Markdown asset rules
 - [005-write-research skill](skills/005-write-research/SKILL.md) - Step-by-step instructions for creating a research document

package/.xdrs/_core/adrs/principles/007-plan-standards.md

@@ -33,7 +33,7 @@ Plans are Markdown documents placed inside a subject folder alongside policies.
 - Plans MUST include an `Expected end date:` field in ISO format (YYYY-MM-DD) inside the `## Proposed Solution` section.
 - File names MUST be lowercase.
 - MUST NOT use emojis in plan content.
-- Any non-Markdown files referenced by a plan SHOULD be used only when they are materially necessary and MUST live in `plans/.assets/` next to the plan files. See `_core-adr-policy-001` for the canonical `.assets/` path conventions.
+- For diagram format preferences and non-Markdown asset rules, see [`_core-adr-policy-020`](020-media-and-asset-standards.md).
 
 **Folder layout**
 

package/.xdrs/_core/adrs/principles/009-presentation-standards.md

@@ -36,7 +36,7 @@ Presentations are Markdown files in Marp format, stored in the `.assets/` folder
 - Slide file names MUST NOT exceed 64 characters (including the `.md` extension).
 - Slide file names MUST be lowercase.
 - When slides refer to content from multiple decisions, plans, or research documents, an article explaining the combined view MUST be written first. The slides then support that article, not the individual documents directly.
-- Slides SHOULD contain minimal text. Prefer Mermaid diagrams, short bullet points, ASCII art, key short statements, and tables. Use longer text only when the exact wording MUST be evaluated by the audience (policies, texts under discussion, controls).
+- Slides SHOULD contain minimal text. For diagrams, prefer ASCII art for very simple cases, Mermaid for flows and relationships, and draw.io when Mermaid is insufficient (see [`_core-adr-policy-020`](020-media-and-asset-standards.md)); for other slide content, prefer short bullet points, key short statements, and tables. Use longer text only when the exact wording MUST be evaluated by the audience (policies, texts under discussion, controls).
 - Slides SHOULD follow a clean, linear storytelling structure (context, problem, solution, actions). Follow the structure of the underlying document, extracting the most important points and stressing central questions, answers, doubts, decisions, and risks.
 - Define the central message or objective of the presentation before creating the slides. If the objective is unclear or there are multiple possible paths, ask the user before proceeding.
 - The target audience MUST be identified (executives, engineers, specialists, control). If the audience is not clear from the underlying document, ask before creating the slides. Include audience info in the file name when multiple audiences exist (e.g. `005-rail-standards-slides-executive.md`).
@@ -51,4 +51,5 @@ Presentations are Markdown files in Marp format, stored in the `.assets/` folder
 - [_core-adr-policy-002 - Policy standards](002-policy-standards.md) - Policy document writing rules
 - [_core-adr-policy-004 - Article standards](004-article-standards.md) - Article standards for multi-document views
 - [007-write-presentation skill](skills/007-write-presentation/SKILL.md) - Skill for creating slide presentations
+- [_core-adr-policy-020 - Media and asset standards](020-media-and-asset-standards.md) - Diagram format preferences and non-Markdown asset rules
 - [Marp](https://marp.app/) - Markdown Presentation Ecosystem

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

@@ -0,0 +1,54 @@
+---
+name: _core-adr-policy-020-media-and-asset-standards
+description: Defines the preferred order for representing visual information and the rules for non-Markdown assets across all XDRS document types. Use when choosing a diagram format or referencing any non-Markdown file in any XDRS document.
+apply-to: All XDRS document types
+valid-from: 2026-08-06
+---
+
+# _core-adr-policy-020: Media and asset standards
+
+## Context and Problem Statement
+
+Rules for diagram format preference and non-Markdown asset handling are scattered across multiple policies (001, 002, 003, 004, 006, 007) and all write-\* skills. The same asset placement and diagram preference rules appear independently in each document-type policy, creating duplication that `_core-adr-policy-002` itself prohibits, and inconsistency when the rules diverge.
+
+Question: What is the canonical preference order for representing visual information in XDRS documents, and where must non-Markdown files be stored?
+
+## Decision Outcome
+
+**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.
+
+### Details
+
+#### 01-prefer-markdown
+Markdown structures MUST be the first choice for any layout, tabular data, list, heading hierarchy, or simple relationship that can be expressed adequately as plain text. Plain Markdown tables, bullet lists, headings, and code blocks MUST be used before reaching for any external visual format.
+
+#### 02-ascii-for-simple
+ASCII art MAY be used for very simple spatial layouts or shapes where plain Markdown structures cannot adequately convey the diagram. ASCII art SHOULD be limited to cases that are trivial to write and maintain as plain text; anything requiring visual complexity SHOULD use Mermaid instead.
+
+#### 03-mermaid-for-complex
+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 diagrams MUST be saved as `.drawio` files in the sibling `.assets/` folder and referenced directly from the Markdown document.
+
+#### 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-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.
+
+#### 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
+
+- [_core-adr-policy-001 - XDRS standards](001-xdrs-standards.md) - Per-document-type `.assets/` canonical paths
+- [_core-adr-policy-008 - Policy structured standards](008-policy-structured-standards.md) - Structured rule block format used in this policy

package/.xdrs/_core/adrs/principles/articles/.assets/001-xdrs-overview.svg

@@ -0,0 +1,258 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- hand-coded SVG; to make editable in draw.io, import and re-export as Editable Vector -->
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
+     version="1.1" width="1650" height="980" viewBox="0 0 1650 980"
+     style="background-color:#ffffff;">
+  <defs>
+    <marker id="arr-p" viewBox="0 0 10 10" refX="9" refY="5"
+            markerWidth="6" markerHeight="6" orient="auto">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#7c4dff"/>
+    </marker>
+    <marker id="arr-o" viewBox="0 0 10 10" refX="9" refY="5"
+            markerWidth="6" markerHeight="6" orient="auto">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#e67e22"/>
+    </marker>
+  </defs>
+
+  <!-- ===== TITLE ===== -->
+  <text x="825" y="42" text-anchor="middle" font-family="Arial,Helvetica,sans-serif"
+        font-size="24" font-weight="bold" fill="#1a1a2e">XDRS — eXtensible Decision Record System</text>
+  <text x="825" y="66" text-anchor="middle" font-family="Arial,Helvetica,sans-serif"
+        font-size="13" fill="#555">A framework to structure, compile and distribute decision records so that AI agents and humans can reliably find and use them</text>
+
+  <!-- ===== SECTION A: DECISION TYPES ===== -->
+  <rect x="20" y="88" width="260" height="422" rx="8" fill="#f0f4ff" stroke="#4a6cf7" stroke-width="2"/>
+  <text x="150" y="112" text-anchor="middle" font-family="Arial,Helvetica,sans-serif"
+        font-size="14" font-weight="bold" fill="#4a6cf7">Decision Types</text>
+
+  <!-- ADR -->
+  <rect x="34" y="124" width="232" height="72" rx="6" fill="#dae8fc" stroke="#6c8ebf" stroke-width="1.5"/>
+  <text x="150" y="146" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="13" font-weight="bold" fill="#1a1a2e">ADR</text>
+  <text x="150" y="163" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#333">Architectural Decision Records</text>
+  <text x="150" y="179" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#666">app · data · integration · platform · operations</text>
+
+  <!-- BDR -->
+  <rect x="34" y="208" width="232" height="72" rx="6" fill="#d5e8d4" stroke="#82b366" stroke-width="1.5"/>
+  <text x="150" y="230" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="13" font-weight="bold" fill="#1a1a2e">BDR</text>
+  <text x="150" y="247" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#333">Business Decision Records</text>
+  <text x="150" y="263" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#666">product · marketing · finance · organization</text>
+
+  <!-- EDR -->
+  <rect x="34" y="292" width="232" height="72" rx="6" fill="#fff2cc" stroke="#d6b656" stroke-width="1.5"/>
+  <text x="150" y="314" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="13" font-weight="bold" fill="#1a1a2e">EDR</text>
+  <text x="150" y="331" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#333">Engineering Decision Records</text>
+  <text x="150" y="347" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#666">infra · devops · observability · governance</text>
+
+  <!-- Policy ID note inside A -->
+  <rect x="34" y="382" width="232" height="114" rx="6" fill="#fafafa" stroke="#aaa" stroke-width="1" stroke-dasharray="4,3"/>
+  <text x="150" y="401" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="11" font-weight="bold" fill="#555">Policy ID Format</text>
+  <text x="44" y="420" font-family="Courier New,monospace" font-size="11" fill="#333">[scope]-[type]-policy-[number]</text>
+  <text x="44" y="440" font-family="Courier New,monospace" font-size="10" fill="#666">checkout-adr-policy-001</text>
+  <text x="44" y="456" font-family="Courier New,monospace" font-size="10" fill="#666">myorg-edr-policy-042</text>
+  <text x="44" y="472" font-family="Courier New,monospace" font-size="10" fill="#666">_core-adr-policy-016</text>
+  <text x="44" y="488" font-family="Courier New,monospace" font-size="10" fill="#666">        (sequential, never reused)</text>
+
+  <!-- Arrow A → B -->
+  <line x1="281" y1="299" x2="317" y2="299" stroke="#7c4dff" stroke-width="2" marker-end="url(#arr-p)"/>
+  <text x="299" y="291" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#7c4dff">decompose</text>
+  <text x="299" y="313" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#7c4dff">into</text>
+
+  <!-- ===== SECTION B: XDRS ELEMENTS ===== -->
+  <rect x="320" y="88" width="440" height="422" rx="8" fill="#f9f0ff" stroke="#7c4dff" stroke-width="2"/>
+  <text x="540" y="112" text-anchor="middle" font-family="Arial,Helvetica,sans-serif"
+        font-size="14" font-weight="bold" fill="#7c4dff">XDRS Document Elements</text>
+  <text x="540" y="129" text-anchor="middle" font-family="Arial,Helvetica,sans-serif"
+        font-size="11" fill="#888">Each decision record decomposes into specialized document types</text>
+
+  <!-- Policy element -->
+  <rect x="334" y="141" width="412" height="64" rx="6" fill="#e1d5f7" stroke="#7c4dff" stroke-width="1.5"/>
+  <text x="354" y="161" font-family="Arial,Helvetica,sans-serif" font-size="13" font-weight="bold" fill="#1a1a2e">Policy — What must be followed</text>
+  <text x="354" y="178" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">Rules, guardrails, core decisions. The source of truth.</text>
+  <text x="354" y="195" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">Captured as ADR / BDR / EDR policy documents.</text>
+
+  <!-- Research element -->
+  <rect x="334" y="215" width="412" height="64" rx="6" fill="#dae8fc" stroke="#6c8ebf" stroke-width="1.5"/>
+  <text x="354" y="235" font-family="Arial,Helvetica,sans-serif" font-size="13" font-weight="bold" fill="#1a1a2e">Research — Why the decision was made</text>
+  <text x="354" y="252" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">Problem context, constraints, findings, option tradeoffs.</text>
+  <text x="354" y="269" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">One research may inform multiple downstream policies.</text>
+
+  <!-- Skills element -->
+  <rect x="334" y="289" width="412" height="64" rx="6" fill="#d5e8d4" stroke="#82b366" stroke-width="1.5"/>
+  <text x="354" y="309" font-family="Arial,Helvetica,sans-serif" font-size="13" font-weight="bold" fill="#1a1a2e">Skills — How to implement</text>
+  <text x="354" y="326" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">Step-by-step procedural guides for humans or AI agents.</text>
+  <text x="354" y="343" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">Executable with verifiable outcomes.</text>
+
+  <!-- Articles element -->
+  <rect x="334" y="363" width="412" height="64" rx="6" fill="#fff2cc" stroke="#d6b656" stroke-width="1.5"/>
+  <text x="354" y="383" font-family="Arial,Helvetica,sans-serif" font-size="13" font-weight="bold" fill="#1a1a2e">Articles — Overview / Views</text>
+  <text x="354" y="400" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">Synthetic texts combining multiple policies and skills.</text>
+  <text x="354" y="417" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">Never replace policies as source of truth.</text>
+
+  <!-- Plans element -->
+  <rect x="334" y="437" width="412" height="64" rx="6" fill="#f8cecc" stroke="#b85450" stroke-width="1.5"/>
+  <text x="354" y="457" font-family="Arial,Helvetica,sans-serif" font-size="13" font-weight="bold" fill="#1a1a2e">Plans — When / How to roll out</text>
+  <text x="354" y="474" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">Ephemeral execution docs. Deleted after implementation.</text>
+  <text x="354" y="491" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">Lasting outputs become Policies, Skills, or Articles.</text>
+
+  <!-- Arrow B → C -->
+  <line x1="761" y1="299" x2="797" y2="299" stroke="#e67e22" stroke-width="2" marker-end="url(#arr-o)"/>
+  <text x="779" y="291" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#e67e22">organized</text>
+  <text x="779" y="313" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#e67e22">in</text>
+
+  <!-- ===== SECTION C: SCOPE SYSTEM ===== -->
+  <rect x="800" y="88" width="830" height="422" rx="8" fill="#fff8f0" stroke="#e67e22" stroke-width="2"/>
+  <text x="1215" y="112" text-anchor="middle" font-family="Arial,Helvetica,sans-serif"
+        font-size="14" font-weight="bold" fill="#e67e22">Scope System — Hierarchical Namespaces</text>
+  <text x="1215" y="129" text-anchor="middle" font-family="Arial,Helvetica,sans-serif"
+        font-size="11" fill="#888">Scopes organize decision ownership. Scopes listed later in root index.md override earlier ones.</text>
+
+  <!-- Precedence arrow (right side) -->
+  <line x1="1598" y1="480" x2="1598" y2="148" stroke="#e67e22" stroke-width="2" stroke-dasharray="4,3" marker-end="url(#arr-o)"/>
+  <text x="1598" y="314" text-anchor="middle" transform="rotate(-90,1598,314)"
+        font-family="Arial,Helvetica,sans-serif" font-size="11" font-weight="bold" fill="#e67e22">Precedence: later overrides earlier</text>
+
+  <!-- core -->
+  <rect x="814" y="141" width="770" height="58" rx="6" fill="#f8cecc" stroke="#b85450" stroke-width="1.5"/>
+  <text x="834" y="162" font-family="Arial,Helvetica,sans-serif" font-size="13" font-weight="bold" fill="#1a1a2e">core   (e.g. _core, myorg-core)</text>
+  <text x="834" y="179" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">Meta-governance: authoring standards, scope-type definitions. No consumable policies.</text>
+
+  <!-- reference -->
+  <rect x="814" y="209" width="770" height="58" rx="6" fill="#fff2cc" stroke="#d6b656" stroke-width="1.5"/>
+  <text x="834" y="230" font-family="Arial,Helvetica,sans-serif" font-size="13" font-weight="bold" fill="#1a1a2e">reference   (e.g. security-ref-baseline)</text>
+  <text x="834" y="247" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">Standards, regulations, reference models. Read-only adoptable material.</text>
+
+  <!-- platform -->
+  <rect x="814" y="277" width="770" height="58" rx="6" fill="#d5e8d4" stroke="#82b366" stroke-width="1.5"/>
+  <text x="834" y="298" font-family="Arial,Helvetica,sans-serif" font-size="13" font-weight="bold" fill="#1a1a2e">platform   (e.g. cloud-plat-infra)</text>
+  <text x="834" y="315" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">Live services and infrastructure teams can consume. Documents operational capabilities.</text>
+
+  <!-- standard -->
+  <rect x="814" y="345" width="770" height="58" rx="6" fill="#dae8fc" stroke="#6c8ebf" stroke-width="1.5"/>
+  <text x="834" y="366" font-family="Arial,Helvetica,sans-serif" font-size="13" font-weight="bold" fill="#1a1a2e">standard   (e.g. checkout, mobile-app)</text>
+  <text x="834" y="383" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">Business areas, products, teams. General-purpose scopes. Default type.</text>
+
+  <!-- _local -->
+  <rect x="814" y="413" width="770" height="58" rx="6" fill="#e1d5f7" stroke="#7c4dff" stroke-width="1.5"/>
+  <text x="834" y="434" font-family="Arial,Helvetica,sans-serif" font-size="13" font-weight="bold" fill="#1a1a2e">_local   (reserved)</text>
+  <text x="834" y="451" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">Workspace-local overrides. Never distributed. Highest precedence within workspace.</text>
+
+  <!-- ===== SECTION: FILE STRUCTURE ===== -->
+  <rect x="20" y="530" width="390" height="290" rx="8" fill="#f0fff4" stroke="#27ae60" stroke-width="2"/>
+  <text x="215" y="554" text-anchor="middle" font-family="Arial,Helvetica,sans-serif"
+        font-size="14" font-weight="bold" fill="#27ae60">Folder Structure</text>
+  <text x="38" y="578" font-family="Courier New,monospace" font-size="11" fill="#333">.xdrs/</text>
+  <text x="38" y="596" font-family="Courier New,monospace" font-size="11" fill="#333">  index.md              ← root index (lists all scopes)</text>
+  <text x="38" y="614" font-family="Courier New,monospace" font-size="11" fill="#333">  [scope]/</text>
+  <text x="38" y="632" font-family="Courier New,monospace" font-size="11" fill="#333">    index.md            ← scope overview + frontmatter</text>
+  <text x="38" y="650" font-family="Courier New,monospace" font-size="11" fill="#333">    [adrs|bdrs|edrs]/</text>
+  <text x="38" y="668" font-family="Courier New,monospace" font-size="11" fill="#333">      index.md          ← type index</text>
+  <text x="38" y="686" font-family="Courier New,monospace" font-size="11" fill="#333">      [subject]/</text>
+  <text x="38" y="704" font-family="Courier New,monospace" font-size="11" fill="#333">        NNN-title.md    ← Policy</text>
+  <text x="38" y="722" font-family="Courier New,monospace" font-size="11" fill="#333">        researches/     ← Research docs</text>
+  <text x="38" y="740" font-family="Courier New,monospace" font-size="11" fill="#333">        skills/         ← Skill packages</text>
+  <text x="38" y="758" font-family="Courier New,monospace" font-size="11" fill="#333">        articles/       ← Article docs</text>
+  <text x="38" y="776" font-family="Courier New,monospace" font-size="11" fill="#333">        plans/          ← Plan docs</text>
+  <text x="38" y="794" font-family="Courier New,monospace" font-size="11" fill="#333">        .assets/        ← Binary assets</text>
+
+  <!-- ===== SECTION: GOVERNANCE MECHANISMS ===== -->
+  <rect x="430" y="530" width="1200" height="290" rx="8" fill="#fffbf0" stroke="#f39c12" stroke-width="2"/>
+  <text x="1030" y="554" text-anchor="middle" font-family="Arial,Helvetica,sans-serif"
+        font-size="14" font-weight="bold" fill="#f39c12">Governance Mechanisms</text>
+
+  <!-- Gov 1 -->
+  <rect x="446" y="568" width="270" height="232" rx="6" fill="#fdebd0" stroke="#f39c12" stroke-width="1.5"/>
+  <text x="581" y="589" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="12" font-weight="bold" fill="#1a1a2e">1. Scope-type standards</text>
+  <text x="461" y="609" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">Policies in core-type scopes that</text>
+  <text x="461" y="625" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">define rules for ALL scopes of a</text>
+  <text x="461" y="641" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">given type.</text>
+  <text x="461" y="669" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#888">e.g. business-area-scope-type.md</text>
+  <text x="461" y="685" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#888">in ecomm-core applies to all</text>
+  <text x="461" y="701" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#888">business-area scopes</text>
+
+  <!-- Gov 2 -->
+  <rect x="732" y="568" width="270" height="232" rx="6" fill="#fdebd0" stroke="#f39c12" stroke-width="1.5"/>
+  <text x="867" y="589" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="12" font-weight="bold" fill="#1a1a2e">2. follows: declaration</text>
+  <text x="747" y="609" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">Scope explicitly declares which</text>
+  <text x="747" y="625" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">core-type scope standards apply.</text>
+  <text x="747" y="641" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">Creates a mandatory governance</text>
+  <text x="747" y="657" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">relationship to that scope.</text>
+  <text x="747" y="685" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#888">e.g. checkout/index.md:</text>
+  <text x="747" y="701" font-family="Courier New,monospace" font-size="10" fill="#888">follows: ecomm-core</text>
+
+  <!-- Gov 3 -->
+  <rect x="1018" y="568" width="270" height="232" rx="6" fill="#fdebd0" stroke="#f39c12" stroke-width="1.5"/>
+  <text x="1153" y="589" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="12" font-weight="bold" fill="#1a1a2e">3. Local meta-policies</text>
+  <text x="1033" y="609" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">Files named NNN-core.md inside</text>
+  <text x="1033" y="625" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">a scope's principles/ directory.</text>
+  <text x="1033" y="641" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">Govern authoring within that</text>
+  <text x="1033" y="657" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">scope only.</text>
+  <text x="1033" y="685" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#888">Applied implicitly — no index</text>
+  <text x="1033" y="701" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#888">declaration needed.</text>
+
+  <!-- Gov 4 -->
+  <rect x="1304" y="568" width="310" height="232" rx="6" fill="#fdebd0" stroke="#f39c12" stroke-width="1.5"/>
+  <text x="1459" y="589" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="12" font-weight="bold" fill="#1a1a2e">4. -core sibling scope</text>
+  <text x="1319" y="609" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">A separate scope directory of</text>
+  <text x="1319" y="625" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">scope-type: core for shared</text>
+  <text x="1319" y="641" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">meta-governance across a family</text>
+  <text x="1319" y="657" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">of governed scopes.</text>
+  <text x="1319" y="685" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#888">e.g. ecomm-core/ governs all</text>
+  <text x="1319" y="701" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#888">ecomm business-area scopes.</text>
+  <text x="1319" y="717" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#888">Distinct from local meta-policy.</text>
+
+  <!-- Precedence chain label -->
+  <text x="1030" y="742" text-anchor="middle" font-family="Arial,Helvetica,sans-serif"
+        font-size="11" font-weight="bold" fill="#f39c12">Precedence chain (lowest → highest):</text>
+  <text x="1030" y="760" text-anchor="middle" font-family="Arial,Helvetica,sans-serif"
+        font-size="11" fill="#555">1. Scope-type standards  →  2. follows: standards  →  3. Local meta-policies  (all subordinate to _core structural rules)</text>
+  <text x="1030" y="778" text-anchor="middle" font-family="Arial,Helvetica,sans-serif"
+        font-size="11" fill="#555">When absent from workspace: companion scope is READ-ONLY. Governed scope declares follows: in its index.md.</text>
+
+  <!-- ===== DISTRIBUTION SECTION ===== -->
+  <rect x="20" y="840" width="1610" height="130" rx="8" fill="#f0f8ff" stroke="#2980b9" stroke-width="2"/>
+  <text x="825" y="864" text-anchor="middle" font-family="Arial,Helvetica,sans-serif"
+        font-size="14" font-weight="bold" fill="#2980b9">Distribution &amp; Usage — Versioned Packages</text>
+
+  <!-- Package -->
+  <rect x="36" y="876" width="240" height="80" rx="6" fill="#dae8fc" stroke="#6c8ebf" stroke-width="1.5"/>
+  <text x="156" y="896" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="12" font-weight="bold" fill="#1a1a2e">Package</text>
+  <text x="156" y="912" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#444">Scopes are versioned npm</text>
+  <text x="156" y="926" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#444">distributions. Consumers install</text>
+  <text x="156" y="940" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#444">and extract them into workspace.</text>
+
+  <!-- Scope Composition -->
+  <rect x="296" y="876" width="240" height="80" rx="6" fill="#d5e8d4" stroke="#82b366" stroke-width="1.5"/>
+  <text x="416" y="896" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="12" font-weight="bold" fill="#1a1a2e">Scope Composition</text>
+  <text x="416" y="912" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#444">Multiple scopes compose together.</text>
+  <text x="416" y="926" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#444">External scopes tracked in</text>
+  <text x="416" y="940" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#444">.filedist.lock as read-only.</text>
+
+  <!-- Linting -->
+  <rect x="556" y="876" width="240" height="80" rx="6" fill="#fff2cc" stroke="#d6b656" stroke-width="1.5"/>
+  <text x="676" y="896" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="12" font-weight="bold" fill="#1a1a2e">Linting / Validation</text>
+  <text x="676" y="912" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#444">xdrs-core CLI validates structure,</text>
+  <text x="676" y="926" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#444">frontmatter, naming, index links,</text>
+  <text x="676" y="940" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#444">and scope governance compliance.</text>
+
+  <!-- AI Agents -->
+  <rect x="816" y="876" width="240" height="80" rx="6" fill="#e1d5f7" stroke="#7c4dff" stroke-width="1.5"/>
+  <text x="936" y="896" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="12" font-weight="bold" fill="#1a1a2e">AI Agent Context</text>
+  <text x="936" y="912" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#444">AGENTS.md + XDRS structure gives</text>
+  <text x="936" y="926" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#444">AI agents reliable, scoped access</text>
+  <text x="936" y="940" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#444">to all decisions and skills.</text>
+
+  <!-- RAG -->
+  <rect x="1076" y="876" width="240" height="80" rx="6" fill="#f8cecc" stroke="#b85450" stroke-width="1.5"/>
+  <text x="1196" y="896" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="12" font-weight="bold" fill="#1a1a2e">RAG / Web Publishing</text>
+  <text x="1196" y="912" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#444">Compiled corpus feeds RAG apps,</text>
+  <text x="1196" y="926" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#444">documentation sites, or knowledge</text>
+  <text x="1196" y="940" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#444">base systems.</text>
+
+  <!-- Extension Packages -->
+  <rect x="1336" y="876" width="280" height="80" rx="6" fill="#fdebd0" stroke="#f39c12" stroke-width="1.5"/>
+  <text x="1476" y="896" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="12" font-weight="bold" fill="#1a1a2e">Extension Packages</text>
+  <text x="1476" y="912" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#444">Teams build their own XDRS packages</text>
+  <text x="1476" y="926" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#444">extending xdrs-core with custom</text>
+  <text x="1476" y="940" text-anchor="middle" font-family="Arial,Helvetica,sans-serif" font-size="10" fill="#444">scopes and governance rules.</text>
+
+</svg>

package/.xdrs/_core/adrs/principles/articles/001-xdrs-overview.md

@@ -8,6 +8,8 @@ the framework and links out to the authoritative Policy documents for full detai
 
 ## Content
 
+![XDRS Overview Diagram](.assets/001-xdrs-overview.svg)
+
 ### What the central elements are
 
 The XDRS framework is built around a small set of artifact types that play different roles in the

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/002-write-policy/SKILL.md

@@ -142,7 +142,7 @@ Mandatory rules to apply while drafting:
 - Keep the decision itself authoritative in the Policy. Supporting artifacts may elaborate, but they should not restate the full decision when a short reference is enough.
 - Make clear when the decision applies and any important exception boundaries.
 - Keep exploratory option analysis in a related Research document when it would distract from the final decision text.
-- Prefer plain Markdown, tables, Mermaid.js (sequence, state, activity, entity diagrams), or ASCII art for simple structure, flow, layout, or relationship indications.
+- 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.
 - If the Policy genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/.assets/` and link them using a same-folder relative path (e.g., `.assets/image.png`).
 - Use relative paths for all links; never use absolute paths starting with `/`.
 - No emojis. Lowercase filenames.

package/.xdrs/_core/adrs/principles/skills/003-write-skill/SKILL.md

@@ -99,7 +99,7 @@ Rules:
 - Do not duplicate content from referenced Policies — link instead.
 - Do not present the skill itself as policy; mandatory behavior must come from referenced Policies or other policy artifacts.
 - When the skill depends on Policies, make the activation logic and instructions consistent with the Policy metadata so the skill does not operationalize inactive or out-of-scope decisions.
-- Prefer plain Markdown, tables, Mermaid.js (sequence, state, activity, entity diagrams), or ASCII art for simple structure, flow, layout, or relationship indications.
+- 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.
 - If `SKILL.md` genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/.assets/` and link them using a same-folder relative path (e.g., `.assets/image.png`).
 - Use relative paths for all links; never use absolute paths starting with `/`.
 - No emojis. Lowercase filenames. Target under 6500 words.

package/.xdrs/_core/adrs/principles/skills/004-write-article/SKILL.md

@@ -98,7 +98,7 @@ Rules to apply while drafting:
 - Every factual claim must link back to the authoritative Policy or Skill.
 - If the article advises readers what to do, clearly separate active/applicable Policies from background, historical, or out-of-scope ones.
 - Never reproduce decision text verbatim; summarize and link.
-- Prefer plain Markdown, tables, Mermaid.js (sequence, state, activity, entity diagrams), or ASCII art for simple structure, flow, layout, or relationship indications.
+- 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.
 - If the article genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/articles/.assets/` and link them using a same-folder relative path (e.g., `.assets/image.png`).
 - Use relative paths for all links; never use absolute paths starting with `/`.
 - Target under 1950 words for best reader engagement (SHOULD). If content grows beyond that, break it into separate chapter articles rather than expanding a single file. The hard limit is 8000 words.

package/.xdrs/_core/adrs/principles/skills/005-write-research/SKILL.md

@@ -139,7 +139,7 @@ Rules:
 - Keep traceability to related Policies, skills, articles, discussions, and external sources primarily in `## References`.
 - Use good-enough evidence. Experienced professional judgment is allowed, but the conclusions still need support that other colleagues can inspect and learn from.
 - Ensure the methods and test conditions are reproducible enough for an experienced professional to rerun or evolve the critical parts later.
-- Prefer plain Markdown, tables, Mermaid.js (sequence, state, activity, entity diagrams), bullet points, or ASCII art for simple explanations and comparisons, especially in the introduction and results.
+- For diagrams and non-Markdown assets, follow `_core-adr-policy-020`: prefer plain Markdown tables/lists and bullet points 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.
 - If the research genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/researches/.assets/` and link them using a same-folder relative path (e.g., `.assets/image.png`).
 - Use relative paths for all links; never use absolute paths starting with `/`.
 - Keep section word limits within the standard and keep the document under 5000 words total unless the introduction explicitly states that a very detailed analysis is required.

package/.xdrs/_core/adrs/principles/skills/006-write-plan/SKILL.md

@@ -118,7 +118,7 @@ Rules to apply while drafting:
 - The Expected end date must be in ISO format (YYYY-MM-DD), placed inside the `## Proposed Solution` section, and should not be more than 2 years from the plan creation date.
 - If the plan scope is too large for 2 years, break it into multiple plans.
 - Remember that this plan must be deleted after full implementation. Write it with that ephemeral nature in mind.
-- Prefer plain Markdown, tables, or ASCII art for structure and flow.
+- 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 for complex diagrams, 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.
 - If the plan genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/plans/.assets/` and link them using a same-folder relative path (e.g., `.assets/image.png`).
 - Use relative paths for all links; never use absolute paths starting with `/`.
 - Use lowercase file names. Never use emojis.

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

@@ -44,11 +44,9 @@ 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
+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
-   - ASCII art for simple layouts or structures
    - Key short statements for emphasis
    - Longer text only when exact wording must be evaluated (policies, controls)
 4. Keep the total under 30 slides. If more content is needed, plan separate slide sets.
@@ -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)