# AgentCM project: Smoke project The drawings and specifications of this project are in `.construction/` as text, one file per sheet and per specification section, generated by AgentCM from its database and kept current as people edit them. Search these first; open a drawing only to look at something the text points to. ## Start here - `.construction/INDEX.md`: every sheet (number, title, revision and its date, discipline, how complete its text is, its PDF and page) and every specification section, with their files. - `.construction/sheets/.txt`: the sheet's text as paragraphs in reading order, each with its position (x, y from the top left of the sheet, 0 to 1). - `.construction/sheets/.tsv`: every line of text with its box (x, y, w, h), source, tag (detection's), how (`accepted` when a person accepted the tag in AgentCM's review, `pending` when not yet: a proposal, not a fact), label (a person's own), paragraph, view, and zone (the cell of the sheet's border grid, `J13`, the way architects name where a view is); the text is last, so a search for a whole cell ends in `$`. - `.construction/schedules/-.tsv`: one file per schedule, legend or keyed-notes table, listed in `INDEX.md` under Schedules and legends with its title. A comment line, a header line, then one line per row, cells by column: from the sheet's text, the row's position first and the table's own header rows at the top; from a schedule ingested into AgentCM, its rows under the drawing's column headers. The comment line ends with the schedule's id (`schedule_id=`, `none` for a table read from the text). Read a room's finishes or a door's size here, and in `.rows.txt` (next) for what no table file holds. - `.construction/sheets/.rows.txt`: the text across the sheet line by line, cells between tabs, the line's position first, leaving out what a table in `schedules/` holds: a table those files do not have, or rows of a table they miss (at the sheet's edge). Each row is in exactly one of `schedules/` and `.rows.txt`, so search both. A line runs across the whole sheet, so two panels side by side share one: check a cell's position in the `.tsv` when it matters. - `.construction/sheets/.groups.tsv`: the callouts and tags a person accepted in AgentCM's review, with where each callout points (`sheet:detail`). Only what was accepted is here, so a search that finds nothing here proves nothing. - `.construction/specs/
.txt`: a specification section, each line starting with its page in the manual (`pg440`). - `.construction/CHANGES.md`, `versions.tsv`, `history//` and `history/specs/
/` (only once a sheet or a specification section has been reissued): what each new version changed and which document issued it, every version of every sheet and section, and each earlier version's text with a `.diff`. `sheets/` and `specs/` always hold the current version. - `.construction/xrefs.tsv`: every reference between sheets, details and specification sections, one per line (from, position, kind, to, detail, target, how, found, text). - `.construction/tags.tsv`: every occurrence of a known identifier (a room, a door, a tag, a grid line), one per line (id, kind, sheet, position, view, how, text). How: `accepted` (a person accepted it in AgentCM's review), `schedule` (a row of a schedule ingested into AgentCM, or one a person confirmed in its calibration) or `text` (found in the text alone: check its place). `INDEX.md` says how many rooms are known and how they were found. The room list in `tags.tsv` is incomplete for this project: AgentCM found few room numbers, so a search of `tags.tsv` that finds nothing proves nothing. Search the sheet files instead. A sheet marked `partial` in `INDEX.md` needed OCR that was not run, and one marked `pending` or `failed` has no text yet: a search that finds nothing there proves nothing. When `.construction/pending.tsv` exists, AgentCM is behind on the sheets it lists (sheet, since, state, reason): `queued` sheets have edits their files will show within seconds, and `failed` ones a refresh that did not complete, with the reason. Check it before trusting a sheet's files; no file means every sheet's files are current. ## Searches that work - One room, door or tag across the set: `grep -P '^1607\t' .construction/tags.tsv` lists every sheet it is on, with its kind and how it is known. An identifier `tags.tsv` does not know is still found by the next search. - Where something appears: search all the sheet files at once (`.construction/sheets/*.tsv`) for a room number, a door number, a material or a phrase. The file name is the sheet. - What refers to a sheet, a detail or a specification section, and what a sheet refers to: one search of `.construction/xrefs.tsv`, for `\tA-501\t` (the sheet in the to column), `\tA-501\t5\t` (detail 5 on it) or `^A-501\t` (from that sheet). A line marked `accepted` was confirmed by a person; one marked `text` was found in the text alone. `found` says whether the detail is on the target sheet as a view label; `removed` (search `\tremoved\t`) means an earlier version of that sheet showed it and the current one does not: a revision took it away, and the reference needs checking. A line of kind `title` is a view's own mark (its id over its own sheet's number): it says where that view is on the sheet. A line with `-` as its detail names the sheet without a detail the text settles: check it with the searches below. `INDEX.md`'s section "How the references are drawn" says which placements of a detail each discipline uses and how often their details are found. - What a callout points to: a callout is usually two lines of text, the detail id directly above the sheet number (`5` over `A-501`); in the `.txt` they are usually consecutive lines. Some sets put the detail beside or below, or write `5/A-501` as one piece. - Which sheets refer to a detail: search the `.txt` files with a multiline pattern, the detail on one line and the sheet number on the next, for example `\t5\np\d+\t[\d.]+\t[\d.]+\tA-501$` (Grep with multiline on). Then look at the positions in the `.tsv` for details placed beside or below. - The views on a sheet: `grep -n '^## view' .construction/sheets/.txt` lists them (id, title, scale, area), and reading from a heading's line gives that view's text. A heading's area marked `area estimated` comes from where the labels are and can hold a notes column beside the view; `drawn` was drawn by a person. A view's label is its detail id at title size, larger than the callout text, with its title beside it and its scale below; the `.tsv`'s view column says which view each line is in. A sheet's views come from these two, not from a query of the database's `graph_views` table. - A schedule row: `grep -w 1607 .construction/schedules/*.tsv .construction/sheets/*.rows.txt` finds the room or door in every table, each row once: in its table's file, whose first lines are the header rows that say what each column is, or in a sheet's `.rows.txt` when no table file holds it. - A specification requirement: find the section in `INDEX.md`, then search its file. The specification names materials in its own words, which may differ from a schedule's legend. - Another discipline: drawings refer to another discipline by name ("SEE STRUCTURAL"), rarely by sheet number. Find that discipline's sheets in `INDEX.md` and look for the same room, grid line or area there. ## The database, for counts and joins (optional) If `query.sh` fails (AgentCM's database is not running), the files hold the same data: work from them. What AgentCM has linked (rooms, schedules, accepted callouts) can also be queried read-only, for a count or a join: run one query with `sh .construction/query.sh "SELECT ..."` or `powershell -File .construction/query.ps1 "SELECT ..."`. Every view has `project_id`: keep to this project's, `00fffe4b-5221-40a7-a12c-d55a55497f7e`, since one database serves several projects. Query the five views (`v_room_profile`, `v_sheet_contents`, `v_schedule_pivot`, `v_cross_references`, `v_open_conflicts`); the tables can be read too, but their columns may change. `.construction/db_schema.yaml` lists the tables, the views and the write endpoints; `.construction/database.yaml` gives the connection and the API's address (`api_url`). ## Looking at a drawing Look at the box the text files give, not the whole sheet: `sh .construction/crop.sh ` (or `powershell -File .construction/crop.ps1 `) renders that box of the sheet's PDF page as a PNG and prints its path; read that PNG. `` is the sheet's file name in `sheets/`; the box is in the sheet files' positions, 0 to 1 from the top left (a view's heading gives its area, a `.tsv` line its own box). A box too large to read sharply is refused: crop a smaller one. The PDF and page are in `INDEX.md`. ## Which source wins Highest first: (1) the drawing or specification itself, seen through `crop.sh` or the section's page: to check, never the first stop; (2) what a person confirmed in AgentCM: lines marked `accepted`, rows marked `schedule`, accepted zones' tables, confirmed sheet names and vocabularies; (3) what AgentCM read from the text alone: lines marked `text` or `pending`, a view's `area estimated`, sheets marked `partial`, which are leads to check, not facts; (4) a skill's own extraction, only for what AgentCM does not hold, and a fact about the documents found that way goes back to AgentCM (next), so the next session finds it there. When AgentCM is wrong, never edit `.construction/`: AgentCM leaves a file changed outside it alone, so the file goes stale, and its truth is the database. Use the document's value in the task at hand and say so, with the crop. Send the correction back for the project engineer to confirm, never into accepted data: a missed tag or callout through `tag-detections/ingest` (at `api_url` in `database.yaml`), where it waits as a pending card in AgentCM's review; anything else (a wrong text, a room name, a wrong zone) as a line in `.construction/skills/corrections.tsv`, under the header `sheet x y w h kind crop agentcm drawing`: the sheet's number, the box `crop.sh` took (0 to 1 from the top left), the kind (`text`, `room`, `tag`, `callout`, `zone`, `view`, `sheet` or `other`), the crop's path, then AgentCM's value and the drawing's value. One correction per line, tab-separated, each value on one line (tabs and line breaks become spaces); add lines, and never rewrite the lines already there. ## The construction skills The construction plugin (`/construction:...` skills) adds trade workflows: schedules to Excel and back, submittal logs, RFIs, bids, subcontracts, takeoffs, code research. In this folder: do not split sheets, extract specification text or rasterize whole sheets with a skill; AgentCM has done that (see `INDEX.md`, `specs/`, `crop.sh`). A skill that reads a schedule ingests its rows through `api_url` in `database.yaml`, and they appear in `schedules/`. A skill's own working data is under `.construction/skills/`.