xdrs-core 0.18.0 → 0.20.0

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

@@ -36,7 +36,7 @@ Collectively, these are referred to as XDRs.
 - ALWAYS use the following folder structure for XDR documents:
   `.xdrs/[scope]/[type]/[subject]/[number]-[short-title].md`
 - ALWAYS ignore symlinks paths. NEVER create or update documents inside symlinked folders.
-- **Readonly files are external XDRs.** A file with read-only permissions (e.g., `444` set by a distribution tool such as filedist) was distributed from an external source repository. It must NEVER be modified locally. To change it, submit the change to the source repository and re-extract the updated package.
+- **Files listed in `.filedist` are external XDRs.** A file whose path appears in the workspace root `.filedist` file was distributed from an external source repository. It must NEVER be modified locally. To change it, submit the change to the source repository and re-extract the updated package. The `.filedist` format is one entry per line: `<relative-path>|<package>|<version>`. A scope is considered external when any of its files appear in `.filedist`, and tools (such as `xdrs-core lint`) will skip external scopes by default.
 - Optional supporting artifacts under the same subject:
   - `.xdrs/[scope]/[type]/[subject]/researches/[number]-[short-title].md`
   - `.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/SKILL.md`
@@ -48,12 +48,12 @@ Collectively, these are referred to as XDRs.
   - `_core-adr-004` defines article standards
   - `_core-adr-006` defines research standards
   - `_core-adr-007` defines plan standards
-- For simple structure, flow, layout, or relationship indications, documents SHOULD prefer plain Markdown, tables, or ASCII art instead of external assets.
-- Images and other supporting files SHOULD be used only when they are materially necessary to preserve clarity, fidelity, or evidence. When used, they SHOULD live in a sibling `assets/` folder next to the document.
-  - XDRs in the subject root use `.xdrs/[scope]/[type]/[subject]/assets/`
-  - Articles use `.xdrs/[scope]/[type]/[subject]/articles/assets/`
-  - Research uses `.xdrs/[scope]/[type]/[subject]/researches/assets/`
-  - Skills use `.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/assets/`
+- 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.
+- Images and other supporting 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.
+  - XDRs in the subject root use `.xdrs/[scope]/[type]/[subject]/.assets/`
+  - Articles use `.xdrs/[scope]/[type]/[subject]/articles/.assets/`
+  - Research uses `.xdrs/[scope]/[type]/[subject]/researches/.assets/`
+  - Skills use `.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/.assets/`
 - **Scopes:** 
   - Short name that defines a group or a package of xdrs
   - examples: `business-x`, `business-y`, `team-43`, `_core`
@@ -107,16 +107,24 @@ Collectively, these are referred to as XDRs.
     - `governance`: Engineering governance, risk controls, and compliance mechanics.
       - Examples: dependency governance, approval policies, mandatory quality checks.
 - Never use emojis
-- **Links:** Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/` (e.g., `/.xdrs/_core/adrs/principles/001-xdrs-core.md`). Sibling files and child folder references SHOULD use relative paths (e.g., `002-other-doc.md`, `assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../../assets/test.png`, `../other.md`); they break when files are moved and are harder to read.
+- **Links:** Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/` (e.g., `/.xdrs/_core/adrs/principles/001-xdrs-core.md`). Sibling files and child folder references SHOULD use relative paths (e.g., `002-other-doc.md`, `.assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../../.assets/test.png`, `../other.md`); they break when files are moved and are harder to read.
 - **Indexes**
