Skip to content

Add agent instructions and an engine reference - #659

Open
daylioti wants to merge 2 commits into
masterfrom
agent-instructions
Open

daylioti wants to merge 2 commits into
masterfrom
agent-instructions

Conversation

@daylioti

@daylioti daylioti commented Nov 6, 2026

Copy link
Copy Markdown
Collaborator

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, FilesDb and FilesDbExt must answer identically, and .htaccess and 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:

File For
AGENTS.md the engine: repo map, commands, how a request runs, the rules that bite, code style as practised, security notes, definition of done
qdb/AGENTS.md the Rust extension / daemon: PHP-free modules, format versions, contract sync, root-owned creates (own.rs), the test suites
docker/AGENTS.md the image: pins, multi-arch, deny snippets, clear_env, supervisord and entrypoint conventions
profiles/generic/AGENTS.md building a site; doctor setup copies it into every new site

How each tool picks them up:

Tool Mechanism
Codex, Copilot, Cursor, Zed, Windsurf, Junie, Amp, opencode read AGENTS.md natively (nearest file wins)
Claude Code CLAUDE.md containing @AGENTS.md (an import, not a symlink: Claude's edit tools refuse to write through symlinks, and Claude reads AGENTS.md on its own only when no CLAUDE.md / CLAUDE.local.md exists)
Gemini CLI .gemini/settings.json sets context.fileName to AGENTS.md

Reference, 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 state
  • content-model.md: nodes on disk, names and lookup, lineage, status, permissions, users, languages
  • templates-and-qtags.md: template resolution, Qtag parser rules, writing a Qtag, the core tag catalog
  • modules.md: module anatomy and catalog, overrides, assets, forms, JSON actions, Shadow, API router, jobs, mail, doctor
  • recipes.md: checklists for a new Qtag, hook, site module, form, API endpoint, action, job type, asset, doctor command, storage method, URL route

Sites. 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.md and ../../docs/reference/, and leaves a "This site" section for each team's own conventions. Existing sites can adopt it with cp profiles/generic/AGENTS.md profiles/generic/CLAUDE.md sites/<host>/.

Serving and packaging.

  • .dockerignore keeps the top-level agent files out of the image's web root. The profile copies stay, because doctor setup needs them.
  • .htaccess now refuses real .md files, as nginx's deny-dev-files.conf already does, so a site's AGENTS.md isn't served under Apache.
  • .gitignore adds CLAUDE.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:

  • Legacy path per call site: the README and the CI comment still described one; FilesDb now answers everything.
  • layout_version: 3, not 2.
  • getRaw(): reads the file in daemon mode too.
  • quanta_db.root: the site directory, not db/.
  • Stub version() example: 1.1 instead of 1.3.

The generated qdb pages are rebuilt. The image_max_doc_kb default was left alone, because the ini default and the Rust default differ and it isn't clear-cut.

Verification

  • Every file path and every PHP Class::method / ->method() named in the new docs exists in the code. The PHP examples pass php -l on PHP 8.5.12.
  • Size: root AGENTS.md is 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=generic on a throwaway host, in the image with this branch's profiles/ mounted: the site gets AGENTS.md and CLAUDE.md.
  • A context-only build with this .dockerignore: root AGENTS.md, CLAUDE.md and .gemini/ are absent; profiles/generic/AGENTS.md is present.
  • A headless Claude Code session at the repo root quoted the title and rule 1 of 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

  • Stale generated page. docs/introduction.html is behind README.md (it has no logging section). Run npm run docs:build to refresh it.
  • Dev files in the image. node_modules/ and package-lock.json reach the image's web root when built from a checkout that has them.
  • Candidates for a security review: /qtag/ and /q/ render Qtags taken from the URL, and the API router has no auth layer.

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.
@daylioti
daylioti requested a review from Aldus83 November 6, 2026 09:29

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant