This is the development record, published as it was written. It is amended by revision, including where the work went wrong. Nothing here has been rewritten for the web.
Context
What this project is, why it exists, and what "good" looks like. Read this before RECORD.md, AGENTS.md or any code.
The product, in one paragraph
A small supplier enters their domain and gets a free, dated, shareable report on whether AI agents can find, read and use their website — plus the exact files that fix what they cannot. Every line of that report is the result of a check that anyone can re-run. No model decides the result. The rubric is published and generated from the code that runs it.
Why it exists
Two outcomes, and both are required. Neither is decoration for the other.
1. External revenue, small. The business model hypothesis is that the surviving payer in an agent-mediated market is the supplier buying legibility, not the advertiser buying impressions. The free report is the proof; the paid tier is monitoring — re-running the check and reporting drift, so a supplier knows when a platform or a theme change has quietly broken their machine-readable surfaces. The registered test is in RECORD.md, fixed before any outcome was observed.
2. A clean, public decision corpus. This project is also the demonstration case for Perspicuity: a fresh start, built end to end under the method, producing records that show what the method actually looks like when it is working. That corpus is intended to be published. It is not documentation written after the fact — it is the development process.
The corpus is the backbone
This is the part that is easy to nod at and then quietly abandon, so it is stated as a rule:
Every consequential choice in this repository exists as a Perspicuity record before the work that depends on it. If a choice is not in a record, it has not been made.
A consequential choice is one with credible alternatives that materially affect outcomes, behaviour, authority, dependencies or review obligations. That includes research choices, such as an evidence rule that changes a conclusion, and it includes choices about the process itself.
The project's own record is [RECORD.md](RECORD.md). Sub-decisions live in [docs/records/](docs/records). The naming, linking and admission rules are in [docs/RECORDS.md](docs/RECORDS.md), and make records checks them.
Three consequences follow, and all are deliberate:
- Records are written to be read by strangers. Assume a record may one day be published on
perspicuity.ai. Write the decisive basis so someone with no context can follow why. Keep credentials, customer details and personal data out of every record.
- A record is evidence, not a status symbol. The shortest record that makes the basis,
the current position and the next action reviewable beats a long one. A record that restates its parent is noise in the corpus.
- Every actor is named. Not "the agent", not a job title, not a model name — the first two
mean nothing to a stranger, and the third changes under the work. The coordinator names itself in its first session and names each worker it delegates to. The rule, the roster and the check that enforces it are in docs/ACTORS.md.
The rule is not left as prose. scripts/check_actors.py fails the build on one of five listed role words anywhere in the corpus or the process documents, so the naming convention is a property of the repository rather than a habit of the session that wrote it.
How the work is recorded
One evolving record per intention, amended by revision and never rewritten into agreement with hindsight. The record for a consequential choice exists before the work that depends on it; docs/RECORDS.md splits a record's life into the two moments that make that survivable — registering the basis and the choice before dependent action, and filing the evidence and the findings after it.
Three stages, which overlap and repeat: Frame and Decide (the problem, the outcomes, the alternatives, the selection or the pending question), Act (units, owners, acceptance criteria registered before implementation, evidence after), and Review (assessment against criteria registered earlier, with delivery acceptance kept separate from evidence of later benefit).
Four rules do the real work. They are stated in full in AGENTS.md, and a reader who remembers only these four will still file a usable record:
- Register before dependent work. A record written afterwards records what you decided, not
what you knew, and the difference is the whole value of the corpus.
- Separate the recommendation from the selection. A worker prepares the basis and
recommends; David decides. Never record a choice you were not authorised to make.
- Keep givens, uncertainties and assumptions apart, each with its source. Collapsing them is
how a corpus becomes confidently wrong.
- Delivery is not benefit. "It shipped" and "it worked" are different findings.
Who acts
| Actor | Kind | What they own |
|---|---|---|
| David | Human | The principal and the decider. Owns the objectives, spending, outbound messages, external agreements and the release word for publication. |
| Rook | Agent, coordinator | The process documents, the corpus, and the reversible implementation choices inside David's grant. Named itself in its first session; the name outlives the model behind it. |
| A named worker | Agent | One bounded assignment, granted and named by the coordinator, returning its own basis and evidence. Named with the grant. |
Agents are named, never called "the agent", a job title, or a model name. The roster, the naming rule and the check that enforces it are in docs/ACTORS.md; the delegation rules are in docs/RECORDS.md.
The claim boundary
The report establishes what is mechanically checkable about a domain. It does not establish that an agent will find, trust or recommend a business, and it does not measure traffic or ranking.
This boundary is the product's whole credibility. Anyone can sell a score. The reason a supplier should believe ours is that we show the checks, show the evidence, mark which requirements are grounded in published practice and which are our own judgment, and refuse to promise an outcome we cannot observe.
The boundary is not just prose: tests/test_checks.py::ClaimBoundaryTests fails the build if catalogue wording drifts into a prediction.
What we are deliberately not doing
- No accounts, no cookies, no tracking. Cycle one collects nothing about a visitor.
- Only the submitted domain is fetched. Nothing else is crawled. No merchant data is
scraped, no permission exposure is created.
- Reports are private by default at an unguessable link. The supplier publishes; we do not.
- No paid API in the core. The report is deterministic and needs no model. A model may
later draft suggested files or extract facts, under a recorded choice, and may never change a pass/fail result.
- One page type. A landing page, a rubric, a report. Scope creep here is the known failure
mode of every previous project in this workspace.
What we reuse rather than rebuild
- The existing server, Caddy, snapshots, health checks and release practice.
find-my-next-bite's measured agent-discovery findings: maximal crawler permissiveness,
llms.txt, sitemap, canonical pages, one joined JSON read interface.
- The Perspicuity skill and its record format.
- Apache-2.0, the licence already in use.
Success, and what would stop us
Registered before the outcome was known, in [RECORD.md](RECORD.md):
- Passes at one paying user, or ten real audits plus two unprompted enquiries.
- Fails at ten real audits and zero enquiries.
- Scope cap: if the public site is not live by 2026-10-03, stop and return to Frame and
Decide rather than expanding scope.
Stopping is a real option and a cheap one. Ten audits and zero enquiries is a useful, publishable finding about the payer hypothesis, and it belongs in the corpus as much as a success does.
How this record connects
It builds on or points to: RECORD, RECORDS, ACTORS, AGENTS.
It is referenced by: Agent instructions, Choose what cycle one delivers, Host the check under Perspicuity and publish the corpus with it, Make the record conventions followable and enforce the actor rule.