A juudd site can carry a brief: a page of plain language saying what the site is for, what each table holds and what the person decided. Your assistant writes it with write_site_brief. The next assistant to work on the site, in another conversation or another AI app, reads it at the top of read_site, before it sees a single file.
That is the decision. The rest of this post is the gap it closes, how the brief is written and kept, and what we have not done.
The code says what, not why
A site is rarely changed by the assistant that built it. The person comes back next week, in a different chat, often in a different app. read_site hands that assistant the files. Nothing handed it the reason for them: what the site is for, what a column's values mean, what the person asked to keep exactly as it is.
So every new conversation started from the code and guessed the rest. A system that is guessed at on every visit cannot keep growing, because each guess is a chance to undo something the owner decided last month.
One tool to write, and the read is one you already make
The write is a tool of its own, write_site_brief(site, brief), because it is a new act. The read is not a second tool. The brief sits above the files in read_site, the call an assistant already makes before it changes an existing site. A separate read tool would be one more thing a model has to know to call, and a brief nobody reads is worth nothing.
Two properties follow from how it is written:
- The argument is the whole brief, not a line to append. The assistant reads it in
read_site, edits it and sends the full text back, so it stays one document an assistant can read in full rather than a log. - It is gated on ownership like every tool that takes a site. You can only write a brief for a site you own.
A rewrite loses nothing
Every writing is kept as its own row. Nothing is updated in place; the newest row is the one that is read, and the reply says so: when a brief replaces another, it tells the assistant that the one it replaces is kept.
That is why the tool declares itself non-destructive, by the same rule deploy_site follows. An assistant that replaces a good brief with a worse one has not destroyed the good one.
The edges
The brief is bounded, and the bound is a refusal. At most 6,000 characters. An empty brief, or a longer one, writes nothing, is recorded as a refusal, and the sentence says why. It is never cut off silently. The longer case tells the assistant to keep what the next person needs and leave out what the code already says. This is the same rule as every other bound here.
A site with no brief says so. The listing carries one line that names write_site_brief, so an assistant that has never seen the tool is told it exists at the moment it is useful.
An outage must not look like an empty page. If the table holding briefs cannot be reached, read_site says nothing about a brief at all, rather than "no brief yet". The second would invite an assistant to write one over a brief that exists. Because every writing is kept, the harm would be limited, but the listing should still not say something untrue.
The first publish asks for one. When a site's first version goes live, the reply tells the assistant to write the brief before the conversation moves on. The person has just said what they want, and no one else has it yet.
What is not decided
- The panel does not show the brief. The person sees it through their assistant. A panel view is cheap later; it was not needed to make the loop work.
- Earlier writings cannot be read back through a tool. They are kept so a rewrite is not a loss, and a tool to read them gets added when someone needs one.
- Nothing checks what is written. The tool's description asks for no passwords, keys or personal data, and nothing enforces it, as nothing enforces it for deployed code.
- We have not yet measured whether a brief changes anything: whether sites with a second deploy have one, and whether later deploys come from a different client than the first.
The rule, once
A site remembers what it is for: one brief, written whole with write_site_brief, shown first by read_site, with every earlier writing kept. The tools and their limits are listed in the docs.