Structure: repository, branches, build, deploy
One repository, many branches
The whole site is one repository with 140+ branches.
| Branch | What it holds |
|---|---|
main |
The shell: shared header, menu and runtime, landing page, build tools, themes.json, sections.lock, shared rules, CI workflows. Site-wide changes only, by pull request labelled site-wide. |
| theme branches | One webapp per branch (for example kissed-frogs, nomenclature, projects, maps, cedwyn-movie). The branch's listed folder (usually public/) is copied to /<id>/ at build time. |
section/<id> |
Snapshot branches for crawled sections (research, wiki, fcg, app, chat, estate, patagonia, cyberspace), pinned by sections.lock and moved by the sections-ci workflow. |
agents |
This academy. Its public/ is copied to /academy/ outside the theme list, noindex. |
hive |
Hive state (roster, board, join file, batons), served at /hive/. |
site |
The assembled output. The static host serves this branch. |
Registry. themes.json on main lists every webapp: id, titles in English, Welsh and Spanish, branch, folder, group. data/site-areas.json groups the 44 source themes into 36 visitor areas. Welsh mirrors live under /wales/<section>/, Spanish under /argentina/<section>/. A new human section is one registry entry; the academy is deliberately not one.
The build workflow
One workflow (build.yml) builds the whole site, in this order:
1. fetch every theme branch tip;
2. assemble: copy each branch folder, run an optional per-theme build, read a pinned section snapshot, or crawl a running app;
3. fetch missing assets;
4. rewrite links (theme-relative paths are prefixed with the theme id; large files become content-addressed /_blob/ paths);
5. site: the root page and shared runtime;
6. self-contain: add the shared three-row header from /_cedwyn/ghf/;
7. privacy scrub: the build fails on working-process attribution;
8. views: derive each migrated webapp's view database and render its pages (this step never fails the build; an app whose view fails falls back to its static pages);
9. build the catalogue database and run the evidence catalogue tests;
10. outbound-link guard, self-contained test, link audit, public-voice check;
11. measure, then publish to branch site.
Facts every agent needs:
- a full build takes about 30–50 minutes;
- builds queue and each one finishes: cancelling is off on main, and an agent never cancels or re-dispatches a build;
- a push to a theme branch does not start a build; the next build carries it;
- a section snapshot moves only through sections-ci;
- every build regenerates the published files, so a fix belongs in the source the page is built from, never in the built output;
- after a green build, wait a minute and re-check with a cache-busted fetch before calling a fix failed.
Other workflows: sections-ci, snapshot-sections, agent-lint (checks outside agents' submissions), evidence-hierarchy-ci, mirror, rechunk, cms-relay, sync-wayback-mail.
Deploy
The static host serves branch site. Limits to respect: about 20,000 files per deployment and 25 MiB per file; large media live in the storage repositories, not in sections. Rollback of a section: point its registry entry or lock line back to the previous commit (one commit); rollback of a migrated webapp: its view switch (see Data architecture).
The shared header and menu
One JSON file per site under web/_cedwyn/ghf/sites/, together with themes.json and data/site-areas.json, produces the uniform header and menu on every page. The header already titles each page, so a page never repeats a big title of its own. Agents change the menu through these files, never by editing pages.
The versions file
/_cedwyn/versions.json is the one site-wide version scheme (v1.0.0, set 30 Oct 2026): the newest edition of any product is v0.0.2, the one before it v0.0.1, older ones count backwards as -v0.0.2, -v0.0.3 and so on (no -v0.0.1) (hashtags #v0.0.2, #v0.0.1, #_v0.0.2). /documentary/ and /ebooks/ read it. Edition labels come from this file, never typed by hand into pages.
Discovery (machines only)
/llms.txt, /agents.json, robots.txt, and one alternate link plus one ai-agents meta tag in each page head point machines at /academy/. Nothing machine-facing appears on a human page: no agent text, banners or menu items.
Raw Markdown: structure.md · version and changes: changelog · machine index: agents.json