# CDSL Author Guidance Corpus

This corpus is a Chinese-first, non-authoritative author aid. The runtime
operation contract, fragment schema, topology/reference tokens, preflight and
verifier evidence always win over these Markdown files. The manifest maps
only workflow phase, scheduled atomic operation and repair state; it never
classifies the user's part request.

## Source Migration

| Source reference | CDSL target sections | Intentionally excluded |
| --- | --- | --- |
| `cad-brief.md` | `01`, `02`, `09` | Python/file workflow |
| `parameters.md` | `02`, `07` | sidecars, animation, viewer control |
| `positioning.md` | `03`, `06`, `op-reference` | assemblies, joints, `Location`, imported STEP placement |
| `build123d-modeling.md` | `03` through `08`, operation appendices | build123d APIs, labels, colors and assembly source |
| `build123d-modeling.zh-CN.md` | all Chinese terminology and rule review | a duplicate competing rule set |
| `inspection-and-validation.md` | `09`, `10` | CLI paths and selector syntax |
| `snapshot-review.md` | `09` | renderer commands |
| `repair-loop.md` | `10`, `05`, `06`, `08` | build123d-only remediation syntax |
| `step-generation.md` | `00`, `09` | Python generator commands |
| `supported-exports.md` | `09` | mesh tolerance and exporter-specific flags |

## Selection Contract

- Requirements authoring selects `00` to `03`.
- Feature planning selects `00`, `02`, `03`, `04`, `07`, and `08`.
- A scheduled feature selects `00`, `03` to `06`, `08`, and its current
  operation appendix.
- Repair selects `00`, `03`, `06`, `09`, `10`, and its operation appendix.
- Final validation selects `00`, `09`, and `10`.

At a bounded prompt budget, contract, coordinate/datum, and the scheduled
operation appendix are mandatory. Other sections are included in stable
priority order. A malformed corpus or an unsupported operation registry
falls back to the original short author prompt and records fallback metadata
with the author usage record.

## Evaluation Commands

Run the six matched control scenarios three times each, first without and
then with guidance:

```bash
PYTHONPATH=backend python -m app.cad_agent.evals.live --suite comprehensive --repetitions 3 --author-guidance off \
  --scenario rectangular_mounting_plate --scenario circular_flange_pcd \
  --scenario obround_slot_plate --scenario rounded_rectangular_pocket \
  --scenario double_hole_linkage_arm --scenario l_bracket

PYTHONPATH=backend python -m app.cad_agent.evals.live --suite comprehensive --repetitions 3 --author-guidance on \
  --scenario rectangular_mounting_plate --scenario circular_flange_pcd \
  --scenario obround_slot_plate --scenario rounded_rectangular_pocket \
  --scenario double_hole_linkage_arm --scenario l_bracket

PYTHONPATH=backend python -m app.cad_agent.evals.live --compare-guidance-reports CONTROL/report.json TREATMENT/report.json
```

The comparator excludes declared validation gaps and engine-declared
`unsupported_*` capability gaps from prompt quality metrics, checks paired
model/runtime/contract/budget equivalence, and
requires the treatment's checkpoint/completion rates not to regress, median
author calls to stay within 10 percent, and either schema/decision or CDSL
expression failures to improve.