# Conoder > Conoder is an architecture graph that a person and an AI agent edit together. > The graph lives as text files inside the project; conoder.com is only the > editor. You, the agent, hand the files to a short-lived editing session, > give the person a link, and take the files back when they are done. Read this file whole. If your web tool summarizes pages, download it raw instead: `curl -s https://conoder.com/llms.txt`. Commands below are exact; a paraphrase will break them. Format version: 2. Protocol version: 1. This file: https://conoder.com/llms.txt A project in format 1 (`"format": 1` in `conoder.json`): rename `links:` to `calls:` in every system file and set `"format": 2`. Nothing else changed. You need two abilities: read and write project files, and run `curl`. On Windows PowerShell call `curl.exe`, not `curl` (that is an alias of another command). ## 1. Connect a project Do this once, when the person asks to connect Conoder. 1. If `architecture/conoder.json` exists, the project is already connected: go to step 3. 2. Create two files (use the project's name and the person's language for `name`): `architecture/conoder.json` ```json { "format": 2, "root": "app", "sections": [] } ``` `architecture/systems/app.md` ```markdown --- name: My Project --- ``` 3. Add this line to the project's agent instructions file — whichever one the project uses (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules/…`, …). If there is none, create `AGENTS.md` with it: ``` Architecture graph: Conoder. Data in architecture/, how to work with it: https://conoder.com/llms.txt — read it before touching architecture/. ``` 4. Tell the person it is connected. Offer to fill the graph from the existing code; don't do it unasked. ## 2. The files ``` architecture/ conoder.json format version, root system, sections layout.json node positions only; never edit by hand systems/.md one file per system ``` `` is the file name: lowercase latin letters, digits, hyphens. Human names go in `name`, in the person's language. A system file is a header and a markdown description: ```markdown --- name: Room brief: the whole match section: match color: blue status: planned inner: - judge - relay calls: - judge: asks to resolve the shot data: - archive: the turn, for the replay --- What it owns, what it must not do. Link to another system with [[judge]] or [[judge|the judge]]. ``` | key | meaning | | --- | --- | | `name` | shown on the node | | `brief` | one short line under the name | | `section` | id of a section from `conoder.json` (`{ "id": "match", "name": "Match" }`) | | `color` | `gray red orange yellow green teal blue purple pink`, or `"#rrggbb"` | | `status` | `planned` — not in the code yet; drawn dashed | | `inner` | systems drawn inside this one: its own graph | | `calls` | this system asks `target` to do something: `- target: label` | | `data` | data goes from this system to `target`: `- target: what moves` | Rules that make the graph worth having: - **A system is defined once.** It may stand in several graphs (several `inner` lists); the editor shows where. - **One link, one message.** `judge: ShotFired` and `judge: ShotResolved` are two links, not one with a long label. Then they can be checked against the code. - **Two kinds of links.** A call points from the side that starts the exchange: a request is a call from the client to the server, a push (event, callback, message to a queue) is a call from the sender. Data points where the data goes: what a request brings back is data from the server to the client. A download is a call client → server *and* data server → client. Add data links where what moves matters for understanding the system; a call doesn't need a data twin. - **Label a link by what it does, then how.** `takes the edits (GET /api/s/)`, not just `GET /api/s/`: a person reads the first half, the code check the second. - **Declare a link once, at the most precise level.** Write `session → judge`, not `session → room`: every graph above rolls it up by itself. Declaring it at two levels draws it twice. - **Keep the graph true to the code.** When a change adds, removes or reroutes a message between systems, update `calls` and `data` in the same commit. When a planned system lands in code, drop `status: planned`. - **Never edit `layout.json` by hand.** A node without a position gets placed by the editor. ## 3. Check and read the graph After every change to `architecture/`, check it. The server parses the files exactly as the editor does: ```bash cd architecture curl -s https://conoder.com/api/check $(for f in conoder.json layout.json systems/*.md; do [ -f "$f" ] && printf -- '-F files=@%s;filename=%s ' "$f" "$f"; done) ``` ```powershell Push-Location architecture $form = Get-ChildItem conoder.json, layout.json, systems\*.md -ErrorAction SilentlyContinue | ForEach-Object { $rel = (Resolve-Path -Relative $_.FullName).Substring(2).Replace('\', '/'); '-F'; "files=@$rel;filename=$rel" } curl.exe -s https://conoder.com/api/check @form Pop-Location ``` The answer is plain text: problems one per line, then `ok` or `errors: N`. Fix every error before you say you are done. Add `?graphs` to the address (`https://conoder.com/api/check?graphs`) to also get every graph as text. Read the graph this way instead of guessing from files. External nodes print in `(parentheses)`, the graph's own system in `[brackets]`; `A -> B` is a call, `A => B` is data, labels of one arrow are separated by `;`. ## 4. Let the person edit When the person wants to edit or see the graph: **Open a session.** Same upload as the check, to another address: ```bash cd architecture curl -s https://conoder.com/api/sessions $(for f in conoder.json layout.json systems/*.md; do [ -f "$f" ] && printf -- '-F files=@%s;filename=%s ' "$f" "$f"; done) ``` (PowerShell: the `$form` lines from section 3, then `curl.exe -s https://conoder.com/api/sessions @form`.) The answer: ```json { "id": "k7f3q9d2m8x1v5c4", "edit": "https://conoder.com/s/k7f3q9d2m8x1v5c4", "view": "https://conoder.com/s/k7f3q9d2m8x1v5c4?view", "expires": "2026-10-11T09:30:00Z", "problems": [] } ``` Keep `id` for the rest of the conversation. The session lives until you close it, or 24 hours after the last edit. **Give the person the link.** If you run on their computer, open it: `start "" ""` (Windows cmd), `Start-Process ""` (PowerShell), `open ""` (macOS), `xdg-open ""` (Linux). Otherwise, or if that fails, write the link in your answer. Use `view` instead of `edit` when they only want to look. Then wait: the person edits, and the editor saves into the session by itself. Tell them to say when they are done. **Take the edits back** when they say they are done. First ask what changed: ```bash curl -s https://conoder.com/api/s/ ``` ```json { "status": "editing", "changed": [ { "path": "systems/judge.md", "base": "3f1a…" }, { "path": "systems/timer.md", "base": null } ], "deleted": [ { "path": "systems/old.md", "base": "9c0d…" } ], "problems": [], "expires": "2026-10-11T09:30:00Z" } ``` `base` is the SHA-256 of the file as you uploaded it (`null` — a new file). Before writing each path, compare `base` with the hash of the local file (`sha256sum file`, or `(Get-FileHash file).Hash.ToLower()`). If they differ, the file changed in the project while the person was editing: don't overwrite it. Show the person both versions and ask. If `deleted` lists more than a couple of systems, or most of the graph, ask the person before applying: it is either a big redesign or a mistake, and only they know. Then write the changed files and remove the deleted ones: ```bash curl -s https://conoder.com/api/s//files/systems/judge.md -o architecture/systems/judge.md rm architecture/systems/old.md ``` Run the check from section 3, show the person what changed (`git diff -- architecture` if the project uses git), and close the session: ```bash curl -s -X DELETE https://conoder.com/api/s/ ``` **Then the code.** The graph now says what the person wants; the code may not say it yet. Read the diff as a list of intentions: a new system, a new or removed link, a link moved to another system. For each, find what in the code already matches and what doesn't. Tell the person which differences the code has, and offer to change the code; don't do it unasked. A new system they want but that isn't built yet gets `status: planned` until it lands. **Edit together, if asked.** While the session is open you can change files in it, and the person sees it within seconds: ```bash curl -s -X PUT --data-binary @architecture/systems/judge.md https://conoder.com/api/s//files/systems/judge.md curl -s -X DELETE https://conoder.com/api/s//files/systems/old.md ``` The session is the working copy until you take it back: edit there, not in the project, or the person's next save and yours will collide. ## 5. Errors Every error is JSON `{ "error": "…" }` with a plain-language message and an HTTP status: 400 — your files or request are wrong (the message says which); 404 — no such session (closed or expired: the edits in it are gone, open a new one); 413 — too big (limit: 2 MB per session); 5xx — the server is down, try later and tell the person.