xdrs-core 0.46.3 → 0.47.0

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

@@ -100,6 +100,7 @@ ADR and EDR share the same six technical subject names (see [`_core-adr-policy-0
 - **Links:** Use relative paths for all links; MUST NOT use absolute paths starting with `/`.
 - **Indexes**
   - Every document in the collection (Policies, skills, articles, research, and plans) MUST be reachable through the index chain: root index → scope index → type index → document. A document that exists on disk but is not linked from its canonical type index is considered an orphan and MUST be added to the index or removed.
+  - Index files MUST NOT contain policy rules or normative requirements. Those MUST be placed in dedicated Policy documents. Indexes are navigation artifacts only: links and short descriptions.
   - Keep a canonical type index with all documents of a certain type+scope in `[xdrs-root]/[scope]/[type]/index.md`. The type index MUST link to every Policy, skill, article, research, and plan under that type+scope.
   - Canonical index requirements:
     - Organize XDRS documents by subject for easier navigation

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.
-- For diagram format preferences and non-Markdown asset rules, see [`_core-adr-policy-020`](020-media-and-asset-standards.md).
+- For diagram and asset rules in Policy documents, see [`_core-adr-policy-020`](020-media-and-asset-standards.md). Rule `02-policy-diagram-restrictions` below summarises the overall stance; the detailed rules are in policy 020.
 - 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
@@ -99,6 +99,10 @@ When a policy's frontmatter includes `freeze-reference: true`, the policy MUST N
 
 Content-level checks that do not affect the policy's reference (required sections, word count, emojis, broken outgoing links, structured rule block format, normative language) remain enforced. The `valid-from` date is not taken into consideration when evaluating whether `freeze-reference` applies.
 
+#### 02-policy-diagram-restrictions
+
+Images and diagrams in Policy documents are subject to strict restrictions: images MUST NOT be used; diagrams SHOULD be avoided and are only allowed in direct and punctual cases where directly connected to the decision. Diagram content has no normative force and must not be used for enforcement. For full rules see [`_core-adr-policy-020`](020-media-and-asset-standards.md) rules `10` through `14`.
+
 **Policy template**
 
 All Policies MUST follow this template

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Defines the preferred order for representing visual information and the rules for non-Markdown assets across all XDRS document types, including policy-document-specific restrictions on images and diagrams. 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
 ---
@@ -34,10 +34,10 @@ Mermaid.js SHOULD be used for diagrams that require explicit visual representati
 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 also be used when the diagram is expected to be edited directly by users in a graphical tool and its structure fits the draw.io editing model (e.g., boxes, connectors, swimlanes, layered layouts). 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.
+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. SVG MUST NOT be used in Policy documents (see rule `10-no-images-in-policies`).
 
 #### 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.
+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. PNG MUST NOT be used in Policy documents (see rule `10-no-images-in-policies`).
 
 #### 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.
@@ -48,7 +48,23 @@ Non-Markdown files (images, diagrams, schemas, JSON examples, binaries, or any o
 #### 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`.
 
+#### 10-no-images-in-policies
+Images — including raster formats (PNG, JPEG, GIF, TIFF, and similar) and SVG files — MUST NOT be used in Policy documents. These formats cannot express MUST, SHOULD, or MAY obligations with the precision that prose requires, and their content cannot be systematically enforced during review.
+
+#### 11-diagrams-rare-in-policies
+Mermaid and draw.io diagrams SHOULD be avoided in Policy documents. They MAY be included only in direct and punctual cases where the diagram illustrates the core structural pattern or architecture that the policy decision itself mandates. A diagram that introduces context, detail, or explanation not already present in the policy prose MUST NOT be included.
+
+#### 12-diagrams-connected-to-decision
+Any diagram included in a Policy document MUST be directly connected to the policy decision described in that document. A diagram MAY include a simple illustrative example. Diagrams showing multiple usage examples, edge cases, or supplementary context MUST be placed in an article instead.
+
+#### 13-diagrams-not-normative-in-policies
+Content within diagrams in Policy documents — labels, annotations, and depicted relationships — MUST NOT be used for policy enforcement. Mandatory and advisory language within a diagram has no normative force. During authoring, diagram content MUST be checked for consistency with the policy prose; any inconsistency MUST be resolved before the policy is published.
+
+#### 14-articles-for-visual-explanation
+When additional visual explanation is needed for a Policy — such as multiple usage examples, context breakdowns, detailed walkthroughs, or educational material — an article MUST be written instead of adding more diagrams to the policy. Articles are the appropriate place for visual education about a policy; the policy itself MUST remain focused on the decision declaration.
+
 ## References
 
 - [_core-adr-policy-001 - XDRS standards](001-xdrs-standards.md) - Per-document-type `.assets/` canonical paths
+- [_core-adr-policy-002 - Policy standards](002-policy-standards.md) - Summary rule `02-policy-diagram-restrictions` that points to rules 10–14 here
 - [_core-adr-policy-008 - Policy structured standards](008-policy-structured-standards.md) - Structured rule block format used in this policy

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.46.3",
+  "version": "0.47.0",
   "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",