Site notes: what a project knows about its site
Every FlowQA project carries a small knowledge base about the site it tests, written by the engines and corrected by people. It exists so each exploration and repair starts with what earlier ones learned, and so coding agents can read what a page is for.
What is in it
| Note | Path | Written by | Holds |
|---|---|---|---|
| README | README |
the first map, from the project description and the exploration brief; then people | what the product is, what the team said, what the map found, what is off limits, which variables hold accounts |
| Page | pages/<slug>, one per URL pattern (/products/:id) |
each map; journeys and repairs append to its Learned section | title, headings, navigation, forms with their fields and submit, a text excerpt, and what journeys and repairs found there |
| Exploration | explorations/<id> |
each completed exploration | one summary line and the journeys with their outcomes; what changed since the last map |
Ids, numbers and UUIDs in paths collapse to :id, so /products/12 and /products/13 share one note.
Values of variables are never written into notes.
Who reads it, in what order
- The planner gets the README, one line per page note and the last few exploration summaries, before the crawl itself.
- The explorer gets the note of the page it has landed on, flattened to a short paragraph, in every decision it asks the models.
- The repair engine gets the note of the failing step's page.
- The context pack ("hand me the map") ends with the whole knowledge base as Markdown.
- Coding agents read it through the MCP tool
flowqa_site_notes(the index, or one note by path).
Who writes it
Engines write only notes they own (source: engine).
A person's edit (Settings, Site notes, or PUT /v1/projects/:p/qa/notes/<path>) makes the note theirs (source: person), and from then on engines only refresh its verified date.
A page that vanishes from the latest map is marked "Not seen in the last map", never deleted; people can delete any note.
The Learned section of an engine page note survives a refreshed description and keeps the last 30 lines.
API
GET /v1/projects/:p/qa/notes lists the index (no bodies).
GET, PUT and DELETE /v1/projects/:p/qa/notes/<path> read, write and remove one note; PUT takes { body, title?, summary? }.
Exploration and repair jobs carry notes: { readme, index, pages }, with full page notes for the pages the job will touch (at most 40).
What the engines keep to themselves: insights
Beside the note a person can read, each page note carries an insight the strong model wrote for the engines.
During the map the model is given every page's title, headings, navigation, forms and excerpt, fifteen pages per call, and writes two or three sentences per page: what it is for, how it behaves, and what an automated tester must know (required fields, controls disabled until something else happens, gates, redirects).
After generation one more call turns what the journeys went through (how they ended, the explorer's notes, refused forms, questions a person answered) into a sentence per journey, appended to the start page's insight as a dated line; the newest twelve stay, and each map refreshes the opening paragraph while keeping the lines.
Insights are read by the planner (the page list carries them), by the explorer on every page it lands on, and by the repair engine, so a project's explorations get better at its site over time.
They are never shown in the workbench, the context pack, the MCP tool or the notes API; insights: false on an exploration's options turns the calls off.
Reviewing what an exploration wrote
Every exploration keeps the list of notes it created or updated: the README and the page notes from its map, what each journey taught its start page, its own log entry, and the notes a person's answers added under "From the team".
The exploration view carries it as notes_updated (path, title, created or updated, a one-line detail), and the Explore dialog shows it after the map and again when generation finishes, with a button that opens the note in Settings, Site notes, ready to correct.