Sub-sites on `culture.dev`

AgentCulture projects whose primary docs site should live under the shared culture.dev origin — so navigation between them is same-origin, cache hits survive cross-project jumps, and external links live at one canonical host — follow a single reference pattern. culture.dev/agex/ is the live path-prefix example; zehut and shushu will follow.

Status (2026-05): culture.dev is now served by a single Cloudflare Worker from the katvan build, and several projects’ docs are aggregated directly into that build rather than deployed as separate path-routed Pages projects. The afi and citation-cli sub-site entries were pruned from the sitemap index and _data/sites.yml because their /<project>/sitemap.xml URLs returned the main-site HTML instead of XML (dangling index entries that triggered Search Console read errors). The separate-Pages scaffold described below is the historical reference and needs reconciliation against the in-build-aggregation model — settle that before wiring a new sub-site.

The rest of this page documents that scaffold — the exact edits a sub-site needs on the project side and the culture side. Per the status above, treat it as the historical separate-Pages reference: it records how the wiring worked, not a green-lit path for a new sub-site until the in-build-aggregation reconciliation lands.

When to make a project a sub-site

The project is an AgentCulture first-class namespace (e.g. culture afi, culture devex) and wants a public docs home.
The project’s docs are natural neighbours of the other culture.dev/* sub-sites — agents and humans should be able to navigate between them without leaving the origin.
The project is comfortable deploying via Cloudflare Pages with its docs rooted at a path prefix (baseurl: /<project>), not a subdomain.

If any of those don’t hold, keep the project’s docs on its own origin and cross-link via rel=related only.

Reference scaffold (project side)

Mirror the afi-cli scaffold (agentculture/afi-cli#7) or the earlier agex-cli scaffold it was modeled on. Both are blessed; new sub-sites should start from the afi-cli version because it includes the later refinements.

Required pieces in the project repo:

docs/_config.yml — Jekyll config with url: https://culture.dev and baseurl: /<project>. Path-prefix hosting, not subdomain.
Theme: just-the-docs (matches the rest of the culture.dev family).
Plugin: jekyll-sitemap so /<project>/sitemap.xml generates automatically.
docs/_includes/head_custom.html — rel=related back-links to the other culture.dev sub-sites (optional but recommended).
.github/workflows/docs.yml — builds docs/ and deploys to a Cloudflare Pages project named <project>. See the afi-cli workflow for the canonical job shape.

Not in the project repo:

The Cloudflare Pages project itself, custom-domain binding, DNS records, Worker / Redirect Rule for path routing — tracked in agentculture/cloudflare.

Reference scaffold (culture side)

Every sub-site touches exactly five files in this repo. The diff for culture.dev/afi/ is the canonical example (PR #289); the agex entries in the same files are the prior example.

File	Edit
`_data/sites.yml`	Add `<project>: https://culture.dev/<project>/`. Centralises every cross-site URL so links never hard-code the origin.
`_config.culture.yml` (`aux_links:`)	Add `"Display Name": - "https://culture.dev/<project>/"` — shows up in the top nav bar.
`_config.culture.yml` (`footer_content:`)	Add a one-line description + link, parallel to the agex / afi entries.
`_includes/head_custom.html`	Add `<link rel="related" href="{{ site.data.sites.<project> }}" title="Display Name">` so cross-site discovery is declarative.
`sitemap.html`	Add a `<sitemap>` entry pointing at `/<project>/sitemap.xml` (see the `afi` and `agex` lines in this file) so search engines see the sub-site.

That is the whole culture-side cost. No _config.culture.yml routing block is needed — the path prefix is served by Cloudflare, not Jekyll.

Required edits vs. optional

All five culture-side edits above are required for a sub-site to be considered properly wired. A sub-site that skips rel=related or sitemap.html is “reachable but not discoverable” and should not ship.

On the project side, just-the-docs and jekyll-sitemap are required; everything else (landing-page content, rel=related back-links, custom head_custom.html tweaks) is project-specific.

Checklist for a new sub-site

Land the Jekyll scaffold in the project repo (model on afi-cli’s docs/ + .github/workflows/docs.yml).
File the Cloudflare companion issue in agentculture/cloudflare asking for the Pages project + path routing.
Open a PR against this repo adding the five file edits above. Reference the Cloudflare issue in the PR body so ordering is explicit (the Pages project must exist before nav links go live, otherwise the aux-link 404s).
After merge, verify https://culture.dev/<project>/ returns 200 and `curl -sI https://culture.dev/sitemap.xml | grep /sitemap.xml` finds the sub-sitemap entry.

Sub-sites on culture.dev