-  - Keep a canonical index with all XDRs of a certain type+scope in `.xdrs/[scope]/[type]/index.md`
+  - Every document in the collection (XDRs, 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.
+  - Keep a canonical type index with all documents of a certain type+scope in `.xdrs/[scope]/[type]/index.md`. The type index must link to every XDR, skill, article, research, and plan under that type+scope.
   - Canonical index requirements:
     - Organize XDR documents by subject for easier navigation
     - Add a short description of what this scope is about (responsibilities, general worries, teams involved, link to discussion process, etc)
     - Add a list of other scope indexes that this scope might be related to (only add scopes that might be overridden). E.g: "business-x-mobileapp" scope could refer to "business-x" and "sensitive-data" scopes in its index list. XDRs in scopes listed last override XDRs in scopes listed first when addressing the same topic.
     - Each XDR element entry in the index MUST include a short description of its content, preferably with an imperative statement or the question it answers, when possible (<15 words). Example: "Use this while planning a new feature", "What communication tone we use with our customers?", "PNPM vs Yarn comparison study"
-  - Outside the scopes, keep an index pointing to all canonical indexes in `.xdrs/index.md`. Add the text "XDRs in scopes listed last override the ones listed first"
+  - Outside the scopes, keep a root index in `.xdrs/index.md` that links to each scope index (`.xdrs/[scope]/index.md`). Add the text "XDRs in scopes listed last override the ones listed first". The root index must not link directly to type indexes; readers navigate from the scope index to the type indexes. Use the link text pattern `View scope [scope_name]` for each scope link (e.g. `[View scope myteam] linking to (myteam/index.md)`).
   - Always verify if indexes are up to date after making changes
+- **Scope index**
+  - Each scope folder must maintain an `index.md` file at `.xdrs/[scope]/index.md`.
+  - The scope index is a short article (under 1000 words) that provides an overview of all XDR contents within that scope. Follow article standards (`_core-adr-004`) when writing this file.
+  - The audience for the scope index are engineers, architects, or business analysts who want to check if the scope's contents are useful for them before diving into the specific documents. Write a guided summary that helps them decide whether to explore further.
+  - Focus on the most relevant content of the scope: what decisions are covered, what problems they address, and how the scope relates to other scopes.
+  - At the end of the scope index, always add links to the canonical type indexes (`adrs/index.md`, `bdrs/index.md`, `edrs/index.md`) that exist within the scope.
+  - Whenever the contents of a scope change (new XDRs, skills, articles, research, or plans are added, updated, or removed), evaluate whether the scope index should be updated to reflect the newer contents.
 
 **Folder structure examples:**
 - `.xdrs/business-x/edrs/devops/003-required-development-workflow.md`
@@ -126,20 +134,20 @@ Collectively, these are referred to as XDRs.
 ```text
 subject/
 |-- 001-xdr.md
-|-- assets/
+|-- .assets/
 |-- articles/
 |   |-- 001-article.md
-|   `-- assets/
+|   `-- .assets/
 |-- plans/
 |   |-- 001-plan.md
-|   `-- assets/
+|   `-- .assets/
 |-- researches/
 |   |-- 001-study.md
-|   `-- assets/
+|   `-- .assets/
 `-- skills/
     `-- 001-task/
         |-- SKILL.md
-        `-- assets/
+        `-- .assets/
 ```
 
 ## References

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

@@ -109,7 +109,7 @@ Question: In the end, state explicitly the question that needs to be answered. E
 [Optional section with implementation specifics, applicability boundaries, rules, concise examples, or do/don't guidance. This is the answer to the question in the "Context and Problem Statement". (<1300 words)]
 
 ## Considered Options 
-[this section is present ONLY if there was more than one option to choose from]
+[this section is present ONLY if the user explicitely indicated that there were multiple options to choose from while making this decision.]
 
 * (CHOSEN) **Option 2** - Brief description of option 2
   * Reason: Brief description of why this option was accepted, containing the strengths, strategical motivations and it's differential over the other options.

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

@@ -63,7 +63,7 @@ Quick test:
             SKILL.md              # required
             scripts/              # optional: executable scripts the agent may run
             references/           # optional: detailed reference material
-            assets/               # optional: images, templates, data files, and other local resources
+            .assets/               # optional: images, templates, data files, and other local resources
 ```
 
 Examples:
@@ -114,9 +114,9 @@ Rules:
 - `## 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.
-- Images and other local resource files referenced from `SKILL.md` SHOULD be used only when they are materially necessary and SHOULD live in `assets/` inside the same skill package.
+- Images and other local resource files referenced from `SKILL.md` SHOULD be used only when they are materially necessary and MUST live in `.assets/` inside the same skill package.
 - Keep `SKILL.md` under 6500 words. Move lengthy reference material to `references/`.
-- Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/`. Sibling files and child folder references SHOULD use relative paths (e.g., `assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../other.md`).
+- Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/`. Sibling files and child folder references SHOULD use relative paths (e.g., `.assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../other.md`).
 - Always use lowercase file names.
 - Never use emojis in skill content.
 

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

@@ -28,7 +28,7 @@ Articles are Markdown documents placed inside a subject folder alongside decisio
 - Articles must remain consistent with the XDRs, 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-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.
-- Images and other local resource files referenced by an article SHOULD be used only when they are materially necessary and SHOULD live in `articles/assets/` next to the article files.
+- Images and other local resource 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.
 - Always use lowercase file names.
 - Never use emojis in article content.
 - Articles should be kept under 1950 words. Move detailed content to referenced XDRs or Skills.
@@ -42,7 +42,7 @@ Articles are Markdown documents placed inside a subject folder alongside decisio
       [subject]/
         articles/
           [number]-[short-title].md
-          assets/
+          .assets/
 ```
 
 Examples:

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

@@ -48,7 +48,7 @@ Research documents are Markdown files placed inside a subject folder alongside d
 - Research documents SHOULD link in `## References` to the XDRs, 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 XDRs, including a mix of ADRs, BDRs, and EDRs, when the same investigation remains relevant across several decisions.
-- Images and other local resource files referenced by a research document SHOULD be used only when they are materially necessary and SHOULD live in `researches/assets/` next to the research files.
+- Images and other local resource 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.
 - Research file names MUST be lowercase. Never use emojis.
 - A research document MAY exist before the related XDR is written, or remain after the XDR changes, as long as its status and references stay clear.
 
@@ -61,7 +61,7 @@ Research documents are Markdown files placed inside a subject folder alongside d
       [subject]/
         researches/
           [number]-[short-title].md
-          assets/
+          .assets/
 ```
 
 Examples:

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

@@ -31,7 +31,7 @@ Plans are Markdown documents placed inside a subject folder alongside decision r
 - Plans MUST include an `Expected end date:` field in ISO format (YYYY-MM-DD) inside the `## Proposed Solution` section.
 - Always use lowercase file names.
 - Never use emojis in plan content.
-- Images and other local resource files referenced by a plan SHOULD live in `plans/assets/` next to the plan files.
+- Images and other local resource files referenced by a plan MUST live in `plans/.assets/` next to the plan files.
 
 **Folder layout**
 
@@ -42,7 +42,7 @@ Plans are Markdown documents placed inside a subject folder alongside decision r
       [subject]/
         plans/
           [number]-[short-title].md
-          assets/
+          .assets/
 ```
 
 Examples:

package/.xdrs/_core/adrs/principles/skills/002-write-xdr/SKILL.md

@@ -35,6 +35,7 @@ Consult `001-xdrs-core` while making each choice in this phase. The summaries be
 - **EDR**: specific tool/library, coding practice, testing strategy, project structure
 
 **Scope** — use `_local` unless the user explicitly names another scope.
+- If the user names a scope other than `_local`, check the workspace root `.filedist` file. If any file under `.xdrs/[scope]/` appears in `.filedist`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
 
 **Subject** — pick one from the allowed list for the chosen type (from `001-xdrs-core`):
 - ADR: `principles`, `application`, `data`, `integration`, `platform`, `controls`, `operations`
@@ -123,7 +124,7 @@ valid-from: [Optional. ISO date YYYY-MM-DD from when enforcement begins]
 ### Implementation Details
 [Rules, applicability boundaries, concise examples, and optional do/don't guidance — under 1300 words]
 
-## Considered Options (if meaningful options exist)
+## Considered Options (only if the user explicitly indicated multiple options)
 
 ## Conflicts (mandatory if conflicts found in Phase 3)
 
@@ -140,9 +141,9 @@ Mandatory rules to apply while drafting:
 - Keep the decision itself authoritative in the XDR. 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, or ASCII art for simple structure, flow, layout, or relationship indications.
-- If the XDR 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`).
-- Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/` (e.g., `/.xdrs/_core/adrs/principles/001-xdrs-core.md`). Sibling files and child folder references SHOULD use relative paths (e.g., `002-other-doc.md`, `assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../../assets/test.png`, `../other.md`).
+- Prefer plain Markdown, tables, Mermaid.js (sequence, state, activity, entity diagrams), or ASCII art for simple structure, flow, layout, or relationship indications.
+- If the XDR 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`).
+- Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/` (e.g., `/.xdrs/_core/adrs/principles/001-xdrs-core.md`). Sibling files and child folder references SHOULD use relative paths (e.g., `002-other-doc.md`, `.assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../../.assets/test.png`, `../other.md`).
 - No emojis. Lowercase filenames.
 - Target under 1300 words total; under 2600 words for complex decisions.
 
@@ -167,6 +168,7 @@ If any check fails, revise and re-run this phase before proceeding.
 3. Add or verify the scope entry in `.xdrs/index.md`.
 4. If significant research was produced or already exists, link it from the XDR `## Considered Options` section.
 5. If concise rules, examples, or do/don't bullets help readers apply the decision correctly, add them inside `### Implementation Details` without turning the XDR into a long procedure.
