wip: preserve local engine and agent workflow changes before ganjihong refactor integration

backend/agent/skills/cad-authoring/SKILL.md

@@ -0,0 +1,165 @@
+# 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.