D34. A course's rules for agents follow the Elabora that runs; an author's edits are never overwritten (13 Oct 2026) · For developers

elabora init copied AGENTS.md once: after an update, older courses kept rules that did not know the new tools, and the « Nietzsche » session, running the app’s older bundled CLI in a course whose rules came from a newer one, looked for commands that were not there. Options weighed: a versioned template that Elabora refreshes when unedited; a short, stable AGENTS.md that points to a command printing the current rules (always in step with the CLI that runs, but agents read their instructions file at the start and do not always run a command first, and a course read without Elabora would lose its rules); both. Originally chosen: the full rules stayed in the file, kept up to date, and the command printed those of the running CLI.

The file (@elabora/node agent-rules.ts): the rules between  and , then « Notes for this course », the author’s and agents’ own part, which Elabora never changes. The marker says which revision of the template the block is and a fingerprint of its text, so Elabora tells rules nobody edited from edited ones. templates/agents-revisions.json lists every revision of the template (27 found in the repository’s history, from 5 October), appended by npm run gen when the template changes; an AGENTS.md written before the markers is recognised by its whole text (five of the six modules of the library it was tried on were unedited copies; the sixth, imported from an intermediate version, is left and reported).
Brought up to date without asking when unedited, as a system change (update_agent_rules) that elabora undo reverts: when the app opens the course (the engine, after a format migration if any), when an MCP server starts in it, and when any elabora command runs in it (the note on stderr, outputs unchanged); elabora migrate writes them with the format. Edited rules are left as they are and said once a command runs (elabora rules update --force replaces them, the notes kept). An older Elabora meeting rules of a newer one (a revision it does not know) says that the commands they name may be missing and writes nothing: the opposite check.
elabora rules prints the rules of the running CLI and where the course’s stand; elabora rules update [--force].
The examples and the test courses carry the current rules (npm run gen rewrites theirs, a unit test checks it), so tests do not write them. Revisit if: authors want to keep Elabora’s rules and change one of them (a per-rule override in the notes), or the rules grow too long for agents’ context (then the short file pointing to elabora rules becomes the better trade).

17 Oct 2026: progressive disclosure

Course rules outgrew their purpose as an always-read file. The marker/fingerprint/revision and author-note lifecycle is unchanged, but the current template is a compact invariant checklist and task router. Long recipes now live in opt-in skills and references, shipped with the CLI and exposed as MCP resources. elabora tools skills [name [reference]] provides the CLI-only equivalent. The authoring/design skills are short entry points; narration, translation and Storyline/Rise import are separate skills. MCP instructions point to the rules and skills rather than restating policies. Existing courses with unedited rules upgrade to the new revision; edited blocks and author notes are preserved. Old revisions remain in history.

19 Oct 2026: what the split dropped, restored

A review of the split found D52 still taught correctly and a few rules lost or weakened. Revision 8 gives them back in one line each, without growing the file: after a validation the agent keeps writing the plan and tells the author what changed (elabora plan diff); a change of substance is the author’s call; no Playwright script to see a screen (elabora look, elabora preview, elabora screenshot); sources may hold personal data, quote only what the module needs. « The repository-root AGENTS.md governs… » is gone: an author’s course folder has no repository root, and the developer’s AGENTS.md already points here. Skills are also read through elabora_docs (D53).

29 Oct 2026: a CLAUDE.md beside AGENTS.md

Claude Code reads a folder’s AGENTS.md only when it finds no CLAUDE.md or CLAUDE.local.md in that folder or above it, and only since its version 2.1.277. The app is covered: its request to the agent and the MCP server’s instructions name AGENTS.md. But Claude started by hand in a course kept under a folder with its own CLAUDE.md read that file and skipped the course’s rules. So a course has its own CLAUDE.md, whose one line @AGENTS.md imports the rules (the founder, 29 Oct).

Where it is written. elabora init, a module made from a template and a Storyline/Rise import write it beside AGENTS.md. A re-import keeps the author’s. A course that has AGENTS.md and no CLAUDE.md gets it by the path of the rules: a command run in it, an MCP server starting there, the app opening it, a migration. It is part of update_agent_rules, the same system change that elabora undo reverts. pnpm run gen writes it in the examples, the module templates and the test courses, so that tests write nothing there.
Never over an author’s. A CLAUDE.md that is there is left as it is, whatever it says, even under --force. Without AGENTS.md, nothing is written.
Like AGENTS.md, it stays out of what learners get. SCORM and web builds, and so what elabora publish uploads, leave both out, and validation does not read them. It is a file of the module, though: backups, the .elabora archive, and the copy a translation is made in carry it.
No warning in the app about edited rules. Only agents read AGENTS.md, and they always go through the CLI or the MCP server. Both tell them, which is the founder’s call. The note now says what elabora rules update --force does: it puts the current rules back, loses what was edited in them, keeps the notes, and can be undone. The MCP server also puts the note in its instructions, because a host keeps a server’s stderr in its logs, where the agent never reads it.