# Demo Walkthrough

This walkthrough runs the current Phase 0 through Phase 10B `.aieng` reference demo. It creates a bracket package, adds mock topology, recognizes rule-based feature candidates, applies user engineering context, generates visual/object/interface scaffolds, imports a CAE deck scaffold, applies explicit user CAE mappings, generates AI-readable summaries, creates a structured patch proposal, exports a CalculiX scaffold deck, generates a validation status file, and validates the package.

The demo does not parse STEP geometry by default, execute CAD operations, mesh, solve, run manufacturing checks, import solver results, or call an LLM/RAG/MCP/skill/plugin system.

Phase 13 note: the reference demo still stops at patch proposal unless `aieng apply-patch` is explicitly run. Patch proposal generation alone does not modify structured parameters or geometry.

## Commands

From the repository root:

```bash
mkdir -p build
aieng import-step examples/bracket.step --out build/bracket_001.aieng --overwrite
aieng extract-topology build/bracket_001.aieng --overwrite
aieng recognize-features build/bracket_001.aieng --overwrite
aieng apply-context build/bracket_001.aieng --context examples/bracket_user_context.yaml --overwrite
aieng build-visual-index build/bracket_001.aieng --overwrite
aieng build-visual-manifest build/bracket_001.aieng --overwrite
aieng build-interface-graph build/bracket_001.aieng --overwrite
aieng import-cae-deck build/bracket_001.aieng --deck examples/bracket_loadcase.inp --format calculix --overwrite
aieng apply-cae-mapping build/bracket_001.aieng --mapping examples/bracket_cae_mapping.yaml --overwrite
aieng build-interface-graph build/bracket_001.aieng --overwrite
aieng build-object-registry build/bracket_001.aieng --overwrite
aieng summarize build/bracket_001.aieng --overwrite
aieng propose-patch build/bracket_001.aieng --intent "Reduce mass by 15% while keeping mounting holes unchanged."
aieng export-calculix build/bracket_001.aieng --out build/solver_deck.inp --overwrite
aieng update-validation-status build/bracket_001.aieng --overwrite
aieng validate build/bracket_001.aieng
```

PowerShell users can replace `mkdir -p build` with:

```powershell
New-Item -ItemType Directory -Force -Path build
```

`import-step`, `extract-topology`, `recognize-features`, `apply-context`, `build-visual-index`, `build-visual-manifest`, `build-interface-graph`, `import-cae-deck`, `apply-cae-mapping`, `build-object-registry`, `summarize`, `export-calculix`, and `update-validation-status` support `--overwrite`. Phase 10C intentionally runs `build-interface-graph` twice: first to create the interface ID prerequisite for the mapping file, and again after `apply-cae-mapping` to enrich the interface graph with `cae_refs`. `propose-patch` intentionally creates the next deterministic patch file instead of overwriting an existing patch. Because the first command recreates the package with `--overwrite`, the demo normally produces `ai/patches/patch_0001.json`.

## Phase 10B interface graph prerequisite

`examples/bracket_cae_mapping.yaml` maps `FIXED_HOLES` to both:

- `feature_id: feat_hole_pattern_001`
- `interface_id: iface_feat_hole_pattern_001`

That interface ID is generated by `aieng build-interface-graph`. Therefore `objects/interface_graph.json` must exist before `aieng apply-cae-mapping` is run with this fixture. If a mapping file references only `feature_id` values, the interface graph is not required for that specific mapping.

Expected reference mappings after Phase 10B:

- `FIXED_HOLES` maps to `feat_hole_pattern_001` and `iface_feat_hole_pattern_001`, with `mapping_method: user_provided` and `confidence: high`.
- `LOAD_FACE` maps to `feat_base_plate_001`, with `mapping_method: user_provided` and `confidence: high`.

## Phase 10C CAE refs in the interface graph

After `aieng apply-cae-mapping`, rerun `aieng build-interface-graph --overwrite`. The second interface-graph build reads `simulation/cae_mapping.json` and adds `cae_refs` to generated interface entries. `FIXED_HOLES` should appear on `iface_feat_hole_pattern_001`; `LOAD_FACE` should appear on the interface containing `feat_base_plate_001`. These references are user-provided traceability links only: no automatic mapping inference, meshing, solver run, result import, or geometry modification is performed.

