build-gate / build (push) Waiting to run

Details

consolidate docs into documentation/ and deployment shells into deployment/

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.

2026-09-21 23:23:23 +00:00

3 KiB

Raw Blame History

Contributing to doxa-maps

Everything a contributor needs, short. Recipes live in documentation/how-to.md, lookups in documentation/reference.md, depth in documentation/architecture/.

The mental model — three zones

  library/  (@map)          plugin-designs/<map>/          internal/
  shared, parameterized ──► your map: its screens ──►    the build machine
  legend · map · controls    (.vue) + private colors,     (scripts, staging)
  REUSE, never customize     api wiring, components       NEVER touch
  per-map                    BUILD EVERYTHING HERE

Rule of thumb: local by default — code moves into library/ only when a second map genuinely needs it. One fix in library/ reaches every map on the next build.

Two ways one bundle shows many maps

Pattern A — parameterized: one .vue, many instances differing only by config (*.instances.json → the build emits one standalone page per instance).
Pattern B — multi-profile: several .vue screens in one bundle, selected by profile-config.profile.

Pick A when the maps differ by configuration, B when they differ by layout/behavior. Full walkthrough + the migration story: documentation/architecture/patterns-and-provenance.md.

The two build steps (never confuse them)

Command	What	Writes to `public/`?
`bun run dev`	HMR plugin gallery at `localhost:5173` — iterate on a map in isolation	No
`bun run build`	every bundle → `public/doxa-maps/<bundle>/<bundle>.js` + generated pages	Yes

To see a change on the served site: bun run build (or BUNDLE=<name> bun run build:bundle), then refresh. dev never updates the served tree.

Two-terminal workflow for integration work: terminal 1 bun run build:watch (rebuilds into public/ on save) · terminal 2 serves the host site / public/.

Where the bundles go

public/ is the committed web-root — serve it from anywhere and every map is embeddable from it (script tag or the generated per-map page). Same-origin vs external-CDN modes, paths, embedBaseUrl: documentation/how-to.md → "Where do the maps get served from?".

Ground rules

Never edit library/ to customize one map (bundle-private code goes in your src/).
Never bake tokens or data into a bundle — everything arrives at runtime via profile-config.
Before a PR: bun run build && bun run verify must pass (adds drop-portability + parse gates).
Colors are values, not logic: documentation/contributing/COLORS.md.

One-line recap

Copy plugin-designs/template-bundle/, change exactly four things (folder name, tag in index.js, tag/profile strings in index.html, .vue filenames), build everything inside your folder from @map blocks, bun run build, embed the snippet. That's the whole job.

3 KiB Raw Blame History