Repository navigation
Conversation
They are what an agent reads before touching the node database, and five statements in them were wrong: - Call sites no longer keep a legacy path each. FilesDb answers every method and FilesDbExt falls back to it; the README and the CI comment still described the old design. - The segment layout is 3, not 2. - getRaw() reads the file in daemon mode too since layout 3, so it returns the real bytes of a corrupt document instead of ''. - quanta_db.root is the site directory, which is what the image and the parity suite configure, not the site's db/ directory. - The version() example in the stub said 1.1; the contract is 1.3. The generated qdb pages of the docs site are rebuilt, which also brings in the section on running PHP as root added to usage.md.
Coding agents had no project context, so each session rediscovered the engine from the code and tripped over the same things: a new class is not found until the class map is rebuilt, a ':' in a Qtag attribute starts the target, FilesDb and FilesDbExt must answer identically, and .htaccess and the nginx vhost implement the same routes. AGENTS.md is the tool-agnostic entry point that Codex, Copilot, Cursor, Zed and most other agents read natively. CLAUDE.md imports it for Claude Code, which only reads AGENTS.md when no CLAUDE.md exists, and .gemini/settings.json points Gemini CLI at it. qdb/ and docker/ have their own, read when working there. They stay short because they are loaded into every session; docs/reference/ holds the detail they link to: architecture, content model, templates and Qtags, modules, and step-by-step recipes. A site is a separate repository, and tools that stop at its git root never see the engine's AGENTS.md from inside it. profiles/generic/ now ships a site-level AGENTS.md, which doctor setup copies into every new site and which points back to the engine reference. The top-level files are kept out of the image, whose build context is also its web root. .htaccess now refuses .md files, as nginx already does, so the AGENTS.md in a site's folder is not served under Apache. CLAUDE.local.md, the per-checkout counterpart, is ignored.
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Coding agents (Claude Code, Codex, Copilot, Cursor, Gemini CLI, …) had no project context. Each session rediscovered the engine from the code and tripped over the same things: a new class stays "not found" until the class map is rebuilt, a
:in a Qtag attribute starts the target,FilesDbandFilesDbExtmust answer identically, and.htaccessand the nginx vhost implement the same routes. The same material is also the knowledge base for the new website and user manual.What
Entry points, one per area, short because they load into every session:
AGENTS.mdqdb/AGENTS.mdown.rs), the test suitesdocker/AGENTS.mdclear_env, supervisord and entrypoint conventionsprofiles/generic/AGENTS.mddoctor setupcopies it into every new siteHow each tool picks them up:
AGENTS.mdnatively (nearest file wins)CLAUDE.mdcontaining@AGENTS.md(an import, not a symlink: Claude's edit tools refuse to write through symlinks, and Claude readsAGENTS.mdon its own only when noCLAUDE.md/CLAUDE.local.mdexists).gemini/settings.jsonsetscontext.fileNametoAGENTS.mdReference, read on demand (
docs/reference/, hand-written, not part of the docs-site build):architecture.md: boot sequence,Environment, module loading, class map, hook mechanism and the full catalog of fired hooks, caches and generated statecontent-model.md: nodes on disk, names and lookup, lineage, status, permissions, users, languagestemplates-and-qtags.md: template resolution, Qtag parser rules, writing a Qtag, the core tag catalogmodules.md: module anatomy and catalog, overrides, assets, forms, JSON actions, Shadow, API router, jobs, mail, doctorrecipes.md: checklists for a new Qtag, hook, site module, form, API endpoint, action, job type, asset, doctor command, storage method, URL routeSites. A site is its own repository, and tools that stop at its git root never see the engine's
AGENTS.md. The site template explains the site layout, templates, a Qtag cheat sheet and commands. It points back to../../AGENTS.mdand../../docs/reference/, and leaves a "This site" section for each team's own conventions. Existing sites can adopt it withcp profiles/generic/AGENTS.md profiles/generic/CLAUDE.md sites/<host>/.Serving and packaging.
.dockerignorekeeps the top-level agent files out of the image's web root. The profile copies stay, becausedoctor setupneeds them..htaccessnow refuses real.mdfiles, as nginx'sdeny-dev-files.confalready does, so a site'sAGENTS.mdisn't served under Apache..gitignoreaddsCLAUDE.local.md.qdb doc corrections (separate commit). These docs are what an agent reads before touching the node database, and five statements in them no longer matched the code:
FilesDbnow answers everything.layout_version: 3, not 2.getRaw(): reads the file in daemon mode too.quanta_db.root: the site directory, notdb/.version()example: 1.1 instead of 1.3.The generated qdb pages are rebuilt. The
image_max_doc_kbdefault was left alone, because the ini default and the Rust default differ and it isn't clear-cut.Verification
Class::method/->method()named in the new docs exists in the code. The PHP examples passphp -lon PHP 8.5.12.AGENTS.mdis 173 lines / 11 KB. The longest chain Codex concatenates (root +qdb/) is ~16 KB, against its 32 KiB default cap.npm run docs:check: all internal links resolve.doctor setup --profile=genericon a throwaway host, in the image with this branch'sprofiles/mounted: the site getsAGENTS.mdandCLAUDE.md..dockerignore: rootAGENTS.md,CLAUDE.mdand.gemini/are absent;profiles/generic/AGENTS.mdis present.AGENTS.md, so the import resolves.Not exercised here: Codex, Gemini CLI and Cursor sessions. Quick check for any of them: ask "what must you do after adding a Qtag class?" The expected answer is
php doctor <host> class_map.Noticed, not changed
docs/introduction.htmlis behindREADME.md(it has no logging section). Runnpm run docs:buildto refresh it.node_modules/andpackage-lock.jsonreach the image's web root when built from a checkout that has them./qtag/and/q/render Qtags taken from the URL, and the API router has no auth layer.