Work rules for agents
The rules an agent — or a person at a terminal — works by on a site’s files. The engine does most of the enforcing; what remains is conduct. A copy travels with every install.
The idea
Writing to the site is touching data/<type>/, theme/, assets/ and guide/ — nothing more. The machine views (JSON-LD, projections, caching) derive from the first three; guide/ holds the site’s own notes for whoever works on it. search reads any of the four (with the root’s read right), and the docs besides. The schema is the affordance list; every change is a diff; preview and undo live in the version history.
The rules
- Read the guide first, then the docs, then the index.
fetch "guide"— the site’s own rules: tone, structure, design, data conventions. The engine ships its own short advice, the same on every site, kept current;site.mdand the rest are this site’s, written by the people and agents who work here — when you agree a new rule, write it there. A key withoutguide.readdoes not see the root — ask for it. These engine docs come next, through the MCP:search { in: "docs", query }finds the page,fetch "docs/<path>.md"reads it, any key may. Then what is here:/data.md(the index as a list) or/data.json(the full form),?q=<words>on either orsearch { query }for ranked hits — and one file,data/<type>/<identifier>.json, for precision. Search before you scan: a hand-rolled walk over the files, or an index of your own, is wasted work that drifts. - Data leads. What is in
data/is the truth; templates do not translate and invent no fallbacks. - Every internal reference is a stub —
{"@type": "...", "identifier": "..."}— never a path, never a copy. - Discuss first, code later. Changing the engine is architecture and goes past the owner;
data/andtheme/are the daily work. - You do not have to commit — the history is kept for you. Every change is recorded automatically; authorship lives in your journal line.
- Project values belong in the project layer — constants in
theme/config.php, never in the engine. Server and process facts are environment, not configuration. - Every change command ends with a journal line — the command in plain English, who asked, who executed, what was touched, what changed. Through the MCP, pass what was asked as
noteon the write verb (up to 280 characters); the MCP journals actor, verb and target by itself, the note is the why. A change without a line is a timeline that lies by omission. - Destructive means naming the target. Wiping entities, files or server content needs an explicit confirmation that names them — “remove the three placeholder reviews”, not “clean up”; in doubt, show the list first.
- Drafts: stage, publish, refuse. Work that needs approval goes to the draft layer, never the live tree: stage, preview through the capability link, publish on approval, refuse by dropping. The last publish or refusal closes the round and retires the token — the next stage mints a fresh one; through the MCP, publishing also needs the right and a clean audit.
- Content per language is a language map. In data and strings always; in shared sections an inline map picked with
$m[locale_lang()] ?? $m[SITE_LANG_DEFAULT]— never comparelocale_lang()to a literal (the audit warns: it makes one language special and falls silent on a new one).
The one rule for pages
Give an entity a slug and it is a page: a path (leading slash optional, non-empty, no extension, depth allowed but no tree semantics), a language map for translated paths, or one invariant string. The shell follows from the type or presentation.shell — see How a page finds its shell. Home is data/webpage/home.json, without a slug. No route line, ever — theme/index.php is for redirects, POST handlers and deliberate overrides.
No slug does not mean private. Every live entity is public through the index, the graph and its own file address under /data; only what may be on the street belongs in data/. And data is not a slug: a page cannot claim /data or anything under it.
Recipes
New page. An entity in data/<type>/<identifier>.json, canonical schema with a slug and a description (without one the page stays out of llms.txt); a line in a curated list only where the site keeps one by hand (the guide says which — overviews that read the index list it on their own); optionally a bespoke shell. A new type needs no setup — the first create under data/<type>/ opens it. Audit; journal.
New article. An entity with articleBody — the type shell picks it up, the sitemap line follows, an index-read overview lists it; a curated list gets a line only when the site keeps that list by hand. Image optional, as an ImageObject with name and caption. Audit; journal.
URL change. Change the slug (sitemap, language links and @id follow) and add a 301 in the redirect table for the outside scope. Update internal references in the same round; the audit reports links that still take the detour.
Audit before it travels
Every publish runs an audit: broken references, missing required fields, bad links or template syntax block it, and the MCP tells you what failed. A targeted publish audits only the drafts in it; an unpublish checks what removing a live path would break. Catch it before you publish — stage, preview, let the audit pass.