Engineering workflows

Open Designs (/app/designs) after signing in. The workspace presents a reusable engineering library, project assembly tree, inspector, configuration tools, native build history, and release review. Work in the personal scope by default; organization scope is available only when your account has access to one.

Begin a project

For a quick tour, select Create synthetic demo. It creates a public synthetic proving system and selects the new project. The example contains two devices, reusable boards, a shell, and a cable with explicitly incomplete electrical facts. Use it to learn navigation and evidence flows, not as a manufacturing design.

For your own work, create a New private project. Create reusable definitions in the library by choosing a title and discipline (assembly, board, cable, device, hardware, interface, or shell). Each new definition starts as a draft with unknown or illustrative fields. The definition is shared within its authorized scope; projects refer to exact revisions rather than copying the definition.

Select a definition to inspect or edit its draft. Save draft changes before freezing. Freeze saved draft creates an immutable revision. Later changes create a new draft/revision; they do not rewrite the frozen record. To use a revision as the project's root, select it and choose Set this revision as project root. In the project tree, select an occurrence to inspect its instance path and contained revisions. Shared boards and parts can appear in multiple assemblies while remaining one definition.

When editing an assembly, link contained instances to exact revision IDs and record relationships, placements, ports, and configuration explicitly. A containment relationship builds the assembly tree; electrical connection, physical mating, mounting, and exposed ports describe different engineering facts. Do not use containment or a cable continuity path to imply active conversion or electrical compatibility.

Evaluate a configuration

Use Configuration and board/shell builds on a selected project. Publish or select a rule pack, choose the requested options, and evaluate the saved choice. Review the result and its explanation, including missing facts and proposal states. A configurable candidate or development proposal is not an existing released solution. Rule-pack claims about real revisions require supported source evidence; a passing synthetic rule pack only proves its declared synthetic specification.

Queue a native CAD build

The build panel accepts an exact frozen board revision and shell revision from the selected project's revision closure. Select both inputs and choose Queue build. Review the resulting job state, source hashes, toolchain and recipe provenance, logs, artifacts, and parsed checks. Builds retain their inputs and history; creating another build does not replace prior evidence.

The web app and ordinary queue worker do not execute engineering.cad. Native jobs need a separately provisioned isolated Node worker with SPECMATE_NATIVE_RUNNER=1, a reviewed native tool installation, and the same development database/queue and scoped private object storage. The deployment configuration uses SPECMATE_CAD_SOURCE_ROOT and SPECMATE_OPENSCAD_ROOT to identify the worker source and OpenSCAD tool root. Follow the detailed CAD worker operator guide for the bounded runner setup, and keep CAD tools, Docker access, and application secrets out of web requests. Do not enable a native worker solely to explore the synthetic demo.

The current bounded recipe produces a passive two-contact PCB and parametric shell example. It is not general-purpose conversion of imported CAD into hardware. Imported originals remain byte-preserved; an editable derivative is a separate artifact. A successful process and clean ERC/DRC or mesh checks do not establish fit, printability, electrical performance, or bench behavior.

Review and export a release

The release panel requires a saved valid configuration, at least one successful build, and an explicit acknowledgement that physical unknowns remain. Choose the intended BOM scope (assembly, procurement, fabrication, or consumables) and review the package manifest, pinned revisions, assets, rights, artifacts, source hashes, configuration explanation, build evidence, and unresolved checks. Unknown asset rights or missing evidence can block creation or export. Treat a review release as a frozen evidence package, not proof of qualification.

Release JSON is portable and records provenance for review. Verify downloaded packages and keep source and artifact rights attached when transferring them. Optional signed release webhooks are server-configured and delivered through the existing durable delivery contract; they are not required to use Specmate. A receiving system should verify the signature over raw request bytes and deduplicate event IDs before applying effects.

Engineering API

Machine clients can use the versioned engineering API described by /api/openapi.json at a running instance. Open API Keys at /app/api-keys, create a key, and grant the required engineering read/write permissions. The key is shown once; store it in a server-side secret manager. Requests also obey the current personal or organization workspace authorization; a project-only key does not grant engineering access. Do not paste key material into prompts, source files, or issue reports.

The API exposes projects, definitions and drafts, immutable revisions, rule packs/configurations, builds, releases, and authorized artifacts under /api/v1/engineering. The downloadable release package and artifact routes apply authorization and integrity checks. Consult the live OpenAPI document for operation paths, schemas, and required permissions; do not assume an undocumented operation exists.

Evidence and physical review

Keep measured facts separate from estimates and synthetic declarations. Record units, coordinate frames, instance paths, source hashes, tool versions, provenance, and explicit unresolved states. Unknown must remain unknown until supported evidence is reviewed. CAD checks, BOMs, package integrity, renders, and successful queue jobs are useful engineering evidence, but they do not replace dimensional measurement, printability review, electrical testing, or bench validation. FDM/resin slicing, printer submission, firmware, and physical validation are outside the current workflow.