History

doxa-maps 8fcb187f36 Some checks are pending build-gate / build (push) Waiting to run Details Gate: no machine-specific path may enter tracked source The repo is clean -- git grep over every tracked file returns zero /home/ paths. That is a real hand-off property: a clone works on any machine, which is what "the path Doxa inherits" requires. But nothing enforced it. Proven by experiment: a /home/lk10x/... line planted in internal/settled-tree-gate.mjs passed check:public-hygiene, check:parse AND check:quoted-scripts. The tree was clean by accident, not by construction. This is the worst failure shape for a hand-off. An absolute path works perfectly for whoever wrote it and breaks only on the inheritor's machine, so no test run by its author can catch it. The sibling ideation tree already paid that cost: two docs cite a workspace root that no longer exists, so a reader following them silently finds nothing. Not a flag on check:public-hygiene, which already detects these patterns but walks a SERVED tree where node_modules never exists -- pointed at the repo root it produced 1,427 findings, nearly all from node_modules/.vite. Its scope is right for its job. This scans `git ls-files`, the set a clone actually receives, which excludes node_modules and build output with no ignore list to maintain. Negative-tested three ways: the exact planted path that beat three other gates now FAILS with file:line; a /Users/ path in a doc FAILS; a checkout with too few tracked files FAILS rather than passing vacuously. Wired into build:unlocked and confirmed running inside a full build (783 files, exit 0). It then caught its own documentation -- my reference.md row quoted the literal patterns as examples. Rewrote the example rather than allow-listing the file, which would have blinded the gate to a real path in the repo's largest doc.		2026-09-22 06:34:27 +00:00
..
architecture	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
assets	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
contributing	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
readme-images	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
screenshots	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
CONTRIBUTING.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
develop-a-plugin-and-see-it-live.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
explanation.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
how-to.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
README-embed-example.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
README-longform.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
README-SECTION-3-cli-commands.md	Gate: no machine-specific path may enter tracked source	2026-09-22 06:34:27 +00:00
README.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
reference-capability-exemplars.md	Generate one canonical exemplar per tier, so a miscitation is copy-paste to fix	2026-09-22 05:35:03 +00:00
reference-library-index.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
reference.md	Gate: no machine-specific path may enter tracked source	2026-09-22 06:34:27 +00:00
slide-deck-outline.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
tutorial.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00
why.md	consolidate docs into documentation/ and deployment shells into deployment/	2026-09-21 23:23:23 +00:00

README.md

documentation/ — pick your path

        "what is this?"          "teach me"        "how do I …?"       "look it up"      "all the detail"
             │                       │                   │                  │                  │
         why.md  ──────────►  tutorial.md  ────►  how-to.md  ────►  reference.md  ───►  architecture/
        (2 min, 1 diagram)   (first map)         (task recipes)     (tables)           (contracts)

why.md — the problem and the "map islands" idea. Start here.
tutorial.md — build your first map, no jargon.
how-to.md — recipes: embed, iframe, SPA, colors, CDN, mobile, tokens.
reference.md — config fields, build scripts, the profile-config contract.
explanation.md — the model in 15 lines.
architecture/ — the deep end: full contracts, the per-file catalog.
README-embed-example.md — the drop-in README used when this bundler is embedded inside a host repo.

Nothing on the simple path is longer than a few minutes; everything complex lives in architecture/, linked from where you'd need it.