Refs #1349. The automation README describes `--mcp` and never mentions
`--serve`, even though every native build accepts it and it is the only channel
that works without a display. It also leaves out the two startup dialogs, the
`document_id` routing, and what `waiting_input` actually means.
`docs/automation/native.md` covers, all measured on a Linux headless machine
with `OpenCADStudio 2026.37+165`:
- choosing between `--mcp` and `--serve`, and what each needs (display,
no-display, `--export` for one-shot conversion);
- the writable `HOME`/`XDG_CONFIG_HOME` requirement, without which
`ocs_sessions` answers `No user configuration directory`;
- the startup dialogs: `AssocPrompt` then `DonationPrompt`, `new` answering
`ok` with no document until `close_modal` clears them, and that the donation
prompt appears once per application version per profile;
- targeting a document: reads and writes follow the active tab, so
`document_id` has to be passed explicitly after `new`;
- feeding a whole line: `waiting_input` means more input is required (not that
nothing happened), `cancel` closes a command, and the `unconsumed` /
`blocked_by` fields added in #1392;
- the interactive `start`/`input` shapes, including that a typed value goes
through `kind: "text"` while a keyword uses `kind: "token"` with its payload
in a field named `text`, and that the `TEXT` content step belongs to the
in-place editor (`text_input` / `text_commit`);
- what only native builds have: `measure`, `ocs_capture` (inline base64, or a
PNG path), and `set_properties` with `collection` and colours as
`{"Index": n}` / `"ByLayer"`;
- the remaining gap: `MTEXT`, `HATCH` and `POLYGON` report `completed` with
`added: 0` on the `--serve` path (#1390).
The README gains one line pointing to the page, placed after the tool list
rather than at the end, so it does not overlap #1394.
Docs only; no code changes.
OpenCADStudio --serve --port <N> listens on 127.0.0.1:<N> and serves the
same line-based JSON protocol over the socket (one client at a time; the
document session persists across reconnects), as an alternative to
stdin/stdout. ocs.py grows a port= option to connect either way.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
query now emits geometry for Ellipse/Text/MText/Polyline/Insert (on top
of Line/Circle/Arc/Point). Add layers op (name, ACI/RGB colour, on/off,
frozen, locked + current layer) and header op (units, PDMODE/PDSIZE,
LTSCALE, annotation scale, current layer/text style). ocs.py gains
layers()/header(). Lets an agent read the drawing's structure and
settings, not just entity counts.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Add undo and redo ops to the headless server (synchronous via update()).
Combined with select, the modify commands MOVE/COPY work through the
existing dispatcher — "select type=Line" then run("MOVE 0,0 10,0")
translates the selection. ocs.py gains undo()/redo().
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Add a select op that sets the document selection (by hex handles from
query, or by type/layer, or clear). Selection drives modify commands, so
an agent can query → select → run("ERASE") to act on specific entities.
Completes the modify half of the act/observe loop. ocs.py gains select().
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Add a query op to the headless server: list entities with handle, type,
layer and basic geometry (Line start/end, Circle/Arc centre+radius, Point
location), filtered by type and/or layer and capped by limit. Closes the
observe half of an agent's act/observe loop. ocs.py gains ocs.query().
Co-Authored-By: Claude Opus 4.8 <[email protected]>
run now feeds coordinate tokens to interactive tools: "LINE 0,0 10,10"
starts the tool, feeds the points, and terminates as if Enter were
pressed — creating real geometry through the existing command system. The
headless session also leaves the welcome (Start) tab so drawing commands
aren'\''t blocked. Verified end-to-end: LINE/CIRCLE create entities that
save and reopen.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Add an external automation API (issue #29 / #100 track 2): `OpenCADStudio
--serve` runs without a GUI and is driven over a line-based JSON protocol
on stdin/stdout — open / new / run / entities / save. State persists
across requests so a script or AI agent can act, observe, and act again.
`run` drives the app's existing command system rather than a separate
binding, so coverage grows with the app; synchronous commands apply now,
pick-based interactive ones come once coordinate feeding is wired. Ships
a ~100-line example ocs.py client over the same protocol — no FFI to
maintain. Headless works because the app already constructs and dispatches
GUI-less in tests.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
buyun14