+6. Evaluate whether the scope index at `.xdrs/[scope]/index.md` should be updated to reflect the new content. If the scope index does not exist, create it following article standards and the scope index rules in `_core-adr-001`.
 
 ### Phase 9: Verify Package structure with Lint
 
@@ -185,6 +187,7 @@ If any check fails, revise and re-run this phase before proceeding.
 - MUST NOT create an XDR that duplicates a decision already captured in another XDR — extend or reference instead.
 - MUST prefer links and short references over repeating the same decision content across related documents.
 - MUST keep scope `_local` unless the user explicitly states otherwise.
+- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist`).
 
 ## References
 

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

@@ -36,6 +36,7 @@ Quick test:
 - "How to execute a business process or policy?" → BDR
 
 **Scope** — use `_local` unless the user explicitly names another scope.
+- If the user names a scope other than `_local`, check the workspace root `.filedist` file. If any file under `.xdrs/[scope]/` appears in `.filedist`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
 
 **Subject** — pick the most specific match for the chosen type (required list per type is in `_core-adr-001`):
 - ADR subjects: `principles`, `application`, `data`, `integration`, `platform`, `controls`, `operations`
@@ -97,9 +98,9 @@ Rules:
 - Do not duplicate content from referenced XDRs — link instead.
 - Do not present the skill itself as policy; mandatory behavior must come from referenced XDRs or other policy artifacts.
 - When the skill depends on XDRs, make the activation logic and instructions consistent with the XDR metadata so the skill does not operationalize inactive or out-of-scope decisions.
-- Prefer plain Markdown, tables, or ASCII art for simple structure, flow, layout, or relationship indications.
-- 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`).
-- Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/` (e.g., `/.xdrs/_core/adrs/principles/001-xdrs-core.md`). Sibling files and child folder references SHOULD use relative paths (e.g., `002-other-doc.md`, `assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../../assets/test.png`, `../other.md`).
+- Prefer plain Markdown, tables, Mermaid.js (sequence, state, activity, entity diagrams), or ASCII art for simple structure, flow, layout, or relationship indications.
+- 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`).
+- Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/` (e.g., `/.xdrs/_core/adrs/principles/001-xdrs-core.md`). Sibling files and child folder references SHOULD use relative paths (e.g., `002-other-doc.md`, `.assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../../.assets/test.png`, `../other.md`).
 - No emojis. Lowercase filenames. Target under 6500 words.
 
 ### Phase 5: Review the Draft
@@ -122,6 +123,7 @@ If any check fails, revise before continuing.
    mkdir -p .github/skills/[number]-[skill-name]
    ln -s ../../.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name] .github/skills/[number]-[skill-name]
    ```
