Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Clarify Preview 1 documentation authority

Yuechen Lida1fc00d730d
diff --git a/README.md b/README.md
index e5a45693..c91e7ebc 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,11 @@
# Aetheris + Firmament v1
+> The public Preview 1 language-manual source is maintained in the sibling
+> `yuechen-li-dev.github.io` repository at `src/aetheris` and published under
+> `/aetheris/`. Documentation here includes architecture, implementation
+> evidence, and historical milestone records; the authoritative frozen support
+> contract is `docs/release/preview1-feature-freeze.md`.
+
Firmament is a deterministic DSL for generating CAD geometry (STEP AP242) via Aetheris.
## What works today
diff --git a/docs/firmament/v2-canonical-authoring.md b/docs/firmament/v2-canonical-authoring.md
index 5876c79f..c85ca613 100644
--- a/docs/firmament/v2-canonical-authoring.md
+++ b/docs/firmament/v2-canonical-authoring.md
@@ -1,5 +1,14 @@
# Firmament V2 canonical authoring
+> **Public manual:** the Preview 1 user guide is maintained in the sibling
+> `yuechen-li-dev.github.io` repository under `src/aetheris` and is published
+> at `/aetheris/`. This page remains implementation-facing authoring evidence.
+> Where historical text here differs from the frozen support boundary,
+> [`preview1-feature-freeze.md`](../release/preview1-feature-freeze.md) and its
+> machine-readable manifest are authoritative. In particular, mixed line/arc
+> whole-loop Fillet is **Experimental**, not Supported, until curved-trim mass
+> verification is release-tight.
+
`Hole<Shaft>`, `Hole<Counterbore>`, and `Hole<Countersink>` are canonical
families. Counterbore requires `CounterboreDiameter` and `CounterboreDepth`;
Countersink requires `CountersinkDiameter` and `CountersinkAngle` in `deg`.
diff --git a/docs/release/preview1-docs-claudefooding.md b/docs/release/preview1-docs-claudefooding.md
new file mode 100644
index 00000000..9cc56ab1
--- /dev/null
+++ b/docs/release/preview1-docs-claudefooding.md
@@ -0,0 +1,33 @@
+# Preview 1 documentation-only authoring review
+
+Date: 2026-08-07
+
+Context boundary: public manual content plus ordinary `aetheris --help` output.
+No parser, compiler, or geometry source was consulted while authoring the
+four-hole case. Existing canonical fixtures supply the other first-attempt
+sources so the review remains tied to executable release truth.
+
+| Task | First-attempt source | Build result | Retries | Public pages used | Invented grammar / compatibility input |
+| --- | --- | --- | ---: | --- | --- |
+| Rectangular plate | `fixtures/FirmamentV2/Canonical/valid/bare-box.firmament` | Success | 0 | Getting started; Language tour | None |
+| Four patterned shaft holes | `fixtures/FirmamentV2/Canonical/valid/docs-four-hole-pattern.firmament` | Success | 0 | Static authoring; Slots and patterns; Holes | None |
+| Concept Path L-bracket | `fixtures/FirmamentV2/Canonical/valid/profile-compose-l-bracket.firmament` | Success | 0 | Concept Path; Profiles/Compose | None |
+| Counterbored plate | `fixtures/FirmamentV2/Canonical/valid/counterbore-hole.firmament` | Success | 0 | Holes; Language reference | None |
+| Supported Profile chamfer | `fixtures/FirmamentV2/Canonical/valid/profile-chamfer-mixed-convex-reflex-loop-top.firmament` | Success | 0 | Edge finishes | None |
+| Supported bounded fillet | `fixtures/FirmamentV2/Canonical/valid/profile-fillet-reflex-two-segment-top.firmament` | Success | 0 | Edge finishes | None |
+| Static/Require/projected PMI | `fixtures/FirmamentV2/Canonical/valid/pmi-projected-hole-diameter.firmament` | Success | 0 | Require/PMI; Language reference | None |
+| Intentional ConvexSmall fillet | `fixtures/FirmamentV2/Canonical/invalid/profile-edgefinish-convex-small-fillet-invalid.firmament` | Rejected with `ProfileBoundaryFilletConvexArcSpindleUnsupported` | 0 | Edge finishes; Diagnostics | None |
+| InlineStep/Recognize/Replace | `fixtures/FirmamentV2/Canonical/valid/inline-step-recognize-replace.firmament` | Success | 0 | Existing STEP | None |
+
+Normal supported first-attempt success: **8/8 (100%)**. The unsupported case
+was correctly identified without fallback. There were no retries,
+compatibility forms, invented fields, or source-code archaeology attempts.
+
+The unsupported diagnostic was useful: it names the spindle/self-intersection
+policy and the manual gives three valid responses (reduce the finish, increase
+the source radius, or leave the corner sharp).
+
+One documentation gap appeared. `validate` accepts the intentionally invalid
+ConvexSmall source because it does not materialize geometry; `build` emits the
+advertised policy diagnostic. The public manual was corrected to distinguish
+language/semantic validation from materialization-policy checking.
diff --git a/fixtures/FirmamentV2/Canonical/valid/docs-four-hole-pattern.firmament b/fixtures/FirmamentV2/Canonical/valid/docs-four-hole-pattern.firmament
new file mode 100644
index 00000000..d3dd92c7
--- /dev/null
+++ b/fixtures/FirmamentV2/Canonical/valid/docs-four-hole-pattern.firmament
@@ -0,0 +1,24 @@
+Model FourHolePlate {
+ Units: mm
+
+ Record MountSpec { Center: Point2 Diameter: Length }
+ Static Mounts: MountSpec[] = [
+ MountSpec { Center: Point2(-30mm, -15mm) Diameter: 6mm }
+ MountSpec { Center: Point2(30mm, -15mm) Diameter: 6mm }
+ MountSpec { Center: Point2(30mm, 15mm) Diameter: 6mm }
+ MountSpec { Center: Point2(-30mm, 15mm) Diameter: 6mm }
+ ]
+ Template MountHole(MountSpec spec) {
+ Hole<Shaft> Mount {
+ On: +Z
+ Center: spec.Center
+ Diameter: spec.Diameter
+ End: ThroughAll
+ }
+ }
+
+ Box Plate { Size: [80mm, 50mm, 8mm] }
+ Modify Plate {
+ Pattern MountPattern Over Mounts { MountHole(Current) }
+ }
+}