STRUCTURE

Research structure and conventions

This document defines the organization of the interface-density research so that future updates remain complete and auditable.

Final organization

density-research/
├── README.md
├── index.md
├── STRUCTURE.md
├── PDS-density-proposal.md
├── _comparison.md
├── _token-analysis.md
├── _practitioner-evidence.md
├── _implementation-data.json
├── handoff/
│   ├── README.md
│   ├── decision-brief.md
│   ├── architecture-options.md
│   ├── component-metric-inventory.md
│   ├── workshop-guide.md
│   ├── pilot-plan.md
│   └── decision-record.md
├── systems/
│   └── <system>.md
├── sources/
│   └── <system>/
│       ├── README.md
│       └── upstream/          # when downloadable source is available
└── token-library/
    ├── README.md
    ├── manifest.json
    ├── render-markdown.ps1
    ├── markdown/
    │   ├── README.md
    │   └── <system>.md
    └── <system>.json

Naming conventions

• System identifiers use lowercase kebab-case.
• A system uses the same identifier in systems/, sources/, token-library/, and token-library/manifest.json.
• Root Markdown files beginning with _ are cross-system synthesis documents.
• index.md is the concise navigation entry point; README.md remains the complete research overview and coverage index.
• PDS-density-proposal.md is an application of the research to PDS and is kept separate from external-system evidence.
• handoff/ translates existing research and the PDS proposal into decision, audit, workshop, and pilot materials. It must keep research findings distinct from proposals and unresolved decisions.
• Deep paths under sources/<system>/upstream/ preserve upstream repository structure and must not be reorganized.

Completeness contract

Every researched system must have:

1. systems/<system>.md — factual system report.
2. sources/<system>/README.md — provenance, version or retrieval date, captured-path inventory, and coverage limits.
3. token-library/<system>.json — exact public values and mechanisms, with unavailable data explicitly identified.
4. A matching entry in token-library/manifest.json.
5. A generated practitioner view at token-library/markdown/<system>.md.

If downloadable source is unavailable, retain the source directory and use its README as a provenance record. Do not create an empty or speculative upstream/ tree.

Evidence and linking conventions

• Prefer relative links between authored research files.
• Each system report links to its local source README and token extract.
• Each source README links back to the system report and token extract.
• Each token file identifies source paths relative to density-research/ and records unavailable evidence explicitly.
• Generated token Markdown embeds the authoritative JSON. Edit the JSON, then run token-library/render-markdown.ps1; do not edit generated system views directly.
• Official public links remain near the claims they support.
• Do not infer unpublished values, APIs, Figma structures, or maturity claims.
• Relative-link validation covers authored research files. Links embedded inside preserved upstream files may refer to uncaptured repository material; those files remain unchanged so the snapshot retains upstream fidelity.

Maintenance workflow

When adding or updating a system:

1. Update the system report without changing unrelated synthesis claims.
2. Add only density-relevant upstream files and preserve their original paths.
3. Record commit, tag, package version, publication date, and retrieval date where available.
4. Update the normalized token extract and manifest.
5. Regenerate practitioner token views.
6. Update the root index and any affected synthesis or handoff documents.
7. Validate JSON, embedded JSON parity, and authored relative links.

Generated directory-tree snapshots are intentionally not stored because they become stale; the root README and this structure guide are the maintained indexes.