+3. Evaluate whether the scope index at `.xdrs/[scope]/index.md` should be updated to reflect the new skill. If the scope index does not exist, create it following article standards and the scope index rules in `_core-adr-001`.
 
 ### Constraints
 
@@ -129,6 +131,7 @@ If any check fails, revise before continuing.
 - MUST consult `001-xdrs-core` as the canonical source for every core element definition, especially type, scope, subject, numbering, naming, and placement.
 - MUST NOT create a skill that duplicates an existing one — extend or reference it instead.
 - MUST keep scope `_local` unless the user explicitly states otherwise.
+- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist`).
 - MUST include a References section linking to `003-skill-standards`.
 
 ## Examples

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

@@ -41,6 +41,7 @@ Do NOT proceed to Phase 1 until you have at minimum a clear **topic** and **audi
 Consult `001-xdrs-core` while making each choice in this phase. The summaries below are orientation only; when any detail is unclear, the standard decides.
 
 **Scope** — use `_local` unless the user explicitly names another scope.
+- If the user names a scope other than `_local`, check the workspace root `.filedist` file. If any file under `.xdrs/[scope]/` appears in `.filedist`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
 
 **Type** — match the type of the XDRs the article primarily synthesizes (`adrs`, `bdrs`, or `edrs`).
 If the topic spans multiple types, use `adrs`. Use the same rules as `002-write-xdr` Phase 2:
@@ -93,9 +94,9 @@ Rules to apply while drafting:
 - Every factual claim must link back to the authoritative XDR or Skill.
 - If the article advises readers what to do, clearly separate active/applicable XDRs from background, historical, or out-of-scope ones.
 - Never reproduce decision text verbatim; summarize and link.
-- Prefer plain Markdown, tables, or ASCII art for simple structure, flow, layout, or relationship indications.
-- 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`).
-- Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/` (e.g., `/.xdrs/_core/adrs/principles/001-xdrs-core.md`). Sibling files and child folder references SHOULD use relative paths (e.g., `002-other-doc.md`, `assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../../assets/test.png`, `../other.md`).
+- Prefer plain Markdown, tables, Mermaid.js (sequence, state, activity, entity diagrams), or ASCII art for simple structure, flow, layout, or relationship indications.
+- 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`).
+- Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/` (e.g., `/.xdrs/_core/adrs/principles/001-xdrs-core.md`). Sibling files and child folder references SHOULD use relative paths (e.g., `002-other-doc.md`, `.assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../../.assets/test.png`, `../other.md`).
 - Keep the article under 1950 words; move detailed content to XDRs or Skills.
 - Use lowercase file names. Never use emojis.
 - If a conflict exists between the article and a Decision Record, note it and defer to the XDR.
@@ -106,6 +107,7 @@ Rules to apply while drafting:
 2. Add a link to the article in the canonical index for that scope+type (`.xdrs/[scope]/[type]/index.md`).
 3. Add back-references in the XDRs, Research documents, and Skills that the article synthesizes, under their `## References`
    section.
