getvect: Instructions file for Codex

AGENTS.md

GetVect is a local desktop vectorizer: an Electron app (TypeScript; React renderer, pure-Node engine in src/engine/) that turns PNG/JPEG/BMP into SVG/EPS/DXF/PDF/PNG on the user's machine — no accounts, no server, offline by default. The engine is deterministic and heavily instrumented; the measurement harness, not opinion, decides whether a change ships.

Commands (green on a clean checkout)

npm install          # ~10 s; postinstall de-quarantines Electron on macOS
npm run typecheck    # tsc strict, both configs
npm run test:engine  # the engine contracts, pure Node, ~20 s — the fast gate
npm test             # engine contracts + full Playwright acceptance suite (~3 min)
npm run instruments  # corpus metrics + threshold gates → artifacts/metrics.json
npm run assets       # regenerate derived/demo assets (CI fails if stale)

There is no linter yet (tracked in katra/tasks/); tsc strict is the only style gate. Match the surrounding code's comment density and idiom — comments in this repo state constraints and reasoning, not narration.

Invariants a PR must not break

• The harness decides. Read docs/HARNESS.md before touching the engine. Corpus fixtures decide; in-house artwork (Frankie) reports but cannot carry a decision. A rate measured over a short boundary is not a defect. State the window of every measurement.
• Determinism: same image + same settings = byte-identical SVG. Tested.
• Sharp corners stay sharp. The de-staircasing failure mode is rounding what was meant to be angular; the mascot's ear tip is the canary and tests/engine/sharp-corners.test.mjs enforces it.
• DEAD GATE rule: a declared threshold whose metric is not produced fails the runner. Never leave a gate that cannot go red.
• The CLI exit codes and flags are a published interface, in the same class as the on-disk katra format, not an internal enum. They are documented in SKILL.md and docs/CLI.md as a contract an outside caller can be written against. No such caller is known today: the reason to freeze the table is that nobody can build against one that moves, so stability is what makes an integration possible at all. Adding a code or flag is free; renumbering or removing one breaks a caller silently, since their branch just stops matching. skill-doc.test.mjs pins both tables by name and fails even when the docs move in the same commit. Change them deliberately and with a note, never as a refactoring side effect.
• Asset staleness gate: derived assets (screenshots, demo media, icons) are regenerated by committed scripts only — never hand-edited; CI runs regenerate-derived-assets.mjs --check and fails on drift.
• Exactly two network touchpoints, both in src/main/: the once-per-launch release-feed check (opt-out via GETVECT_NO_UPDATE_CHECK) and opt-in AI Enhance with a user-supplied key (encrypted via safeStorage, never returned to the renderer). Nothing else may touch the network; the renderer ships CSP default-src 'self'.
• Provenance is enforced. Nothing enters fixtures/ without a stated redistributable licence (build fails). Never vendor, commit, or quote competitor output — this repo's history was rewritten once to purge exactly that. The devlog publishes only via the opt-in gate (scripts/devlog-gate.mjs); its forbidden-names list is load-bearing.
• Tests are invisible. The acceptance suite drives real Electron windows that are never shown (z-window-guard.spec.ts enforces it). Never launch the app headed from an agent session.