Laws for contributors
The laws live in AGENTS.md at the repository root and win over any other document on conflict. This page is a map: it names each area and where its rule is written, and does not restate the rules. spec/ holds concepts, product and requirements; spec/README.md is its index.
Before you change anything
- Every feature has a requirement row (
ID | Given | When | Then | Source) inspec/requirements, in the same commit as the behavior. - The gate is
pnpm test(typecheck, format, unused-code check, class law and the per-package closed-form checks). A change undercrates/also needscargo check --workspaceand, for a wire-type change, theexport_bindingstest with the regenerated types committed. - A change fixes what it opens: no deferral, ledger, skipped test or phase-two note. A red gate is fixed or the change that reddened it comes out.
- Commits go straight to
main, and a push is a production deploy.
Where each rule is written
| Area | What it decides | Section of AGENTS.md |
|---|---|---|
| Settled engine | When the schema counts as frozen: no derivable field, every operation proven against an external truth. | Settled engine |
| Field law | Every persisted field is classed geometry, identity or intent; caches, hints and flags do not exist. | Settled engine |
| Shape law | Curve and Mesh are final; their face loops, validity and the closed-solid rule. | Settled engine; Notable methods & laws |
| Model JSON | The node law, parameters, objects, properties, behaviors, origin and size laws. | Model JSON - CURRENT |
| Component law | Isolated placed documents, lazy resolution, choosers, systems. | COMPONENT LAW |
| Expressions | Namespaces, grammar, the stream, onClick and Property. | Expression namespaces and the stream |
| Kernel laws | What belongs in the core, booleans, chains, transforms, type design, fail-loud errors. | Kernel laws |
| Engine architecture | Doors, the audit, no geometry in TypeScript, one JavaScript boundary. | Engine architecture |
| Constants | Every constant is derived, measured or inherited, and no number exists only to make geometry pass. | Debt, and constants |
| No compatibility layer | A shape is current or gone; unknown keys fail validation. | No compatibility layer |
| UI | Route, error, link, header and layout rules for every page. | UI laws |
| Hosts and routes | One origin, public model pages, the SketchUp plugin. | Hosts and routes |
| Testing | A kernel test names an external truth: a formula, an invariant or a cited reference. | Testing and dev |
Kernel algorithms
Two-dimensional boolean and offset operations use the in-tree Clipper2 port in crates/curve/src/clipper2; three-dimensional booleans use the in-tree triangle_boolean. A defect in a kernel algorithm is fixed in the algorithm, not worked around with a tolerance or a special case. Ported code keeps its copyright and license notices.
Writing a model
Models are authored through the MCP server and its manual (see Getting started). The modelling conventions are spec/conventions.md and spec/modelling-standard.md; the one rule that shapes every document is minimal nodes: one node per operation of the real construction, never a typed coordinate.
Documentation
These pages are built from apps/app/src/docs. The catalog reference and the engine API lists are generated from the engine, so they are changed by changing the engine, never by editing a page. Hand-written pages cite the law they summarize; when a law changes, the page changes in the same commit. The repository is at https://github.com/huukhanhnguyen/parashape.