+4. Evaluate whether the scope index at `.xdrs/[scope]/index.md` should be updated to reflect the new article. If the scope index does not exist, create it following article standards and the scope index rules in `_core-adr-001`.
 
 ## Examples
 
@@ -136,6 +138,7 @@ Rules to apply while drafting:
 - MUST consult `001-xdrs-core` as the canonical source for every core element definition, especially type, scope, subject, numbering, naming, and placement.
 - MUST follow the article template and placement rules from `004-article-standards`.
 - MUST keep scope `_local` unless the user explicitly states otherwise.
+- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist`).
 - MUST defer to active and applicable XDRs when article synthesis conflicts with them.
 
 ## References

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

@@ -36,6 +36,7 @@ If the answers from Phase 1 leave scope, type, or subject ambiguous, use `vscode
 Consult `001-xdrs-core` while making each choice in this phase. The summaries below are orientation only; when any detail matters, the standard decides.
 
 **Scope** — use `_local` unless the user explicitly names another scope.
+- If the user names a scope other than `_local`, check the workspace root `.filedist` file. If any file under `.xdrs/[scope]/` appears in `.filedist`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
 
 **Type** — match the type of decision this research supports (`adrs`, `bdrs`, or `edrs`). Use the same rules as `002-write-xdr` Phase 2:
 - **BDR**: business process, product policy, strategic rule, operational procedure
