Served content#
This page explains what content ADVISOR serves, where it comes from, and how to keep it fresh.
What is served#
The handbook, policy, project docs, the WayneUI markup contract and WayneUI's 1.x to 2.x migration guide in data/ are generated from the sibling stack repositories. data/ is generated, never hand-edited: policy.json and handbook/ from CREED, projects.json from each project repo and generator/projects.seed.json (state, package, version, PHP floor), plus each project's README, best practices and any extra docs its seed names.
Each project entry also carries its version when the project publishes one (composer.json, else package.json, else the newest CHANGELOG heading).
Beyond a project's README and best practices, a seed may bundle further files under extra_docs (a map of slug to path in the project); each lands in data/docs/<id>/<slug>.md and in the project's docs list, and a missing file is skipped, not an error. WayneUI's entry bundles its MIGRATING.md as the migrating doc.
Verified at start-up#
Content is generated by content:generate and verified at start-up against data/manifest.json (a SHA-256 for every file).
Files are cleaned on the way in: line endings are normalized and invisible characters (the TAG block, zero-width and bidirectional controls) are stripped. Image boilerplate is trimmed from the project docs, on the way in and again when read_project_docs serves them: centred hero, badge and cast blocks, lone images whose target is relative or a GIF (linked or not), and rows of nothing but badges. Prose, tables and code blocks are left alone, and the bundled file itself is never rewritten at read time, so its manifest hash still holds.
Hand-written guides#
Beside the generated docs, hand-written guides are kept by hand in generator/guides/ (one Markdown file per slug), the same way the ownership table is kept. Each is bundled into data/guides/ and served as advisor://guide/<slug>; the first is "Connect to Oracle on Citadel". Edit them there, then run content:generate.
Refreshing the content#
To refresh it, with the stack repos checked out side by side:
php vendor/bin/advisor content:generate --sources=/path/to/stack
php vendor/bin/advisor content:generate --sources=/path/to/stack --check # exits 1 on drift
Run content:generate after any change that lands in CREED's policy or handbook, a project's README or best practices, an extra doc, or the projects seed. Commit the regenerated data/ with the source commits in the message.
The generator reads each project's folder from beside the other repos, so a stale clone gives stale docs. WayneUI's development happens on its GitLab repository and the checked-out copy is only a mirror of it: fast-forward the local wayne-ui clone to that repository's main before a resync.
CI cannot see the sibling repositories, so composer ci runs content:verify, which needs none of them.
Catching drift#
composer content:drift compares data/ with a checkout of the stack repos and exits 1 when they no longer agree. It takes the folder from ADVISOR_STACK_DIR; without it, it prints how to run it and exits 1. It writes nothing. On drift it lists the files that moved; regenerate with composer content:generate and review the diff before committing.
The GitLab job content-drift does the same in CI: it clones the repos listed in data/projects.json with the job token, puts them in one folder, sets ADVISOR_STACK_DIR and runs the check. It is manual or scheduled and allowed to fail, so it cannot block main. Run the drift check before every tag: a release must carry docs that still match the repos it advises on.