ParaShape

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) in spec/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 under crates/ also needs cargo check --workspace and, for a wire-type change, the export_bindings test 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

AreaWhat it decidesSection of AGENTS.md
Settled engineWhen the schema counts as frozen: no derivable field, every operation proven against an external truth.Settled engine
Field lawEvery persisted field is classed geometry, identity or intent; caches, hints and flags do not exist.Settled engine
Shape lawCurve and Mesh are final; their face loops, validity and the closed-solid rule.Settled engine; Notable methods & laws
Model JSONThe node law, parameters, objects, properties, behaviors, origin and size laws.Model JSON - CURRENT
Component lawIsolated placed documents, lazy resolution, choosers, systems.COMPONENT LAW
ExpressionsNamespaces, grammar, the stream, onClick and Property.Expression namespaces and the stream
Kernel lawsWhat belongs in the core, booleans, chains, transforms, type design, fail-loud errors.Kernel laws
Engine architectureDoors, the audit, no geometry in TypeScript, one JavaScript boundary.Engine architecture
ConstantsEvery constant is derived, measured or inherited, and no number exists only to make geometry pass.Debt, and constants
No compatibility layerA shape is current or gone; unknown keys fail validation.No compatibility layer
UIRoute, error, link, header and layout rules for every page.UI laws
Hosts and routesOne origin, public model pages, the SketchUp plugin.Hosts and routes
TestingA 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.

Edit on GitHub