@@ -134,9 +135,9 @@ Rules:
 - Keep traceability to related XDRs, 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, bullet points, tables, or ASCII art for simple explanations and comparisons, especially in the introduction and results.
-- 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`).
-- Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/` (e.g., `/.xdrs/_core/adrs/principles/001-xdrs-core.md`). Sibling files and child folder references SHOULD use relative paths (e.g., `002-other-doc.md`, `assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../../assets/test.png`, `../other.md`).
+- 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.
+- 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`).
+- Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/` (e.g., `/.xdrs/_core/adrs/principles/001-xdrs-core.md`). Sibling files and child folder references SHOULD use relative paths (e.g., `002-other-doc.md`, `.assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../../.assets/test.png`, `../other.md`).
 - 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.
 
 ### Phase 8: Check Section Goals
@@ -244,6 +245,7 @@ If any check fails, revise before continuing.
 1. Create the research file at `.xdrs/[scope]/[type]/[subject]/researches/[number]-[short-title].md`.
 2. Add an entry to `.xdrs/[scope]/[type]/index.md`.
 3. Add back-references from the related XDR, article, or skill when the relationship is important for discovery.
+4. Evaluate whether the scope index at `.xdrs/[scope]/index.md` should be updated to reflect the new research. If the scope index does not exist, create it following article standards and the scope index rules in `_core-adr-001`.
 
 ## Examples
 
@@ -276,4 +278,5 @@ If any check fails, revise before continuing.
 - MUST consult `001-xdrs-core` as the canonical source for every core element definition, especially type, scope, subject, numbering, naming, and placement.
 - MUST follow the research template and section-goal rules from `006-research-standards`.
 - MUST keep scope `_local` unless the user explicitly states otherwise.
+- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist`).
 - MUST keep the document as research rather than turning it into a final decision.

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

@@ -33,6 +33,7 @@ Guides the creation of a well-structured plan document by following `_core-adr-0
 Consult `001-xdrs-core` while making each choice in this phase. The summaries below are orientation only; when any detail is unclear, the standard decides.
 
 **Scope** — use `_local` unless the user explicitly names another scope.
+- If the user names a scope other than `_local`, check the workspace root `.filedist` file. If any file under `.xdrs/[scope]/` appears in `.filedist`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
 
 **Type** — match the type of the XDRs the plan primarily implements or relates to (`adrs`, `bdrs`, or `edrs`).
 - **BDR**: business process, product policy, strategic rule, operational procedure
@@ -114,8 +115,8 @@ Rules to apply while drafting:
 - 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.
-- 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`).
-- Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/` (e.g., `/.xdrs/_core/adrs/principles/001-xdrs-core.md`). Sibling files and child folder references SHOULD use relative paths (e.g., `002-other-doc.md`, `assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../../assets/test.png`, `../other.md`).
+- 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`).
+- Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/` (e.g., `/.xdrs/_core/adrs/principles/001-xdrs-core.md`). Sibling files and child folder references SHOULD use relative paths (e.g., `002-other-doc.md`, `.assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../../.assets/test.png`, `../other.md`).
 - Use lowercase file names. Never use emojis.
 
 ### Phase 6: Place and Register
@@ -123,6 +124,7 @@ Rules to apply while drafting:
 1. Save the file at `.xdrs/[scope]/[type]/[subject]/plans/[number]-[short-title].md`.
 2. Add a link to the plan in the canonical index for that scope+type (`.xdrs/[scope]/[type]/index.md`).
 3. Add back-references in the XDRs, Research documents, and Skills that the plan relates to, under their `## References` section.
