docs(architecture): a doc page belongs with the code it documents — the measured destination map by rbuergi · Pull Request #2960 · Systemorph/MeshWeaver

rbuergi · 2026-09-01T11:08:07Z

Survey only — nothing moves in this PR. One new Doc/Architecture page plus its topic-map entry.

Maintainer directive: "i am for moving docs to the functionality ==> mcp docs should go to mcp etc". This records where each of the 996 files under src/MeshWeaver.Documentation/Data/ belongs under that rule — the same rule skills already follow — and, just as usefully, what stays here and why.

Measured against Systemorph/MeshWeaver@f8e208567 and Systemorph/MeshWeaver.Plugins@7e0750c2, plus the live memex.meshweaver.cloud mesh (0a1eabdc0).

Settled first: `Data/` is the SOURCE, not a second copy

If the mesh held an independently-authored copy, drift would outrank placement. It does not:

	Disk	Mesh	On mesh but not on disk
`Doc/WhatsNew`	709	702	0
`Doc/Architecture` (top level)	161	159	0

Every difference is disk-ahead of the deployed image, and Doc/_Policy sets Create/Update/Delete = false so a live edit cannot create one. What the measurement does expose is the lag: a doc fix rides inside MeshWeaver.Documentation.dll, so it needs a core image roll to reach any mesh — a slower channel than the one every module already uses.

The map

Folder	Files	Verdict
`AI`	13	→ the `AI` package. Every symbol resolves in `MeshWeaver.AI`, none in core; 1 executable block in the whole folder. The engine moved, its docs did not.
`WhatsNew`	709	Stays. One fleet-wide feed; satellites already file into it from their own `WhatsNew/`. Only 8.5 % of entries are about non-core packages.
`GUI`	42	Stays. A GUI doc documents the control, and controls are declared in `MeshWeaver.Layout`. 30 of 42 pages name zero plugins symbols; the folder holds 84 of the tree's 132 executable blocks.
`DataMesh`	53	Stays, bar `CollaborativeEditing` and the `SocialMedia` example.
`Architecture`	170	Splits per page, not per folder — ~20 module-owned pages listed with destination and signal.

The mechanism

A MeshDocs/ twin of MeshWeaver.Plugins#1060's ModuleSkillProvider needs no AI dependency at all — InstalledModuleAssembly, IStaticNodeProvider, MarkdownFileParser and the Markdown node type are all core. Four things differ and need designing: depth, page assets, the one-authored-home rule, and porting the doc gate.

Two defects the survey found

Core's own doc gates live in the plugins repo. DocumentationLinkIntegrityTest and DocumentationEmbedIntegrityTest pin this tree from inside MeshWeaver.Plugins/src/MeshWeaver.AI.Test/, so core's CI cannot run them.
The decentral WhatsNew lane is ungated. Three of the four entries authored through it carry no Description and no Order — the exact shape WhatsNewEntryIntegrityTest exists to catch — and the feed sorts them wrong rather than failing.

Beyond docs

samples/ is 988 files (18.9 % of the repo) that CD already refuses to publish, referenced by no project name and not in MeshWeaver.slnx — including 276 files of Northwind whose plugins package is a three-file shell.

🚨 Do not merge and do not arm auto-merge — this is a survey deliverable for review.

🤖 Generated with Claude Code

…he measured destination map Survey only; nothing moves. Records where each of the 996 files under src/MeshWeaver.Documentation/Data/ belongs under the maintainer's rule that documentation follows the functionality it documents, the same rule skills already follow. Settled first, by measurement against memex.meshweaver.cloud: Data/ is the SOURCE of the mesh's Doc/ nodes, not a second copy — 0 mesh-only nodes in either Doc/WhatsNew (709 disk / 702 mesh) or Doc/Architecture (161 / 159), every difference being disk-ahead of the deployed image. The partition is authored read-only, so a live edit cannot create one. What the measurement does expose is the LAG: a doc fix rides inside MeshWeaver.Documentation.dll and therefore needs a core image roll to reach any mesh. The map, by symbol residence and cost: - Doc/AI (13) moves to the AI package — every symbol resolves in MeshWeaver.AI and none in core, and the folder carries 1 executable block, so almost nothing to re-gate. The engine moved; its docs did not. - Doc/WhatsNew (709) STAYS: it is one fleet-wide feed and satellites already file into it from their own WhatsNew/ folders. Only 8.5% of entries are about non-core packages, and new ones already land correctly. - Doc/GUI (42) STAYS: a GUI doc documents the CONTROL, and controls are declared in MeshWeaver.Layout. 30 of 42 pages name zero plugins symbols, and the folder holds 84 of the tree's 132 executable blocks. - Doc/DataMesh (53) STAYS bar two departures. - Doc/Architecture (170) SPLITS per page, not per folder — ~20 module-owned pages listed with their destination and the signal that placed them. Also records the mechanism (a MeshDocs/ twin of Plugins#1060's ModuleSkillProvider needs no AI dependency at all, since every ingredient is core), the counter-list of what is load-bearing where it is (the empty-allow doc-gate, the shared CD staging script, 10 test projects, 1 527 links), and two defects: core's own doc link/embed gates live in the plugins repo, and the decentral WhatsNew lane ships ungated with three of four entries already malformed against the rules core's own test enforces. Beyond docs: samples/ is 988 files CD already refuses to publish, and holds 276 files of Northwind content whose plugins package is a three-file shell.

Copilot

Pull request overview

Adds a new Architecture documentation page that records (as a survey) the “docs follow the functionality” placement rule, including a measured destination map of the current src/MeshWeaver.Documentation/Data/ tree and a proposed mechanism for module-shipped docs, then links it from the Architecture topic map.

Changes:

Add DocsFollowTheFunctionality.md with the measured destination map, gating/dependency findings, and an outline for a MeshDocs/-style module doc provider.
Update Architecture.md topic map to include the new page under “Contributing docs”.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
src/MeshWeaver.Documentation/Data/Architecture/DocsFollowTheFunctionality.md	New Architecture doc page describing the placement rule, measured map, and implications/mechanism.
src/MeshWeaver.Documentation/Data/Architecture.md	Adds a topic-map entry linking to the new page.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

github-actions · 2026-09-01T11:21:58Z