For any agent working against this notes system — Claude, Codex, Envoy, or future tools. Its job is to make rule-reading mechanical rather than discretionary: you match what you are about to do against the map below and read the named note(s) before acting.
Reading rules on demand is fine — you need not read every rule upfront. But the moment you recognise you are entering a governed area (writing or editing code; creating or editing notes; changing infrastructure), stop and read the mapped note(s) before you act in that area, even if you are already mid-task.
Re-reading mid-task is expected and correct. Discovering relevance late is normal. The failure mode is pressing on once relevance has become clear — not the fact that you began before reading. If you realise halfway through a task that a note governs what you are doing, the right move is to stop and read it then, not to reason that it is too late to matter.
Cadence is currently freeform: act on the trigger whenever you recognise it, with no fixed checkpoints. (This is a deliberate first attempt — see gdata-server/todo for the August re-evaluation of whether fixed checkpoints work better.)
• About to write or edit code → ai-agent-guidelines and philosophy
• About to create or edit a .md, README, DESIGN or other documentation file in a repository → README/documentation-in-notes (docs live in notes; repo .md files are one-line pointers) and project-documentation
• About to catch or suppress an exception → exceptions
• About to act on John's own machine, environment, shell aliases, or personal working preferences → memory/john (general preferences and environment) and MEMORY/claude (Claude-specific behaviours)
• About to answer a location question, run a PostGIS query, compare a fix against a gazetteer, or build a location visualisation → using-gps-data
• About to write a CLI entry point or script-cum-library → main-pattern and error-messages
• Looking for outstanding work, what's left to do, or where a project's todo list lives → TODO (master index of every todo note)
• About to read or (especially) write anything under /z, or any other davfs/WebDAV filesystem mount → memory/john (writes are cached locally and may never reach the server; never use the mount in scripts)
• About to create or restructure notes → README/workflow and README/orphaning
• About to edit notes through MCP patch/batch/put/reorder/table_op → MCP Note Editing Guide
• Starting work on a project → that project's note, located via CONTENTS
• Setting up or documenting infrastructure → README/lessons
• Something that should be working isn't — a service “is running” but nothing comes through, a connection is refused or closed unexpectedly, or you are about to restart something to see if that fixes it → README/diagnosis (status is not function; do not restart before you can explain)
• Remote access to pomelo is broken, or you are asked about SSH-into-pomelo, VNC-into-pomelo, kelp ports 2222/15900, Dante/sockd, or the SOCKS5 BIND tunnels → infrastructure/kelp-dante-socks5 (topology, port table, and a per-hop diagnosis table)
• Starting a new session or task → README/agent (working practices: find before investigate, decisive action, targeted edits)
• Wondering how the notes server works, what port it uses, or where data lives → gdata-server/infrastructure
• Starting any session → read john/actions and mention any pending items to John, even if unrelated to the main task
• About to use tools, delegate to another agent, change external state, spend resources, alter infrastructure, or perform any privileged/high-impact action → AI Operational Safety Rules
• About to add a specific, checkable detail (a date, number, recent event, current condition) to round out an explanation, and haven't actually checked it → README/agent (“Don't pad an otherwise-correct answer with an invented specific”)
• John says “end of day”, asks for a day-end handover, or asks to note the day’s work/learning → End-of-Day Review and Handover.
• About to build or upgrade FreeBSD from source, rebuild Radagast ports, or change Radagast’s OS configuration → radagast hub and FreeBSD source-build rules
• About to change UUCP links, polling, routing, or internal host mail → uucp; for the FreeBSD VM link also read uucp/radagast
• About to work on Delay Repay automation, its browser host, claims, or toolkit → delayrepay
• About to change hibernate-on-approach behaviour or deployment → hibernate-on-approach and hibernate-on-approach/todo
• About to operate or change the popit3 mail-processing pipeline → popit3; for live operations read popit3/ops
• About to rename, drop, move, or repurpose any object — database table, file, endpoint, credential, seat, resource, role — that another person, application, or process is actively relying on → shared-resource-coordination (sign-off + agreed time + rollback ready; alias/synonym safer than rename)
When a new rule note is created that should fire on a recognisable situation, add a line to the map. The map is only useful if it stays current — an unlisted rule is a rule that will not be read on time.