+4. Evaluate whether the scope index at `.xdrs/[scope]/index.md` should be updated to reflect the new plan. If the scope index does not exist, create it following article standards and the scope index rules in `_core-adr-001`.
 
 ### Phase 7: Verify with Lint
 
@@ -156,3 +158,10 @@ Rules to apply while drafting:
 - [_core-adr-001 - XDRs core](/.xdrs/_core/adrs/principles/001-xdrs-core.md)
 - [_core-adr-007 - Plan standards](/.xdrs/_core/adrs/principles/007-plan-standards.md)
 - [_core-adr-002 - XDR standards](/.xdrs/_core/adrs/principles/002-xdr-standards.md)
+
+## Constraints
+
+- MUST follow the plan template and section-goal rules from `007-plan-standards`.
+- MUST consult `001-xdrs-core` as the canonical source for every core element definition, especially type, scope, subject, numbering, naming, and placement.
+- MUST keep scope `_local` unless the user explicitly states otherwise.
+- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist`).

package/.xdrs/_core/index.md

@@ -0,0 +1,56 @@
+# _core Scope Overview
+
+## Overview
+
+The `_core` scope defines the XDR framework itself: how decision records, skills, research, articles, and plans are structured, written, versioned, and discovered. This scope is aimed at engineers, architects, and business analysts who build or consume XDR-based documentation.
+
+## Content
+
+### What this scope covers
+
+The `_core` scope is the foundation that all other scopes inherit from. It establishes the rules and conventions that every XDR document, skill, article, research, and plan must follow regardless of which team, product, or domain produces them.
+
+If you are evaluating whether to adopt XDRs, setting up a new XDR project, or extending the framework with your own scopes, start here.
+
+### Framework structure and organization
+
+The core architectural decision [_core-adr-001](adrs/principles/001-xdrs-core.md) defines the fundamental building blocks: three decision types (ADR for architecture, BDR for business, EDR for engineering), scopes as grouping boundaries, subjects as topic categories within each type, and a folder layout that keeps everything discoverable. It also defines the index system (canonical type indexes, scope indexes, and the root index) that ties the collection together.
+
+### Document writing standards
+
+Each artifact type has its own writing standard:
+
+- **XDR documents** follow [_core-adr-002](adrs/principles/002-xdr-standards.md), which defines the mandatory template, frontmatter metadata, applicability rules, conflict handling, and word limits that keep decisions concise and authoritative.
+- **Structured XDRs** with individually referenceable rules follow the extension [_core-adr-008](adrs/principles/008-xdr-standards-structured.md), adding numbered rule blocks and a dot-notation citation syntax.
+- **Skills** follow [_core-adr-003](adrs/principles/003-skill-standards.md), using the agentskills format so they work for both humans and AI agents on an automation gradient from fully manual to fully automated.
+- **Articles** follow [_core-adr-004](adrs/principles/004-article-standards.md), providing synthetic views that combine and link multiple XDRs, research, and skills without replacing them as the source of truth.
+- **Research** follows [_core-adr-006](adrs/principles/006-research-standards.md), using an IMRAD-based structure for studies that back decisions with reproducible evidence.
+- **Plans** follow [_core-adr-007](adrs/principles/007-plan-standards.md), capturing ephemeral execution plans with problem context, proposed solutions, milestones, and deliverables that are deleted after implementation.
+
+### Versioning and distribution
+
+[_core-adr-005](adrs/principles/005-semantic-versioning-for-xdr-packages.md) defines how XDR packages use semantic versioning to communicate upgrade impact when decisions are shared across repositories or teams.
+
+### Usage policy
+
+The business decision [_core-bdr-001](bdrs/principles/001-xdr-decisions-and-skills-usage.md) establishes how agents and humans must use XDR decisions and skills, separating policy authority (which lives in XDRs) from execution guidance (which lives in skills).
+
+### Available skills
+
+The `_core` scope ships with six skills that automate the most common framework operations:
+
+- **001-lint** reviews code and files against applicable XDRs
+- **002-write-xdr** guides creation of a new decision record
+- **003-write-skill** guides creation of a new skill package
+- **004-write-article** guides creation of a new article
+- **005-write-research** guides creation of a new research document
+- **006-write-plan** guides creation of a new execution plan
+
+### Getting started
+
+For a narrative introduction to the framework, including how elements differ, how to decide whether an XDR applies, and how to extend the framework with your own scopes, see the overview article [_core-article-001](adrs/principles/articles/001-xdrs-overview.md).
+
+## Type Indexes
+
+- [ADRs Index](adrs/index.md) - Architectural decisions about the XDR framework structure and standards
+- [BDRs Index](bdrs/index.md) - Business and operational decisions about framework usage policy

package/.xdrs/index.md

@@ -9,8 +9,7 @@ XDRs in scopes listed last override the ones listed first
 ### _core
 
 Decisions about how XDRs work
-[View _core ADRs Index](_core/adrs/index.md)
-[View _core BDRs Index](_core/bdrs/index.md)
+[View scope _core](_core/index.md)
 
 ---
 

package/README.md

@@ -86,20 +86,20 @@ This is especially important for BDRs: because business rules govern decisions t
       index.md                      # canonical index for this scope+type
       [subject]/
         [number]-[short-title].md   # individual decision record
-        assets/                     # optional local resources for subject-level XDR files
+        .assets/                     # optional local resources for subject-level XDR files
         researches/                 # optional decision-backing research documents
           [number]-[short-title].md
-          assets/
+          .assets/
         skills/                     # optional skill packages for humans and AI agents
           [number]-[skill-name]/
             SKILL.md
-            assets/
+            .assets/
         articles/                   # optional synthetic views over XDRs, Research, and Skills
           [number]-[short-title].md
-          assets/
+          .assets/
         plans/                      # optional ephemeral execution plans
           [number]-[short-title].md
-          assets/
+          .assets/
 ```
 
 Document types:
