# Authoring CDSL Modeling Guide

Write one complete `cad.author.v1` document. It is declarative source for a
server compiler, not the runtime CDSL and not an execution log. Return only
the schema-valid object requested by the tool.

## Contract Boundary

Use lower-case local `name` values for bodies and features. They are symbols
within this document only. Never emit an `id`, `feature_id`, `sketch_id`,
`body_id`, `task_id`, revision, candidate, stable topology identifier,
snapshot, owner identifier, selector token, or `host_face`/`mirror_plane`
inside `params`. The server allocates identities and injects selector values
into the destination stated by the operation contract.

Use millimetres and a right-handed coordinate system unless the request says
otherwise. Put every reasonable but unstated design choice in `assumptions`.
Do not turn an assumed dimension into a deterministic acceptance target.

## Modeling Brief

Before authoring, derive this internal brief from the requirements:

- part or multi-body intent; explicit dimensions and units;
- functional datums, origin, base plane, and positive directions;
- primary volumes, holes, pockets, bosses, ribs, patterns, and finishing;
- explicitly verifiable targets versus manual targets;
- assumptions that do not affect fit, safety, or compliance.

Dimensioned request facts take precedence over proportions inferred from an
image. Ask for clarification only when a missing interface, scale, safety, or
compliance value makes construction impossible. Otherwise choose a practical
engineering default and record it as an assumption.

## Construction Order

Choose the simplest supported construction whose parameters directly express
the requested dimensions. Use a stable order:

1. establish the body and functional coordinate frame;
2. create primary additive volume(s);
3. create any selector-hosted feature before its named source output is
   changed by a fuse, cut, shell, pattern, or finishing operation;
4. add remaining bosses, ribs, and other major additive geometry;
5. make remaining pockets, bores, and through features;
6. apply patterns, then fillets and chamfers last.

Every feature must list each feature it actually uses in `depends_on`.
Prefer one complete profile-driven feature for a planar silhouette. Use
primitives when their axis, radius, and height directly express the part.
For through cuts, choose the operation's through extent and make the tool
cross the material; never rely on coincident faces or a guessed nearby face.
Delay dress-up operations because they can alter downstream topology.

The selector-source rule is an intentional exception to a generic “all adds,
then all cuts” sequence. For example, a bolt circle hosted on an original
flange cap must be placed immediately after the base when later additive
fusions replace that exact cap. A required final through-cut can still follow
all additive features and the earlier bolt operation.

Use only the supplied operation list. Follow each operation's parameter schema
exactly, including required sketch state. Do not invent unsupported operation
parameters, implicit booleans, or a substitute operation after a capability
error.

## Sketches And Coordinates

Keep a sketch to exactly `workplane` and `profile`. The workplane declares its
origin, `x_dir`, and normal. Profile coordinates are local to that workplane.
For primitive axes, `origin_mm` is the start-cap center and `direction` is the
positive build direction. For a selector-hosted hole, position coordinates are
world coordinates unless the operation contract explicitly says otherwise.

The Authoring sketch syntax is deliberately smaller than Runtime CDSL. For
every sketch operation, emit exactly this shape. `profile` is singular,
circles use the requested `diameter_mm`, and the local center is `center_mm`:

```json
{
  "workplane": {
    "origin_mm": [0, 0, 12],
    "x_dir": [1, 0, 0],
    "normal": [0, 0, 1]
  },
  "profile": {
    "type": "circle",
    "diameter_mm": 56,
    "center_mm": [0, 0]
  }
}
```

Do not write `profiles`, `plane`, `support`, `radius_mm`, `center`, or any
other key inside an Authoring sketch. The compiler derives Runtime radius and
sketch identity. Use a primitive such as `cylinder_add` when its axis, radius,
and height directly express the requested geometry and no sketch is needed.

Name features for their manufacturing role, for example `base_plate`,
`front_hub_boss`, `center_bore`, and `bolt_holes`. Names make dependencies and
repair diagnostics readable; they are not server identities.

## Selectors

The operation metadata states whether `selectors` are required, their kind,
cardinality, and server-side destination. Put only declarative selectors in a
feature's `selectors` array. Never write the destination field itself inside
`params`.

For an output face, use an exact local role embedded in `source` and state a
unique match:

```json
{
  "kind": "face",
  "source": "front_hub_boss.top_planar_face",
  "match": "unique"
}
```

Do not add `role`, `query`, `host_face`, a face index, a coordinate selector,
or a Runtime selector token. The `source` value is the complete local intent.
The compiler adds its source feature as an auditable graph dependency; include
other true construction dependencies in `depends_on` yourself.

`top_planar_face` and `end_face` mean the positive-direction cap of a supported
extrude, sweep, loft, or cylinder. `bottom_planar_face` and `start_face` mean
the opposite cap. Select the most recent feature whose output is known to be
the required host; do not select a similar face by location, face index, or
proximity.

Translate a request's descriptive `max_z`/`min_z` wording into these output
roles before writing CDSL. Never emit `base.max_z_face` or `base.min_z_face`.
For a cylinder built in `+Z`, the top cap is `top_planar_face` and the bottom
cap is `bottom_planar_face`; reverse-direction features swap their world-Z
position but retain their own start/end roles.

`hole_wizard` requires exactly one `face` selector. It uses that selector as
its host face, so a central bore on a hub should select the hub cap, while a
bolt circle on an exposed flange should select the flange cap. A selector must
name a host that contains every requested hole position. If that cannot be
made unique, redesign the feature sequence or omit the unsupported feature;
never guess a face.

Before creating a hosted hole, calculate each position against the actual host
face. A local boss can be the global highest face while being too small to host
a larger bolt circle. In that case use the exposed flange cap at the bolt
radius, with its own plane height, rather than the global maximum-Z cap. Place
the hosted holes while that source cap's exact provenance is still active:
before a later fusion or cut would split, remove, or replace it. A final
through-cut may still follow all additive features, so a bolt circle can be
hosted before an unrelated final boss and before that final cut.

## Acceptance And Repair

Describe only user-requested, measurable acceptance targets in
`acceptance_targets`; leave inferred dimensions in `assumptions`. On repair,
return a complete replacement document. Preserve feature names and every
feature listed in `executed_feature_ids`, except a feature explicitly named by
the diagnostic. Features that were never executed may be changed freely to
repair an invalid selector, parameter, dependency, or geometry construction.

Read structured diagnostics literally. Fix their named cause with the smallest
document change, then return the entire document. Do not add internal IDs,
weaken a requested value, silently delete a failed feature, or replace a
failed selector with an arbitrary topology element.