doxa-life/doxa-maps

History

Doxa Maps 9b6bcaa0fa Doc audit: five stale claims a newcomer would have acted on Audited README.md and all 35 documentation/*.md against main. Script names and markdown links were already clean — 59 documented scripts all exist in package.json, 0 broken links. What was wrong was file-map.md describing files that no longer exist, and three paths that had moved. REMOVED, all archived in `afb998f17` or earlier and still documented as current: internal/staging.js — the repo-root staging page; the plugin studio is the only entry now index.html — the same page's HTML library/composables/useDoxaSearch.js — deleted in `ea0c47b27`, and dropped from a prose list too REPOINTED: the three colour strategies documented under plugin-designs/doxa-research-map/src/colors/ live in library/colors/. THIRD-PARTY.md's two vendored files live under data/vendor/. embeddability.md's reference to the staging script now says it was archived and where the entry is. WHAT I DID NOT "FIX", because it was not broken: ~20 relative shorthand paths in the architecture docs (`composables/useMapData.js` inside a document about library/) read correctly in context, and three paths name things that are not repo files at all — a runtime endpoint (public/api/maps/token.json), a generated artifact (out/_records.json) and a placeholder (./bundle/bundle.js). Reporting those as defects would have buried the five real ones in 23 false positives. TWO MEASUREMENT TRAPS I fell into on the way, both corrected before reporting: my first env-var scan grepped only internal/, plugin-designs/ and library/ and declared 13 documented env vars unread — 11 of them are read in internal/build-lock.sh, .env.example, deployment/cloud/Dockerfile and the Go backend. And an earlier sweep of my own data files reported six "rega" hits that were all the word "aggregates".		2026-09-28 03:40:55 +00:00
..
app-wrappers.md	Document why a gate cannot import plugin source, and stop teaching public binds	2026-09-22 17:40:11 +00:00
color-strategies.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
components.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
data-sources.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
embeddability.md	Doc audit: five stale claims a newcomer would have acted on	2026-09-28 03:40:55 +00:00
file-map.md	Doc audit: five stale claims a newcomer would have acted on	2026-09-28 03:40:55 +00:00
i18n.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
patterns-and-provenance.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
poster-generation.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
README.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00

README.md

documentation/architecture/ — the deep end

Everything complex lives here, on purpose. The rest of the docs stay simple ("what it does"); when a simple doc says "full contract in architecture/…", this is where it points.

Doc	What it holds
file-map.md	every file, one line each, with the gotcha each carries
data-sources.md	the `api/` seam — connection contract + add-a-source checklist
color-strategies.md	the color-strategy contract + legend wiring
components.md	shared component catalog + shadow-DOM conventions
i18n.md	the locale contract + add-a-language checklist
embeddability.md	the generated per-map pages + manifest that make every map embeddable by default
app-wrappers.md	the SPA shell: `nav.js` + `PROFILES` contracts, `bun run shell` pipeline
poster-generation.md	the poster/preview generator pipeline
patterns-and-provenance.md	the two multi-map patterns in depth + where the design comes from

Simple docs: ../why.md · ../tutorial.md · ../how-to.md · ../reference.md · ../explanation.md