## Optional Python script

The same command chain can be run with:

```bash
python scripts/run_reference_demo.py
```

The script uses only Python's standard library and invokes the local CLI through `python -m aieng.cli` with `PYTHONPATH=src`.

## Expected generated package contents

The resulting `.aieng` zip package should contain these key files:

```text
manifest.json
geometry/source.step
geometry/normalized.step
geometry/topology_map.json
graph/feature_graph.json
graph/constraints.json
simulation/setup.yaml
ai/protected_regions.json
visual/annotation_layers.json
visual/model_manifest.json
objects/interface_graph.json
simulation/cae_imports/source_solver_deck.inp
simulation/cae_imports/parsed_materials.json
simulation/cae_imports/parsed_boundary_conditions.json
simulation/cae_imports/parsed_loads.json
simulation/cae_mapping.json
objects/object_registry.json
README_FOR_AI.md
ai/summary.md
ai/patches/patch_0001.json
simulation/solver_deck.inp
validation/status.yaml
```

## What each file means

- `manifest.json`: package identity, units, provenance, and indexed resources.
- `geometry/source.step`: copied input STEP-like fixture.
- `geometry/normalized.step`: copied normalized STEP resource for current Phase 1 behavior.
- `geometry/topology_map.json`: deterministic mock topology map by default; not extracted from STEP content when using the default backend.
- `graph/feature_graph.json`: deterministic rule-based feature candidates derived from the topology map.
- `graph/constraints.json`: structured constraints generated from user context.
- `simulation/setup.yaml`: static structural simulation intent generated from user context; no solver has run.
- `ai/protected_regions.json`: protected feature IDs and allowed/forbidden operations generated from user context.
- `visual/annotation_layers.json`: visual annotation metadata only; no rendering.
- `visual/model_manifest.json`: visual resource claims/manifest only; no GLB or screenshots are generated.
- `objects/interface_graph.json`: generated interface index; required by the reference Phase 10B mapping because it cites `iface_feat_hole_pattern_001`.
- `simulation/cae_imports/*`: copied/parsed CAE deck scaffold resources; no solver has run.
- `simulation/cae_mapping.json`: conservative CAE mapping scaffold updated by explicit user-provided mapping YAML.
- `objects/object_registry.json`: generated cross-resource object index; not source-of-truth.
- `README_FOR_AI.md`: derived AI-reader guide; not the source of truth.
- `ai/summary.md`: derived engineering summary; not the source of truth.
- `ai/patches/patch_0001.json`: structured, unexecuted patch proposal; no geometry has been modified.
- `simulation/solver_deck.inp`: CalculiX scaffold deck with material block and BC/load intent as comments; scaffold only ? no mesh, no solver run.
- `validation/status.yaml`: machine-readable validation state with `solver_mesh_status`, `patch_status`, and `claim_policy`.

## What is real structured `.aieng` data

The package resources, schemas, manifest references, stable IDs, cross-resource validation, protected-region checks, simulation intent, generated indices, explicit CAE mappings, and patch proposal structure are real MVP `.aieng` data.

## What is mock-based or not implemented

- STEP content is not parsed by the default mock backend.
- Topology is mock-generated unless `--backend occ` is explicitly used with optional OCP/CadQuery installed.
- Feature recognition is rule-based and candidate-only.
- User context supplies engineering assumptions.
- Visual resources are metadata scaffolds only; no rendering occurs.
- CAE mapping is user-provided; no automatic CAE-to-geometry inference occurs.
- No geometry is modified.
- No mesh is generated.
- Solver deck is exported as a scaffold only (no mesh, no active `*NODE`/`*ELEMENT`/`*STEP` sections, no solver run).
- No solver result is attached.
- No manufacturing check is run.
- No LLM, RAG, MCP, plugin, or skill is called.

## How to inspect the package

A `.aieng` file is a zip package. You can inspect it with standard zip tools or from Python. Start with `manifest.json`, then read structured JSON/YAML resources before relying on Markdown summaries.

For AI readers: cite object IDs, distinguish facts from candidate inferences and user assumptions, and do not claim engineering safety without solver-validated evidence.
