SOF-8025: plan for concept documentation and interactive Entity Map

[timurbazhirov]

Epic: SOF-8025

Introduces the plan/ folder convention from mat3ra/agents (section 6) to this repository, and files the plan for two additions to schemas.mat3ra.com: concept documentation and an interactive Entity Map.

Documentation only — no code, no CI changes. The implementation lands in the chained PRs below.

What is here

plan/
├── README.md                     # canonical folder convention, copied from mat3ra/agents
├── upcoming/                     # agreed direction, not built yet
│   ├── ...-entity-map-and-docs-overview.md         # the epic
│   ├── ...-entity-graph-foundation.md              # SOF-8026
│   ├── ...-entity-map.md                           # SOF-8027
│   ├── ...-concept-documentation.md                # SOF-8028
│   └── ...-site-integration-and-release.md         # SOF-8029
└── context/                      # reference material, not plans
    ├── ...-entity-map-plan-review-tb.md            # review + decisions
    └── ...-schema-graph-measurements.md            # the numbers behind the plan

One document per deliverable PR, so each can move upcoming/ → review/ → implemented/ independently.

The problem being solved

The deployed site is a file explorer: it answers "show me schema X" well, but the structure that makes ESSE coherent — 937 references forming an inheritance/composition graph — is invisible, and nothing explains the design. A new contributor cannot answer "what uses core/reusable/energy?" without grepping, or learn why the primitive/abstract/reusable layering exists without reading hundreds of files.

Measurements behind the plan

Taken from the current schema sources and recorded in plan/context/:

Measure	Value
Schema files / example files	564 / 209 (37% coverage)
Reference edges	937 — 376 extends (allOf), 384 contains (properties/items), 177 variant (oneOf/anyOf)
Unresolvable refs / cycles	0 / 0
Isolated schemas	34
Most referenced	definitions/units (30), core/primitive/scalar (28)
Largest fan-out	property/holder (44)

~1.5k rendered elements — comfortably client-side, no backend needed.

Key decisions recorded in the review

1. The CI Pages staging directory is renamed docs/ → site/, freeing docs/ for real documentation sources (its name is incidental — peaceiris publishes the directory's contents to gh-pages). No docs_src/.
2. Docs tooling is a minimal marked-based build step, not a static site generator.
3. CDN dependencies stay (Monaco precedent), pinned with subresource-integrity hashes.
4. The feature is named Entity Map.
5. Examples are detail-panel content, not map nodes; the 209/564 coverage gap becomes a lint-reported metric.
6. graph.json stays site-only until a downstream consumer exists.
7. The landing page gains a Docs · Explorer · Map header.
8. The graph lint runs on pull requests, not only at deploy.
9. The layer taxonomy must be total — unclassifiable paths fail the lint.
10. Map placement encodes the layering rather than mirroring the directory tree.
11. manifest/properties.yaml flags surface as node badges and join the lint.
12. #/entity/<$id> deep links are a documented stability contract.

Chained PRs

This is the root of the chain; each subsequent PR targets the previous branch.

• epic/SOF-8025 → dev (this PR)
• feature/SOF-8026 → epic/SOF-8025 — entity graph extractor + CI lint
• feature/SOF-8027 → feature/SOF-8026 — Entity Map
• feature/SOF-8028 → feature/SOF-8027 — concept documentation + docs/→site/ rename
• feature/SOF-8029 → feature/SOF-8028 — site integration and release

🤖 Generated with Claude Code

---

Generated by Claude Code