cadmaster v1 — paper design (2026-08-17, draft for walkthrough)

Status: SIGNED OFF by Jordan and Aristide, 2026-08-17 (Jordan approved W1-W5; Aristide: "yes"), scoped minus the .ai leg, which gets its own walkthrough when ready. Coding of v1 may begin against this document. Original preamble: Nothing here is code. This is the document we walk through together with real shop files, mark up, and sign off before any interface code is written. Inputs: Jordan's seven design answers (design/interview-2026-08-17.md), every standing ruling in CLAUDE.md, and the market research of 2026-08-17.

1. What v1 is — and is not

v1 is a standalone desktop application for Windows, Linux and Mac — Windows first-class (the research is unambiguous: shop PCs run Windows; LightBurn tried Linux and retreated). Fully offline — customer files never leave the shop; nothing in the app requires a network.

The v1 chain, one job at a time:

Intake → Heal → QC → Part review → Nest → Cut plan → Post → Deliver + Archive

In v1:

• Input: DXF, DWG, .ai, PDF, SVG. Every .ai/PDF/SVG intake requires a stated finished dimension per file — scale is never inferred (Jordan, answer 1).
• Healing to true G2/G3 arcs with function-based tolerance classes.
• QC gates (units, envelope, open contours, duplicates, islands, minimum feature vs beam comp), every result stated.
• Nesting on a chosen sheet, auto plus hand adjustment.
• Tabs, leads, start points and cut order chosen after nesting, in sheet coordinates (Aristide's order ruling, folded in below — section 7).
• Fanuc macro-B post, with the nc_audit run automatically on every program before it can be released.
• Customer sheet / shop sheet split on every job.
• Job archive with a full per-operator audit trail; multi-operator, multi-machine.

NOT in v1 (deliberate, per Jordan's answers):

• Estimator (later module; sales role exists anyway — see section 4).
• Cut-vs-engrave/score layers (future stroke-color signal), rapid routing detours, remote/cloud anything.

IN v1 after all — bridges (Jordan, 2026-08-17, answering Q2): "It should automate it, flag it, make it easy for operator to double check it and edit it if he wants." So automatic bridge placement on floating islands moves INTO v1: the app places bridges, flags every one, and the operator can move, resize or delete them. This supersedes the earlier "bridges later" — recorded as a scope change, not a drift.

• Licensing enforcement is undecided; the design keeps a subscription model possible (no architectural assumption of "bought once, never phones home" — but also nothing that breaks when there is no network, ever).

2. The spine: a wizard the operator can leave

The interaction model (Jordan, answer 5): the wizard is the spine, hand-edit is a right, not a mode. Concretely:

• The job moves through the eight stages above, shown as a progress rail. "Next" runs the automatic work for the following stage.
• At every stage the operator can hand-edit as much as he decides — every automatic result is an editable proposal, not a verdict. Edits re-run the affected checks live; a hand edit never bypasses a gate, it just changes the input the gate judges.
• Gates block advance, with the reason in plain words. A gate is never silent and never a guess: the app states what was detected, what was measured, and what number decided it (the house rule: always state the result). Where the operator may override, the override is recorded to the audit trail with who and when.
• The original file is a base layer everywhere — thick gray, toggleable — with healed/generated work overlaid (the standing house style, straight from the comparison board).
• Sub-wizard depth for the two hard screens (heal review, cut plan): everything has a sane default, so an operator who trusts the defaults clicks through in seconds, and one who doesn't can drill to any single vertex, tab or lead.

3. The eight stages, screen by screen

Each stage below lists: what the app does automatically / what the operator can hand-edit / what gates block "Next" / what the audit trail records.

3.1 Intake

• Auto: create the job (customer, description, due date); accept files by drag and drop; per file detect type; for DXF run units detection and show WHAT was detected and WHY (INSUNITS, coordinate magnitude, sanity vs stated size); for .ai/PDF/SVG demand the stated dimension before the file is accepted at all. Operator picks material × thickness (from the materials table) and target machine (from the machine profiles) — both required up front because beam comp, kerf, lead lengths and the envelope all hang off them.
• Auto (W1, from the -61 walkthrough): classify what the file IS — one part, several parts, or a finished nest — propose the answer, operator confirms. A finished nest may be cut as-drawn (the nest stage becomes verify-only) or exploded into parts for re-nesting.
• Auto (W2): if the material row exists but is incomplete (e.g. no beam comp), say so NOW — "prep may proceed, posting will be blocked until the value is supplied" — as a banner the job carries, not a surprise at post.
• Every gate judges measured geometry, never header claims (the -61's header lies about both units and extents; the geometry doesn't).
• Hand-edit: override detected units (recorded); enter/correct stated dimensions; quantity per part.
• Gates: no file without resolved units/scale; material row must exist (a missing row is a named error, never a fallback to a neighbouring thickness); machine chosen.
• Audit: who created the job, files as received (originals kept immutable), every unit/scale decision, the file-kind call (W1).

3.2 Heal

• Auto: heal each part to true arcs. Tolerance is assigned per feature class, by function (Jordan's business rule): decorative/lettering, mating holes, outer profile — the app proposes the classification, with the class visible on the drawing as color.
• Hand-edit: reassign a feature's class; change a class's tolerance for this job; force a vertex to stay a corner or be smoothed (spike-vs-sustained override); the sub-tolerance smoothing budget is shown, not hidden.
• Gates: zero fit-induced kinks; fidelity within the class tolerance measured against the TRUE source; four-decimal floor respected. PASS/FAIL banner per part with the measured number — never the word "identical" unless it is 100%.
• Audit: tolerance choices, class overrides, measured fidelity per part.

3.3 QC

• Auto: topology — open contours, doubled lines, self-intersections; island detection; minimum feature width vs beam comp (the interference-alarm gate); part-vs-envelope sanity. Every check listed with its result, pass or fail, and the number behind it.
• Auto, islands (Jordan's Q2 answer): every floating island (an 'O' centre, text counters, floating art) gets bridges placed automatically — sized from the table, avoiding lead/tab spans per the standing rule — and every placed bridge is flagged on screen, never silent.
• Hand-edit: fix small topology problems in place (close a gap under the autoclose table value, delete a doubled line); move, resize or delete any auto-placed bridge (deleting the last bridge on an island re-flags the island as unheld). Everything bigger goes back to the customer or to the operator's own CAD.
• Gates: no open cut contour; no feature below beam comp on a compensated path; no island left unheld without an explicit operator waiver.
• Audit: each defect found, and whether it was auto-fixed, hand-fixed, waived, or bounced; every bridge placement and edit.

3.4 Part review

• Auto: generate the customer sheet and shop sheet for the part set — one dataset, two renderers, exactly per the standing split rule.
• Hand-edit: none on the numbers (they are derived); notes to the customer.
• Gate: an owner/operator approves the geometry for production — the explicit staging step Jordan asked the audit trail to carry.
• Audit: who approved which revision of which part, when.

3.5 Nest

• Auto: pack the approved parts on the chosen sheet; rotation variants must buy real packing (the 0.1" rule) so parts don't spin for nothing and carry tabs off the lower-right; spacing from the tables; sheet from stock sizes.
• Hand-edit: drag, rotate, add/remove copies, lock a part, choose a different sheet. Yield shown live.
• W1 path: a job taken in as a finished nest, cut as-drawn skips packing; this screen verifies instead — envelope, spacing, yield stated — and any edit converts it to a normal editable nest.
• Gates: nothing outside the sheet; sheet inside the machine envelope (80 × 160 on the current laser — from the machine profile, not a constant); spacing respected.
• Audit: final placement, yield, who adjusted what.

3.6 Cut plan (tabs, leads, order — after the nest, in sheet frame)

• Auto: slug-retention tabs from the material table (drop-through from the machine profile; smallest tab that holds; traffic rule for over-drop slugs); start points on flats with the lower-right bias; leads sized from thickness with the clear-air pierce standoff scored in every direction; cut order greedy-safe (outer last, never rapid over a held piece), crossings counted and shown, never silent.
• Auto + declare (W3, from the novi walkthrough): cutter comp is declared here, never inferred — default is the shop norm (G41, holes CCW / outer CW); text and art may be declared G40 per contour class to duck interference alarms. The declaration is per job, visible, audited.
• Hand-edit: slide a start point/tab along its contour (the app re-scores the pierce standoff and tab-on-flat rules live and says if the new spot is worse and why); force a tab wider; reorder cuts within safety.
• Gates: no lead or pierce inside any tab span; no pierce below standoff without being listed; unresolvable crossings reported on the shop sheet.
• Audit: every hand-moved tab/start/order change, with the app's scored opinion at the time.

3.7 Post

• Auto: Fanuc macro-B out. Program number by the n+1 strategy (Jordan, 2026-08-17, answering Q4): the app proposes the next free O-number in the machine's scheme — reserved ranges respected, collisions checked against the archive — and the operator can always override, with the override audited and re-checked for collision; micro-segment cleanup keyed to beam comp; arc-center ceiling with sag-gated chording; nc_audit runs on the posted file automatically and its report is shown — a program that fails audit cannot be released; slug report CSV numbered for shop feedback.
• Hand-edit: none on the G-code itself. A post is regenerated from upstream edits, never patched by hand in the app.
• Gates: material row must carry beam comp (a row without it cannot post — the deliberate MaterialIncomplete rule); audit must pass.
• Release check (W4, from the 33215 walkthrough): the release screen lists every table value with provenance ASSUMED that this post consumed, and the owner either confirms it (promoting it to "decided") or accepts it for this job only — recorded either way. Live example: the 1/2" beam comp of .020, read from 33215.NC and never yet confirmed. Jordan's ruling on how this works in practice (2026-08-17): "We will have to field verify the numbers, but if you pull them from the table as discussed we can easily just change it in the table." So: assumed values ride from the table (never baked into code or a job), the release screen shows them, and field verification lands as a plain table edit — provenance flips to measured, every later post picks it up.
• Audit: program number, audit result, who posted, W4 confirmations.

3.8 Deliver + archive

• Auto: the delivery set — NC program(s), MetaCam-safe DXF (the R12 profile writer, always), slug report, customer sheet, shop sheet — written to a folder/USB for the shop floor (who are file recipients, not app users). Job archived complete: sources, healed geometry, nest, NC, audit, event log.
• Hand-edit: none; re-open the job to change anything, which creates a new revision, never rewrites history.
• Audit: what was delivered, when, by whom. The archive is searchable by customer, date, material, machine, operator.

4. Roles and identity

Two in-app roles (Jordan, answer 4). The app is offline, so identity is local: per-operator accounts on the shop PC, owner administers them.

• Owner/operator — everything: jobs end to end, posting, approving, the materials/machine tables, table provenance edits, user administration.
• Sales/estimator — scope set by Jordan (2026-08-17, answering Q1): the role exists for quoting. Sales can create a job, run intake → heal → QC to answer "is this file production-ready?", and — the key addition — run the nest to see yield and material usage, so the material they quote a client per order is checked against a real nest, not a guess. A sales nest is saved on the job as a quote nest; production still requires an owner/operator to approve the geometry (3.4) and to own the nest that actually cuts — the approval and post gates are unchanged. Sales cannot edit any table, cannot approve for production, cannot post. When the estimator module arrives later it lands inside this role, reading the same quote nests.
• Shop floor — not an app user; receives the delivery set as files.

Identity — options for a multi-workstation shop (Jordan's Q3: choose one)

Reality to design for: several workstations per shop, operators sharing a workstation, switching that must be as effortless as macOS fast user switching — or the audit trail dies of friction. All options are fully offline from the internet; "shared" means the shop's own LAN.

• Shared shop data, wherever you log in (common to all options): the job archive, tables, users and audit trail live in ONE shop-local store (a shared folder or a tiny service on any shop PC/NAS); every workstation attaches to it. An operator's identity follows them to any workstation, and two people can work different jobs at once. One job open for edit on one screen at a time.
• Option A — user ID + PIN fast-switch (recommended default): every operator has an account with a 4–6 digit PIN; a switch-user button (or idle timeout) drops to the user list from any screen, two seconds to swap, exactly the macOS pattern. Strong enough to make the audit trail honest inside a trusted shop; light enough that nobody shares a login out of laziness.
• Option B — password + biometric where the hardware has it: full password per account, satisfied day-to-day by the machine's own biometrics (Windows Hello fingerprint/face, Mac Touch ID) so routine switching is still one touch. Heavier to administer; right if the shop wants real authentication, not just attribution.
• Option C — tiered (A + B combined): operators switch with a PIN; owner-only actions (table edits, user admin, license) demand the stronger factor — password or biometric — at the moment of the action. Attribution stays effortless, the dangerous buttons get a real lock.
• DECIDED: Option C (Aristide, 2026-08-17). PIN to switch for everyday work; password or biometric demanded at owner-only actions (table edits, user admin, license). Every audit event carries operator + workstation + time.

Audit trail (Jordan, answer 6): append-only per-job event log — import, every edit (with what changed), stage transitions, approvals, posts, deliveries — stamped with operator and time. Several operators per location, several lasers: every job carries its machine, every event its operator. The archive view can answer "who approved this, who moved that tab, which program went to which laser."

5. Data the app owns (the tables become screens)

Everything CLAUDE.md forbids as a Python literal becomes an editable table with provenance — this is the owner-role heart of the app:

• Machine profiles (one per laser, multi-machine from day one — answer 3): envelope, drop-through, start_clock, comp register, arc-center ceiling, chord-sag max, dialect/post options, program-number scheme. Plus the setup/verify methodology as a defined variable: a structured, per-machine checklist/procedure slot whose CONTENT Jordan and Aristide will author — the app stores, versions and displays it, and can require it to be marked done before first post to a new machine. Machine swap on a live job (W5): heal/QC are per-part and survive; the nest re-validates against the new envelope; cut plan and post re-run (drop-through, start clock, tab tables, dialect, comp register may all differ). The app shows what changed and why before anything re-posts — a job never silently keeps the first machine's numbers.
• Materials table (rows per material × thickness): kerf, beam comp, lead length, tab widths and thresholds, autoclose gap, spacing — every value carries provenance (measured / decided / assumed) and the unsourced list is one click away. A missing value blocks the dependent stage by name.
• Preferences: start-clock, lower-right bias strength, default tolerances per feature class — operator-overridable per job, defaults owned by owner.
• Job archive: as in 3.8.

Table edits are owner-only, audited, and take effect on the next stage run — never silently on posted work.

6. House rules carried into every screen

• Original file = toggleable thick-gray base layer, everywhere geometry shows.
• Every automatic check states its result and its number; nothing silent.
• Four decimals is the display resolution of everything we hand over.
• "Identical" is never displayed unless it is a true 100% match.
• Customer sheet and shop sheet are always split, one dataset, two renderers.
• All shop-bound DXF goes through the MetaCam-safe writer.

7. Pipeline order — folding in Aristide's ruling

Aristide: "tabbing is the LAST thing you should do — the order is wrong." The design adopts it as the spine order you see in section 3: nest for material first, freeze placement, then choose tabs/leads/start points at cut plan in the SHEET frame — the nest reserves blanket lower-right lead room so the cut plan always has air to work with. Walking through this on paper with the -61 nest is the test that the order works; sign-off on this document records the ruling.

8. Paper walkthrough — RUN 2026-08-17 (report: design/walkthrough-2026-08-17.md, hosted at /design/walkthrough/)

Done, minus the .ai leg — deferred by Aristide ("we still need some work on those before that leg is done"); it runs when that leg is ready. The spine held on all three jobs and all eight edge cases; five findings (W1–W5) are folded into this document at the marked sections. All five findings APPROVED by Jordan (2026-08-17): W1, W2, W3, W5 plainly; W4 with the ruling quoted in §3.7 — values ride from the table, field verification is a table edit. The plan as executed:

• The -61 nest (dirty customer DXF, 48 parts, slugs over drop-through, the traffic rule) — exercises heal, QC, nest, cut plan, the order ruling.
• The novi sign (art, G40 declaration, the lead-standoff-in-clear-air lesson, letters with islands) — exercises feature classes, Q2's island answer, small-hole standoff fallback.
• 33215 / O100 (half-inch, comp register, stated-dimension macro grid) — exercises material table, beam comp gate, post + audit.
• A dirty customer .ai (stated dimension, Bézier refit) — exercises intake's scale demand and the vector front end. DEFERRED (Aristide, 2026-08-17) until the .ai leg is ready.

Edge cases to walk deliberately: a DXF with no units header; a part bigger than the envelope; a material row missing beam comp; an island with no bridges module; a hole under 0.300"; a sales login trying to post; two operators touching one job; a job moved to a second machine after nesting.

9. The four questions — ANSWERED (Jordan, 2026-08-17, Aristide present)

• Sales role — "It will be more for quoting purposes so they would need access to the nesting and double check that the material usage that they are going to be quoting the client per order is accurate." → Sales gets the nest for quoting; folded into section 4 (quote nest vs production nest; approval and post gates unchanged).
• Islands — "It should automate it, flag it, make it easy for operator to double check it and edit it if he wants." → Automatic bridges move INTO v1; folded into sections 1 and 3.3.
• Login — "Consider a shop having multiple workstations, consider operators sharing a workstation, consider the way MAC OS allows you to switch between users… a user ID + password/biometric. Give us some good options here." → Three options written out in section 4; DECIDED: Option C (Aristide, 2026-08-17) — PIN to switch, password/biometric on owner-only actions. No questions remain open; the document is complete and ready for the paper walkthrough.
• Program numbers — "Operator can always override, but we would like to have a strategy of n+1." → App proposes next free O-number per machine scheme, operator override always, audited; folded into section 3.7.