08 README as Folder Index Standard

Context

The handbook content tree contained two competing conventions for folder index/landing pages:

1. README.md — Used in Management Practice folders (e.g., HR Management/README.md) and as the Quartz-native folder index convention
2. 01 Overview.md — Used in Value Stream, Guild, Practices, Roles, Cross-Guild, and Company Products folders (21 files total)

Additionally, two standalone index files existed:

• content/01 Value Streams/Value Stream Index.md
• content/02 Guilds/Guild Index.md

This created several problems:

• Quartz rendering gaps: Quartz 4 treats README.md (and index.md) as folder index pages, rendering them when users click folder navigation links. 01 Overview.md was not recognized as a folder index, so clicking a folder in the Explorer showed an auto-generated listing instead of the authored overview content.
• Inconsistency: Some folders used README.md, others used 01 Overview.md, and top-level sections used unique names (Value Stream Index.md, Guild Index.md). Contributors had to know which convention applied where.
• Plugin fallback complexity: Both the Quartz pageList.ts transformer and the Obsidian obsidian-page-list plugin needed a three-tier fallback chain (README.md > 01 Overview.md > index.md) to handle both patterns.
• Numbering collision: In Value Stream directories, 01 Overview.md occupied the 01 prefix, forcing the first substantive document (Value Stream Map) to start at 02. Removing 01 Overview.md freed the 01 prefix for actual content files.

Plan 05 (“Remove README Pattern”) had previously proposed the opposite direction — replacing README.md with 01 Overview.md everywhere. That plan was superseded because it would have worked against Quartz’s native folder index behaviour rather than with it.

Decision

Standardise on README.md as the sole folder index/landing page convention across the entire content tree.

Changes Applied

1. 21 01 Overview.md files renamed to README.md across Value Streams (4), Guild top-level (5), Guild Practices (5), Guild Roles (3), Guild Roles/Cross-Guild (2), Company Products (1), and NeuralOps decisions (1)
2. Value Stream Index.md and Guild Index.md renamed to README.md in their respective directories
3. Value Stream sibling files renumbered (decremented by 1): 02 Value Stream Map.md → 01 Value Stream Map.md through 06 Practice Links.md → 05 Practice Links.md, across all 4 VS directories
4. 150+ wikilinks updated throughout content files, templates, and diagrams to reference the new filenames
5. Plugin logic simplified: Quartz pageList.ts and Obsidian obsidian-page-list/main.js fallback chains reduced from 3 tiers to 2 (README.md > index.md)
6. Obsidian frontmatter enforcer pattern updated (**/VS*/01 Overview.md → **/VS*/README.md)
7. Plan 05 marked as Superseded
8. All plan files, decisions, and documentation updated to reflect the new convention

Convention Going Forward

Folder type	Index file	Notes
Any content folder	README.md	The universal standard
Folders with numbered siblings	README.md + 01 ..., 02 ..., etc.	Numbering starts at 01 for the first substantive file
Quartz root	index.md	Quartz requires this specifically for the site root

Considered Options

Option A: Standardise on README.md (Chosen)

• Good, because Quartz 4 natively treats README.md as a folder index page
• Good, because it aligns with the convention already used in 14 Management Practice folders
• Good, because it is the universal convention across GitHub, GitLab, npm, and most documentation systems
• Good, because it simplifies plugin fallback logic
• Good, because it frees the 01 prefix for actual content files in numbered directories
• Bad, because it requires a one-time migration of 21 files and 150+ link updates

Option B: Standardise on 01 Overview.md (Plan 05 — Superseded)

• Good, because it maintains alphabetical sorting consistency with numbered siblings
• Bad, because Quartz does not recognise 01 Overview.md as a folder index — requires custom emitter modifications
• Bad, because it fights against the platform’s native behaviour
• Bad, because it would require removing 14 existing README.md files in Practice folders
• Bad, because it is not a recognised convention outside this repository

Option C: Keep both conventions (Status quo)

• Bad, because contributors must know which convention applies to which folder type
• Bad, because plugins need complex fallback chains
• Bad, because new content creation templates must handle both patterns

Decision Outcome

Chosen option: Option A — Standardise on README.md, because it aligns with both Quartz’s native folder index behaviour and the broader industry convention, eliminates contributor confusion, and simplifies the plugin architecture. The one-time migration cost is justified by the permanent reduction in complexity.

Consequences

• All new folders must use README.md as their index page
• This applies to governance plan directories as well, including every subdirectory under content/00 Governance/Plans/
• Empty placeholder folders should not remain in published content paths without a README.md, because Quartz can only render authored folder content when the folder index file exists
• The Templater templates (TMP02 Guild Overview) already generate README.md
• The scaffolding code in Plan 08 has been updated to generate README.md instead of 01 Overview.md
• The obsidian-frontmatter-enforcer rules have been updated
• Plan 05 is superseded and should not be implemented