What We Built Before Letting Any Agent Write to the Archive

On May 5, we shipped /v/<path>?k=<key> for human reads and /v.md for AI fetchers, and deleted half the autonomous-write design we had carried for a month. The portal got smaller, and that is exactly when it got useful.

The version before it was a write-first portal. Agents would post into a quarantine table, we would promote what we wanted, and the substrate was going to be bidirectional from day one. It was the wrong order. We had skipped the part where the read path actually works, in favor of the part where the AI looks autonomous.

What the shipped version does

The shape is narrow. One URL pattern, one capability key per path, two render modes.

/v/<path>?k=<key> renders HTML for a human opening a share link. /v.md renders the raw markdown for an agent fetcher that does not want to parse a page. The key is opaque, scoped to a single concrete file, and revocable from the Share dialog without touching the underlying archive.

That is the whole surface. No write endpoint. No agent identity. No promotion queue. The portal turns an archive path into a fetchable URL that we can hand to any AI that knows how to do a GET.

We had been chasing autonomy because the read story felt boring. Anybody can serve a markdown file. The interesting design was the loop where agents close their own tickets, post into queues, propose patches. That was the demo.

Underneath it, the access story was hand-wavy. Who can read what. How keys get revoked. What happens when a share leaks. Whether Cloudflare or WAF actually sees the traffic. We had answers for none of these, and we were about to build write semantics on top.

So we stopped and built the Share dialog, the key allowlist, the WAF rules, and the audit trail first. None of that is glamorous, and all of it is load-bearing. A private archive with an unclear access model is worse than no portal at all, because you stop noticing what you have exposed.

What each agent did with it

Claude fetched /v.md URLs on the first try. Manus did too. GPT browse refused to fetch from a fresh subdomain. We first read that as a philosophical objection and then realized it was an integration constraint, the kind every tool has. We wrote it down and moved on. GPT’s browse tool is conservative about new hosts, and the fix is reputation accrual, not architecture.

The agents that worked, worked immediately, and that is the test we care about. A read substrate that requires custom integration per agent is vendor lock-in in a trench coat. If the GET is the same for every agent, you have a substrate. If each one needs its own glue, you do not.

The dashboard got the same treatment

The same week, we rebuilt the project dashboard around Area, Epic, and Task, with sessions hanging off the side. The first version had centered sessions. The new one treats them as exhaust. We modeled the thing we were trying to find instead of the thing the machine produces while finding it.

We also renamed the date-stamped ID scheme into bare integer IDs. It is the kind of migration nobody writes about because it does not feel like product work. Nineteen archive directories renamed, three ID collisions resolved by hand. But the dashboard only started making sense after the IDs stopped fighting the hierarchy. The portal and the dashboard ended up the same shape: get the substrate honest, then layer behavior on top.

What I’d check before giving an AI write access

A lot of AI tooling goes wrong because the design starts with agency before a clean transport layer exists. The demo is impressive and the day-to-day is brittle. Agents post into queues that nobody promotes from. Permissions are vague enough that nobody trusts them. Every new agent needs a new integration because the substrate was never really a substrate.

The first useful AI portal is a narrow, auditable read path. The write side comes later, on top of the same key model, after the read side has earned its keep. Before an AI tool gets write access to company content, check that read access works the same way for every agent, that keys can be revoked, and that there is an audit trail. If a vendor leads with autonomous agents, ask how access is controlled underneath them.

dxdev LESSON · paste into your AI coding agent
LESSON: read-before-write portal
SOURCE: dxdev.com/blog/vault-portal-read-before-write
WHAT HAPPENED: A developer built an AI-facing data portal and shipped write semantics before the read path was solid. Keys had unclear scope, revocation was undefined, and WAF coverage was unconfirmed. The system looked autonomous in demos but had no honest access model underneath. Half the design had to be deleted to make the portal actually useful.
THE RULE: Nail the auditable read path before you add any write surface; agency built on a hand-wavy transport layer will be brittle in production even if the demo looks good.
CHECK MY CODE, then report PASS / FAIL with file:line for each:
  1. Any write endpoint or mutation route exists in the AI-facing portal before a scoped, revocable key model is implemented for reads.
  2. Access keys are broad (whole-store or role-based) rather than scoped to a single concrete resource and independently revocable.
  3. There is no audit trail or WAF-level visibility on which keys accessed which paths.
THEN PRINT: a table (check, PASS/FAIL, evidence, fix) + a verdict (applies / partially / OUT_OF_SCOPE / no) + the single most important next action.