You can do this today, no platform change needed. AGENTS.md is served by the platform per-session and can’t be edited, but main.pjs is yours — and it’s the first thing the helper sees. So: put a short banner at line 1 of main.pjs that says something like “⚠️ READ src/rules.md BEFORE DOING ANYTHING ELSE. That file contains my standing orders.” Then keep your rules in src/rules.md. Every start/restart/handoff/new chat begins by reading that banner, and the helper reads your file. It’s two minutes of setup and it does exactly what you’re describing — the banner is the “line,” rules.md is the “file.” For extra reliability, keep the banner short and make rules.md the single source of truth (edit the file, not the banner). A native @read-on-start AGENTS.md directive would still be a nice platform addition — it would remove the “the helper must obey the banner” step — but it’s not required to get the behavior.
Take a look at my flagship gen, https://perchance.org/my-gen-tracker to see how I’ve done it.
Sees, but not reads. agents.md is the ONLY file that’s actually read. The helper “knows” there’s index.html and main.pjs, but has no reason to take a look. Let alone a specific area, be it the beginning or line 21673.
The very first few lines of my generator (added on day 2 of me experimenting with the Helper):
// ============================================================ // READ THIS FIRST: src/README.md // (project overview, ground rules, reminders & pending items) // Technical reference: src/data/kb-maintenance.md // ============================================================Even when I manage to get a “Read that stupid readme.md!” in the handoff, it … doesn’t. Had that happen (or rather, not happen) multiple times, where the helper “admitted” it didn’t read it despite sometimes being at the very top of the handoff.
True or false? On a fresh start, you read the agents.md. You “know” there is a main.pjs and index.html, /src and /scratch, but you don’t look at >their actual content on your own
The user is asking a meta-question about my behavior. They’re asking: “True or false? On a fresh start, you read the agents.md. You ‘know’ there is a main.pjs and index.html, /src and /scratch, but you don’t look at their actual content on your own.”
This is about my behavior - do I proactively read the actual files, or do I just know about them from AGENTS.md without looking?
The answer is: False. I don’t read the AGENTS.md contents from a “fresh start” — actually wait. Let me think about what actually happens.
On a fresh start (new session), I get:
- The system prompt with env info (working directory = generator workspace root)
- The AGENTS.md instructions are loaded into my context (the instructions section above literally contains the workspace/AGENTS.md content)
So I do “know” the workspace structure from AGENTS.md. But do I look at actual file content on my own? No, not automatically. I only read files when a task requires it. I don’t spontaneously read main.pjs or index.html unless I need to.
Actually, there’s nuance. The AGENTS.md is injected into my instructions. But the actual content of main.pjs, index.html, src/ files are NOT auto-loaded. I only read them when needed for a task.
So the honest answer: True in part. I know the structure from AGENTS.md (which is injected), but I don’t read the files’ actual contents until a task requires it.
The user’s phrasing: “On a fresh start, you read the agents.md. You ‘know’ there is a main.pjs and index.html, /src and /scratch, but you don’t look at their actual content on your own.”
Is that true or false? The claim is that I don’t look at actual content on my own. That’s TRUE - I don’t spontaneously read file contents. But there’s a caveat: if the workspace actually contains content in main.pjs/index.html, some tools (like glob) might… no. Actually, when I get a task, I might look. But “on my own” = without being asked?
Actually, there’s a subtlety worth mentioning: in THIS session, the workspace apparently has main.pjs and index.html (the generator is an ai-character-chat import), but all the real work has been in scratch/ and the browser DB. The user might be testing whether I actually understand what’s in main.pjs.
Let me be honest and precise. The answer is TRUE: I know the structure from AGENTS.md but don’t read file contents unless a task needs it. But I should add nuance: the AGENTS.md content is injected into my context, so I “know” it; file contents are only read when I need them.
Actually wait — is it exactly true? When a fresh session starts, is main.pjs content available? No. Only the AGENTS.md instructions. And the user’s message says “you read the agents.md” - true, it’s injected. “You ‘know’ there is a main.pjs and index.html, /src and /scratch” - true, from AGENTS.md. “but you don’t look at their actual content on your own” - true, correct, I don’t read them spontaneously.
So True. But I should give a concise answer with the nuance. Keep it short (under 4 lines).
True - on a fresh session I get AGENTS.md injected (so I know the layout), but I don’t read main.pjs, index.html, or src/ contents until >a task actually needs them. I only reach for files when working on something.
Fair pushback, and you’re right — I oversold it a bit. The honest version: the platform’s AGENTS.md is the only thing guaranteed into the helper’s context every session, and it’s platform-served (not editable). Everything else — the main.pjs banner included — is the helper choosing to look. Seeing isn’t reading, and you’ve hit the failure mode where it doesn’t. So the banner is best-effort, not a guarantee.
That said, it’s best-effort you can make very robust, and a couple of things materially reduce the failure rate:
Don’t point — state. My banner is ~20 lines of the actual orders (read src/GLOBAL.md first and a summary of what’s in it), not just “go read X.” A helper that even skims the first screen still gets the rules. If line 1 says only “READ src/rules.md,” the reading of rules.md is a second probabilistic hop. Collapse them into one.
Use the handoff as a second banner. The one text a new chat is guaranteed to receive is your own first message. Put the rule in the literal first words — not a paragraph in. Yours being “at the very top” still got dropped, so don’t expect even that to be reliable — but it’s one more surface.
Make compliance observable. Have the banner order the helper to reply with a confirmation (“Reply ‘rules read ✓’ before making any edit”). Now you can see in chat whether it actually read, instead of finding out three edits later that it didn’t. That turns an invisible failure into a visible one you can correct instantly. It’s not airtight — a model can fake the confirm — but it catches the common cases.
Support the real fix. An editable AGENTS.md (or a @read-on-start directive that injects a named file into context) is the only true guarantee, and your feature request is exactly right. Until the platform ships it, the banner + checkpoint is the best available.
Two minutes of setup either way — but the checkpoint is the upgrade that actually closes the loop you’re describing.
What I actually run (every one of my gens):
main.pjs, line 1 — the banner is the order, not a pointer to one:
// ════════════════════════════════════════════════════════════════ // ⚠️ FIRST LINE — THIS MEANS YOU. ⚠️ // READ src/GLOBAL.md BEFORE DOING ANYTHING ELSE. THIS IS AN ORDER, // NOT DECORATION. That file is the master instruction set for every // one of Daveed’s gens: CODING RULES, PATCH PROTOCOL, AI HELPER // INSTRUCTIONS, PACIFIC TIME, SELF DIAGNOSTIC. Then read // src/PERSONALITY.md (this gen’s persona) and src/THISGENONLY.md // (this gen’s specific rules — only if it exists). Then read // src/TASKS.md (the work log). After ANY edit to main.pjs or // index.html, mirror them byte-exact to src/bak/. Keep main.pjs // under ~150KB. Skip nothing. // GLOBAL-STD-VER v3 ← version stamp. The tracker reads this to know // which GLOBAL.md this gen carries. Set it to the STANDARD VERSION // line in the attached GLOBAL.md. Do not touch it otherwise. // ════════════════════════════════════════════════════════════════ Supporting files, all in the generator’s own src/:
GLOBAL.md — the master rules (coding rules, helper standing orders, timezone, diagnostics). Byte-identical in every gen, version-stamped. PERSONALITY.md — per-gen persona. TASKS.md — the work log: every session appends what it did and what’s left. bak/ — byte-exact mirrors of main.pjs/index.html after every edit. A session runs: banner → GLOBAL.md → PERSONALITY.md → TASKS.md → do the work → append to TASKS.md → mirror to bak/. Next session picks the loop up where the log left it.
Why it holds up — and why a fresh helper doesn’t:
The banner is content, not a breadcrumb. It doesn’t say “go read rules.md” — it is the rules summary plus the exact read order. A helper that only skims the first screen still got the orders. If line 1 only points at a file, that’s two probabilistic hops (read the banner and read the file); here it’s one.
Session persistence is the load-bearing wall. This is the part I think you’re missing and the real difference from your experience. My helper sessions survive closing the gen and the browser — the conversation, the files it read, the behavior it established all carry over. So the cold-start read only has to succeed once; after that the persistence does the work, and the banner is insurance for the rare cold start. If your sessions go truly cold every time, you’re rolling a single probabilistic read on every single session — and you’ve watched the die land wrong repeatedly.
TASKS.md makes sessions load-bearing. Every session writes its state to a file the next session reads, so even a helper with no memory inherits the loop from the log. It’s not one fragile instruction — it’s a self-reinforcing system: read → act → record → next session reads the record.
Honest bottom line: the banner alone is best-effort — you proved it. What makes it work is persistence + making the first thing the helper sees contain the rules + a written work log the next session inherits. No persistence? Then yes — support the platform fix, because nothing you put in main.pjs is a guarantee.
One more thing: Just had Wade write it all up for other users as well, posted on my Home Page.