@@ -129,7 +129,7 @@ Each scope manages its own set of XDR artifacts independently. Scope owners disc
 
 Once a set of decisions is ready to share, scope owners pack the relevant `.xdrs/[scope]/` folder into a versioned npm package using a tool such as [filedist](https://github.com/flaviostutz/filedist) and publish it to an npm registry, either public or a company-internal one. Versioning gives consumers explicit control over which revision of a scope's decisions they adopt, avoiding situations where a single breaking policy change is forced on all consumers at once.
 
-The same applies to Research documents, skills, articles, and any sibling `assets/` folders: because they live alongside XDRs inside the scope folder, they are included in the same package and published together.
+The same applies to Research documents, skills, articles, and any sibling `.assets/` folders: because they live alongside XDRs inside the scope folder, they are included in the same package and published together.
 
 ### Usage
 
@@ -153,7 +153,7 @@ Multiple scope packages can be combined in the same workspace by listing them as
 The published package exposes the `xdrs-core` CLI.
 
 - Bootstrap or extract managed XDR files with the existing `filedist`-backed commands such as `npx -y xdrs-core extract` and `npx -y xdrs-core check`.
-- Lint an XDR tree with `npx -y xdrs-core lint .`. By default, read-only files distributed from external scopes are skipped; use `--all` to include them.
+- Lint an XDR tree with `npx -y xdrs-core lint .`. By default, scopes whose files are listed in the workspace root `.filedist` file are treated as external and skipped; use `--all` to include them.
 
 The `lint` command reads `./.xdrs/**` from the given workspace path and checks common consistency rules, including:
 
@@ -168,7 +168,7 @@ The `lint` command reads `./.xdrs/**` from the given workspace path and checks c
 - root index coverage for all discovered canonical indexes
 - XDR metadata section placement and `valid-from` / `applied-to` field format
 - local markdown links between XDR documents, skills, articles, researches, and plans (excluding fenced code blocks)
-- local image and `assets/` links resolving inside the sibling `assets/` folder for each document
+- local image and `.assets/` links resolving inside the sibling `.assets/` folder for each document
 
 Examples: