The repo is built by several people at once against a single branch,
and nothing in the README said so. The new section carries the
concentric-rings diagram and states the rule that makes it work: a
builder captures main before pushing, resolves every conflict while
holding it, then releases.
Placed before "Repository layout" — it answers the question a reader
has after seeing the studio and before reading a folder list.
The three hand-off README items the definition-of-done still listed:
(1) the map-cruncher hero -- an honest ASCII flow of the product's
whole argument (many maps -> one library -> one build -> five
targets); (2) the two 2026-09-24 certification screenshots showing the
ENTIRE cap-5 app rendering on a foreign host page via iframe and via
JS embed, with the host-page contract note (window.MAP_TOKEN + CORS);
(3) an annotated repo tree naming the free zone, the shared @map zone
and its high bar, and what the build output is.
Driver: 'showcase the capabilities from capability five down to
capability one using screenshots from real maps' -- ordered by
ADVANCEMENT, not complexity ('we don't want to scare people'). The
section now opens on the cap-5 app shell and walks down; the ladder's
point (every rung below stays independently embeddable) is stated up
front.
Four flagship images refreshed to today's product: cap-5 shell now
shows the galaxy globe + Vertical Legend + current nav; cap-4 UPG-100
opens on the Prayer Resources poster wall (the Driver's tab-one
ruling); cap-3 research map and cap-2 prayer preset re-shot current.
The old shots predated the rename, the greyscale ramp and the globe.
TWO RULES THAT WERE COSTING REAL TIME.
1. A FULL BUILD IS NOT NEEDED TO SEE A CHANGE. Agents were running the minutes-
long `bun run build` for edits the dev server hot-reloads. Documented `bun run
dev`, plus the parallel-safe form.
The trap that makes the parallel form mandatory: Vite's default behaviour on
a busy port is to silently move to the next one, and FIVE gates have 5173
written into them (check-facet-changes-map, plugin-gallery-smoke,
smoke-studio, generate-gallery, check-scrim-covers-viewport). A second dev
server without --strictPort therefore leaves those gates talking to somebody
else's server, or to none, reporting a confident wrong answer with no error.
Verified: `--port 5299 --strictPort` serves 200 on root and on the registry,
and a duplicate on the same port exits 1 instead of drifting.
2. A LOCAL COMMIT IS INVISIBLE. The Driver runs a laptop watcher against the
Forgejo repo and sees changes in the browser from THAT repo, so work that
stops at `git commit` has not been delivered however well it was verified.
Documented the push, with the credential kept out of .git/config and filtered
from output.
Also documented the follow-up nobody expects: after pushing to an inline URL,
`git log @{u}..` still reports the commits as unpushed, because git only moves
a remote-tracking ref when it pushes to a NAMED remote. That read as "63
unpushed commits" on a branch that was fully pushed.
check:doc-scripts passes, so every command quoted here exists in package.json.
The build lock protects a second WRITER. It does not protect a READER, and
nothing in the docs said so. Every build starts with `bun run clean`, which
rm -rf's public/doxa-maps, so anything reading the tree mid-build gets a
confident wrong answer: "that bundle is missing", "the dashboard tab does not
exist", "461 files were deleted". Each of those has actually happened here, and
one nearly produced a bug report against a correct change.
check:settled already existed and was already wired in package.json. It was
mentioned in zero markdown files, which is the whole gap: the primitive was
built and never reached the people who needed it. Documented now in the one
place an inheritor reads, with the instruction to grade it by exit code --
like every gate here it prints teaching prose after its verdict, so `| tail -1`
inverts the signal.
Also recorded why a pgrep check is NOT a substitute, because that is the form
the standing brief prescribes and it is the weaker instrument. A process list
samples an instant; the lock knows the queue. Between one queued build finishing
and the next acquiring the lock there is a real window where zero build
processes exist and the tree is about to be wiped -- and a long quiet period
makes that window look more convincing, not less, since the queue is idle
precisely because it is between runs. Measured today: pgrep reported 0 builders
while the gate reported builders=1 waiters=1, and ps confirmed a build had
started 17 seconds earlier.
Verified by execution: check:settled exits 1 with builders=1 waiters=1
churn(45s)=456 while a build runs; check:doc-scripts passes, so every command
quoted here exists in package.json.
Checkpointing thirteen files of agent work that were sitting uncommitted while three
agents wrote to a live tree the Driver was watching through hot reload. Uncommitted work
is work at risk, and a tree being edited under an observer oscillates between states that
look like regressions and are really just partial saves.
The second capability-5 shell now mounts its tabs as real elements too, so no iframe
remains in either shell. It was the last holdout: eight tabs, all iframe mode, each
pointing at a hardcoded built-tree leaf that does not exist under the dev server.
The facet rail keeps its shape when a filter narrows it. Selecting one place took the
rail from sixty-six rows to twenty-one — forty-six rows deleted, none dimmed — so the row
a user was about to click vanished under the cursor, which is what "the buttons went
dead" actually was. Rows whose count falls to zero are now re-admitted at their original
slot and depth, dimmed and inert, which also restores the component's own promise to lose
nothing against the tree it replaced.
Expanding a branch and filtering by it are now separate, visible affordances: the whole
row filters, and expand is a real button with its own hit area and label. Rows that were
never clickable are unmistakably inert rather than silently ignored.
Three more facet axes reach the grid — affinity bloc, engagement status and primary
language — each verified to share a field with an existing prop rather than being mapped
on name resemblance. Two derived facets remain unmapped on purpose: they have no matching
row field, and mapping them would filter confidently to the wrong rows.
Driver 2026-09-21: 'a folder called deployment which will store the capacitor
folder, wordpress folder and tauri folder', and 'a folder called documentation
to store the contributing folder so docs are in one place'.
docs/ + contributing/ + CONTRIBUTING.md -> documentation/ (three doc homes into
one). capacitor/ + wordpress/ + src-tauri/ -> deployment/.
The public/ -> dist/ rename the Driver asked about is NOT here: after seeing the
measured blast radius (855 tracked files, 54 source refs, and public/ is the
served web-root four consumers point at) the Driver withdrew it - 'keep the
public folder the same'.
Path references were rewritten mechanically (258 across 87 files), but three
classes needed hand fixes because a prefix regex cannot see them:
- join(ROOT,'docs',...) in 10 internal scripts - a quoted SEGMENT, not a prefix
- tauri frontendDist '../public' -> '../../public', since src-tauri is now one
level deeper; check:tauri caught this exactly as the card predicted
- the WordPress contract test's dirname(__DIR__,2) -> 3, same reason
Also reverted one over-reach: the rewrite renamed a FINDING-CATEGORY label
'docs' in public-hygiene-check.mjs, which is a rule name in its own header, not
a path.
Verified: full build ALL GUARDS PASS, SRI consistent; check:tauri, check:mobile
(cap sync + webDir OK), check:wp-embed, quoted-scripts, capability-citations,
capability-exemplars, library-index, public-hygiene, parse and drop all pass.
tauri build produced target/release/doxa-maps-desktop (65 MB ELF) and a 58 MB
.deb (Package: doxa-maps, Depends: libwebkit2gtk-4.1-0 libgtk-3-0). tauri info
reports the environment fully green and correctly detects frontendDist
../public, Vue.js, Vite.
The web tree is compiled INTO the binary rather than shipped as files, which is
why the .deb holds only 6 entries - confirmed by 19 distinct embedded
doxa-maps/... asset paths in the ELF and by size (a logic-free shell is 65 MB
only because the 132 MB public/ tree is compressed inside it).
bundle.targets narrowed from all to deb: rpmbuild and linuxdeploy are absent
here, so all would fail two of three formats at the END of a ~6-minute release
build.
The CLI is a devDependency (@tauri-apps/cli, prebuilt binary) rather than
cargo install tauri-cli, which compiles from source.
Status stays BUILT, NOT SHOT. The GUI launch is unverified because this box is
headless - the binary panics in tao with 'Failed to initialize GTK', the
absence of a display rather than a defect, and no Xvfb is installed.
Three docs said the config lives at the repo root - true when written, false
since the move, and exactly the real-but-wrong-target shape: a reader follows
the path, finds nothing, and cannot tell whether the feature exists.
Status upgraded from 'rustc parses main.rs' to what was actually measured:
cargo check finishes with 0 errors and 0 warnings across 400+ crates. Still
'built, not shot' - no packaged binary has been launched.
Five places across three docs still said method 5 was aspirational / not yet
scaffolded / a deferred POC. All were true this morning and all are now false:
tauri.conf.json, src-tauri/ and check:tauri exist.
The honest-ledger table moves from 2 proven / 2 built-not-shot / 1 aspirational
to 2 / 3 / 0, and its closing sentence is corrected - with nothing aspirational
left, 'the two lower states' no longer described the table.
Status is deliberately BUILT, NOT SHOT and never 'proven': proven is reserved
for methods 1 and 3, which have live artifacts. No desktop binary has been
emitted here. Section 3 now carries the runnable contract command, the
one-build-four-consumers framing, and the token/CORS caveat up front.
Three places told a plugin author their work compiles to public/<name>/. That directory
does not exist. The build emits public/doxa-maps/<bundle>/<bundle>.js, where the
doxa-maps segment is the output tree name from vite.doxa-maps-build-config.json — not the
plugin's name and not this repo's folder name. The doc conflated two different <name>s
and sent a receiver looking somewhere empty.
One of the three lines carried its own contradiction: it wrote public/<name>/ and
public/doxa-maps/manifest.json in the same sentence.
Left the reference.md occurrences alone. Both say "output tree" explicitly, so <name>
correctly means the configurable tree name there rather than a plugin.
The layout section now also states the contract plainly, since that is what a hand-off
reader needs: write inside plugin-designs/<your-map>/, run the build, and it appears in
the output tree with no registration step. Every concrete path in the README was then
resolved, and both template forms checked against a real bundle.
The CAP 1 slot shot doxa-vision-card, which is not a single element: it ships
doxa-vision-card.instances.json with two instances, so discover.mjs types it
parameterized and manifest.json records "parameterized" — capability 2.
The same error had already been found and fixed in verify-5-capabilities.mjs, whose own
comment records that it had been sampling cap-2 twice and cap-1 never. That fix landed in
the gate and never reached the README: two artifacts encoding one fact, with nothing
forcing agreement. Fixing one copy was not fixing the fact.
all-people-groups is a genuine cap-1 — one .vue, no instances file, manifest type single.
The README now also says what decides the tier, since the folder's apparent simplicity is
the trap: doxa-vision-card looks like the lightest thing in the repo.
check:capability-citations compares every README capability claim against the manifest,
blocking in CI. Its first matcher used \Z, which is not JavaScript, so it matched zero
sections while still reporting a citation count — a gate reporting a number it had not
verified. It now splits on headings and the count reflects real matches.
The badge read "27/26 zones" — a count exceeding its own total — in two shipped README
screenshots. 26 was the leaf count before slice 09b-6 added the Frontier-Asia uncovered
rows; the literal was never updated, so it drifted the moment the data grew. The
denominator is now derived from perZone.size, which tracks the zone list automatically
and cannot disagree again. Measured from clusters.json: 13 regional + 12 asia + 2
uncovered + 1 deaf = 28. The corrected badge also surfaces 1 genuinely unresolved zone
that the stale denominator was masking.
legend-tree.js asserted "33 leaves" and "7 Frontier-Asia uncovered" in a comment; the
shipped data carries 28 and 2. Corrected to point at the arrays instead of a count.
README showed "List — page 1" and "List — page 2" as the same picture. The shot loaded
one URL twice and tried to reach a page 2 by scrolling and clicking Next; neither exists,
the list has no pagination, and every attempt sat in try/catch so the miss was silent.
The PNGs differed by 0.16% render noise, so no checksum would have caught them. Mean-
while poster-wall — a real manifest-listed profile — had no screenshot at all. Shoot the
real third thing rather than fake a fourth.
check:shot-distinctness gates this, blocking in CI. It keys on url+viewport, so the
deploy2 mobile shot of the same SPA stays legitimate rather than a false positive.
README drew the two cap-5 products apart in prose and even warned that captioning a
studio shot as the product SPA is a documented mistake — then filled its plugin-studio
slot with cap5-doxa-maps-spa.png. Both cap-5 figures showed the same app and no
plugin-studio screenshot existed anywhere in the repo.
A slot filled with the wrong real image looks exactly like a correct one; nothing 404s.
So the fix is to shoot the missing artifact, not re-caption around the gap. Both cap-5
slots now use generated, freshness-gated images.
Also adds check:shot-fidelity. The shot run reported 13x OK while every emoji rendered
as a tofu box: this machine has no emoji font. Measured rather than assumed — the DOM
carries 27 correct codepoints, so the markup is right and the defect belongs to the shot
machine. Reports by default because installing a font is a Driver call; --strict blocks
once one is present.
- internal/playground → internal/plugin-gallery; playground-smoke → plugin-gallery-smoke;
generate-spa → generate-gallery (scripts: gallery, smoke:gallery; smoke:playground stays as alias)
- generate-gallery exports renderGallery(model, { mode }) — the dev plugin serves the same page
at / from the discovered registry (dev mode imports the dev entries, ladder popovers on);
the build writes public/index.html from the manifest (byte-identical to before)
- Docs and probes use the gallery vocabulary
A global prayer movement cannot run on one website: coverage stalls when there
is one place to see the task and one place to sign up. The opening now leads
with that insight and the fix (the same living map on every partner team's own
site — ownership breeds stewardship), trains three roles in the T4T spirit
(map maker / map multiplier / prayer mobilizer, t4tonline.org), and adds THE
PLAYBOOK: list partner teams -> keep the list in a secure collaborative CRM
(Disciple.Tools; the list is an attack surface) -> commission mobilizers ->
embed everywhere (Share button + utm attribution) -> train the trainer. The
craft story, glossary and quickstart remain for the map-maker persona.
- ShareButton resolves its link from where the bundle is hosted (profile-config.shareUrl ->
embedBaseUrl -> window.MAP_EMBED_BASE_URL -> the bundle's own script URL); profiles pass
tree-relative embed pages, so links work in the playground, on doxa.life and on any CDN
- Generated leaf pages try token endpoints in order (override -> configured absolute URL ->
same-origin) and only then offer the paste-once box; build config points at the canonical
https://doxa.life/api/maps/token
- Dev playground extracted from vite.config.js into internal/playground/{discover,render,dev-plugin}.mjs;
serves /assets/* like the built site so data-driven maps initialise; passes assetsBase +
shareUrl to every element; header ladder with a Start-here primer and the five kinds of
mounting files (single-element, preset-element, multi-view-element, composite-element, app-shell)
- New gates: smoke:playground (every element boots, with status text + data diagnostics),
smoke:share (Share URL resolves and reopens the same map), sync:dropin (mirror public/ into a
host checkout, never credentials), deploy:dev (build + sync)
- MapToolbar + ShareButton on every map profile; UPG-100 composite (map + prayer lists) on the
pane layout; shared --map-radius token consumed by the legend components
- docs/reference.md: profile types table, profile-config assetsBase/shareUrl/embedBaseUrl, gates
- The build now emits public/_headers implementing the embeddability split
(direct-embed pages framable anywhere; staging preview-only) — Netlify/CF
Pages consume it automatically; serving/traefik-embed-headers.yaml is the
proxy-side reference. The contract is auditable in-repo, not just documented.
- README: docs table gains how-to, layouts/README (the SPA machinery), and
docs/architecture; Quickstart gains bun run serve + bun run phone.
The headline capability was buried mid-bullet. Now the opening leads with it: one
build composes all your maps, tables, and dashboards into a single-page app that
runs as a website, installs as a mobile app, and embeds on partner sites — with
side-by-side desktop + phone screenshots of the composed SPA as proof.
Also: the story gains the collapsed-platform / mobile-dream beat, and claims are
squared with the audit (Vue is what ships — React concepts transfer; Android
project committed today, iOS scaffolds via Capacitor).
Reorder sections so it reads like a journey (indirect, no cheesy labels): the dream
+ the wall you hit → the language (glossary) → what you get → the powers → the honest
decision → the commitment → first steps → the data caveat → docs → the mission.
Same ideas + section content; only the order changed so the most impactful part (the
story) leads.
Lead with the one-liner + the two commands immediately after the tagline; punchier
bullets; condensed the data caveat. Same content, fewer words, essence first.
- README rewritten as a BLUF-first vision cast for vibe coders (key-terms glossary,
origin story, features, requirements, data caveat, developer's note).
- library/components/WARNING.md: prototype in your app-profile; only proven,
parameterized components graduate into the shared library.
- generate-tree.mjs: inject Subresource Integrity (sha384) + crossorigin into the
standalone page <script> tags and the copy-paste embed snippets (manifest = registry).
- Scrubbed identity-tied phrasing from comments/docs, keeping the technical rationale
and the mission content.
Standalone repo that builds embeddable JAMstack map bundles (web components),
composes them into a lazy-loaded SPA via layouts/, and optionally wraps a
Capacitor Android/iOS app — one build, choose your output/CDN. Diátaxis docs.
History reset to a single clean commit; no PII, IPs, or internal terms.
