1. What the Agent Does — and What It Does Not Do
The XyzPilot agent is a translator. You tell it what geometry you want in plain English. It works out which operator to use, checks that your inputs exist, and calls the correct XyzPilot function. XyzPilot computes the geometry. The agent reports the result.
The agent does not compute geometry itself. It does not guess coordinates. It does not approximate. Every number in every result comes from XyzPilot's exact analytic engine.
- You can describe what you want in natural language — the agent handles the syntax
- Results are always exact — the agent cannot introduce rounding or approximation
- If the agent cannot match your command to a known operator, it tells you — it does not invent geometry
- If your inputs do not exist yet, the agent tells you — it does not assume
2. The Two-Tier Entity Model — Points vs. Geometry
| Tier | What It Includes | Persistence | What Happens When Deleted |
|---|---|---|---|
| Construction | Points (P0, P1, P2…) | Disposable — delete freely after use. Points exist on their own layer and can be hidden, shown, or cleared all at once via Edit → Clear All Points. | Nothing. Lines and arcs built from them are unaffected. |
| Product | Lines, Arcs, Circles, Toolpaths | Persistent — the output you are building toward | Downstream geometry that depends on it is flagged as inconsistent. |
The Baking Rule
When you use points to construct a line or arc, the line or arc geometry is baked — its coordinates are computed and stored as fixed numbers at the moment of creation. The points are no longer needed.
P1 = Point at (10, 20)
P2 = Point at (70, 60)
L1 = Line through P1 and P2 ← L1 is now baked: (10,20) → (70,60)
Delete P1 and P2 ← L1 is unchanged. No warning. No error.
Think of points as pencil marks on paper. You use them to draw the line, then rub them out. The line stays.
3. How Natural Language Becomes Geometry
Every command you give the agent goes through the same four-step process before any geometry is created.
| Step | What Happens | Example |
|---|---|---|
| 1 | Parse intent | "Create the YLarge intersection of L2 and C1" → operator = line-circle intersection, selector = YLarge, inputs = L2, C1 |
| 2 | Validate inputs | Agent checks: does L2 exist? Is it a line? Does C1 exist? Is it a circle? If anything is missing, it stops here. |
| 3 | Resolve selector | Selector is YLarge — explicitly stated. Agent confirms: "I will create the upper intersection point." |
| 4 | Call XyzPilot | Agent calls Point_LineCircleIntersection(L2, C1), selects YLarge candidate, creates P5. |
Shortcut Input
If you know the operator syntax, you can use shortcut input directly:
Full command: "Point/YLarge,Intof,L2,C1"
Shortcut: "YLarge,2,1" (selector, line index, circle index)
Agent decodes: Point/YLarge,Intof,L2,C1 → same result
What the Agent Validates Before Executing
- All referenced entities exist in the model (L2, C1, P1, etc.)
- Each entity is the correct type for the operator
- All required inputs are supplied — no missing arguments
- The selector is valid for this operator
Important: The agent validates inputs — but it cannot validate your intent. If you ask for the YLarge intersection when you meant YSmall, the agent will create the wrong point correctly. Always check your selector.
4. Selectors — Resolving Ambiguous Geometry
Many geometry operations have more than one valid solution. Selectors tell XyzPilot which solution you want.
When You Must Specify a Selector
- Line-circle intersections — two points (use XLarge/XSmall or YLarge/YSmall)
- Circle-circle intersections — two points
- Parallel lines — two sides
- Tangent lines from a point to a circle — two lines
- Arc direction — CW or CCW
What Happens If You Do Not Specify One
The agent will not guess. It will present both candidates and ask you to choose:
You: "Create a point at the intersection of L2 and C1"
Agent: "L2 and C1 intersect at two points:"
" [1] Upper candidate (YLarge) at (10, 17.32)"
" [2] Lower candidate (YSmall) at (10, -17.32)"
"Which would you like to create? (1 or 2)"
Important — Canvas Preview: While the agent is waiting for your selection, the transient preview on the canvas may display a point in the wrong position. This is a preview only — the point has not been created yet. Do not assume the canvas is showing the correct result until you have confirmed your selector choice and the agent confirms the point has been created. Always verify the final position on the canvas after creation.
Selector Quick Reference
| Selector | Applies To | Picks |
|---|---|---|
XLarge | Points, Lines, Circles | The solution with the largest X coordinate |
XSmall | Points, Lines, Circles | The solution with the smallest X coordinate |
YLarge | Points, Lines, Circles | The solution with the largest Y coordinate |
YSmall | Points, Lines, Circles | The solution with the smallest Y coordinate |
OUT | Circle tangency | External tangency — new circle sits outside the reference circle |
IN | Circle tangency | Internal tangency — new circle sits inside the reference circle |
CW | Arcs, Trim | Clockwise traversal direction |
CCW | Arcs, Trim | Counter-clockwise traversal direction |
Start / End | Lines, Arcs | Moves or references the start/end endpoint |
Flip | Fillets | Toggles to the opposite-corner fillet solution |
Rule: Use the selector on the axis along which the two solutions differ. If both solutions share the same X coordinate, use YLarge/YSmall instead of XLarge/XSmall.
5. Practical Workflow Examples
Simple Point Creation
Natural language: "Create a point at X=50, Y=75, Z=0"
Shortcut: "Point/50,75,0"
Agent: "Created P0 at (50, 75, 0)"
Multi-Step Construction
Step 1: "Create a point at (10, 0)" → Created P0 at (10, 0)
Step 2: "Create a point at (10, 50)" → Created P1 at (10, 50)
Step 3: "Create a line through P0 and P1" → Created L0 — vertical line X=10
← L0 is now baked. P0 and P1 are no longer needed.
Step 4: "Delete P0 and P1" → P0 deleted. P1 deleted. L0 unchanged.
Step 5: "Create the YLarge intersection of L0 and C1" → Created P2 at (10, 17.32)
Managing Construction Points: Points exist on their own dedicated layer and can be hidden or shown independently of other geometry. You can also remove all points at once using Edit → Clear All Points — this deletes every point in the model without affecting any lines, arcs, circles, or toolpaths. Use this after completing a construction sequence to keep your model clean.
Tangency Workflow
Setup: L0 = horizontal line Y=0, L1 = vertical line X=100, Radius = 20
Command: "Create a circle of radius 20 tangent to L0 above and to the left of L1"
Agent: "I interpret this as: Circle tangent to L0 (YLarge) and L1 (XSmall), R=20"
"This will create a circle centred at (80, 20). Proceed? (yes/no)"
You: "yes"
Agent: "Created C0: centre=(80, 20), radius=20"
For tangency operations with multiple selectors, always confirm the interpretation before proceeding.
6. When Geometry Changes — Undo and Downstream Effects
XyzPilot uses an Undo system rather than explicit entity deletion. Geometry is removed by undoing the operations that created it — not by selecting and deleting entities directly.
How Undo Works with Dependencies
When you undo a sequence of operations, XyzPilot automatically handles dependencies in the correct order. If an arc was created from L0 and L1, undoing back to L1 will first undo the arc, then undo L1 — the dependency relationship is resolved automatically by the undo sequence.
Example construction sequence:
Step 1: Create L0
Step 2: Create L1
Step 3: Create A0 (arc tangent to L0 and L1)
Undo sequence:
Undo → A0 is removed first (it depends on L1)
Undo → L1 is removed
Undo → L0 is removed
The relationship between A0 and L1 no longer exists once A0 is undone.
XyzPilot handles this order automatically.
Note: Always undo in sequence. The undo system ensures dependent geometry is removed before the geometry it depends on — preventing orphaned or inconsistent entities.
Preview Undo and Preview Redo
XyzPilot provides Preview Undo and Preview Redo controls in the toolbar. These allow you to step back through the transient preview states before committing an operation — useful for reviewing geometry before it is permanently created.
Important: In XyzPilot, geometry is managed through the Undo system — not through explicit deletion commands. If you need to remove geometry, use Undo to step back through the construction sequence in the correct dependency order.
7. Deferred Commands — Working Ahead
Sometimes you want to describe a construction before all the inputs exist. The agent supports this through deferred commands.
You: "Create a circle centred at P5 with radius 30"
(P5 does not exist yet)
Agent: "P5 does not exist yet. Defer this command until P5 is created? (yes / no)"
You: "yes"
Agent: "Command deferred. Waiting for: P5 (Point)"
"When P5 is created, the circle will be created automatically."
Later...
You: "Create a point at (40, 60)"
Agent: "Created P5 at (40, 60)"
"Deferred command resolved automatically:"
"Created C2: centre=(40, 60), radius=30"
8. When the Agent Cannot Help
The agent can only execute operations that exist in the XyzPilot operator catalog. If you ask for something that is not supported, it will tell you clearly and suggest the nearest available alternatives.
You: "Create a spline through P0, P1, P2, P3"
Agent: "Spline operators are not in the current catalog."
"Nearest available alternatives:"
" Broken/Line — polyline through multiple points"
" Arc/Centre,R,Start,End — arc segment"
Common Unsupported Operations
- Splines and NURBS curves
- 3D surface operations
- Freeform sketching
- Dimension annotations
- Hatching and fill patterns
The catalog grows over time. If you regularly need an operation that is not available, report it — it may be added in a future release.
9. Common Mistakes and How to Avoid Them
| Mistake | How to Avoid It |
|---|---|
| Omitting the selector for a two-solution operation | Always specify XLarge/XSmall/YLarge/YSmall when creating intersections, parallel lines, or tangent circles. |
| Using the wrong selector axis | Use the selector on the axis where the two solutions differ. For a vertical line intersecting a circle, use YLarge/YSmall. |
| Referencing a point that has already been deleted | Points are disposable — but only after the geometry built from them is complete. |
| Trying to delete geometry directly instead of using Undo | XyzPilot uses Undo to remove geometry — not explicit deletion. Use Preview Undo in the toolbar to step back through the construction sequence. Undo handles dependency order automatically. |
| Expecting the agent to compute geometry itself | The agent is a translator. It calls XyzPilot functions. It does not compute coordinates or approximate results. |
| Issuing a command with vague spatial language | "Create a point near the top of C1" is ambiguous. Use "Create the YLarge point on C1 at angle 90°" instead. |
| Ignoring the agent's interpretation confirmation | For complex commands, the agent shows its interpretation before executing. Read it carefully. |
10. Quick Reference Card
Entity Types at a Glance
| Prefix | Type | Tier | Delete Freely? |
|---|---|---|---|
P0, P1, P2… | Points | Construction | Yes — after geometry is baked from them |
L0, L1, L2… | Lines | Product | Only if nothing downstream depends on them |
C0, C1, C2… | Circles | Product | Only if nothing downstream depends on them |
A0, A1, A2… | Arcs | Product | Only if nothing downstream depends on them |
T0, T1, T2… | Toolpaths | Product | Only if nothing downstream depends on them |
Command Patterns
"Create a point at X=50, Y=30" → Point/50,30,0
"Create the YLarge intersection of L2 and C1" → Point/YLarge,Intof,L2,C1
"Create a line through P1 and P2" → Line/P1,P2
"Create a line parallel to L1, 25 above" → Line/Parlel,L1,YLarge,25
"Create a circle centred at P1 with radius 30" → Circle/P1,R=30
"Create a fillet of radius 10 between L1 and L2" → Fillet/L1/L2,R=10
If Something Goes Wrong
"What depends on L2?" — shows downstream geometry
"Show deferred commands" — lists pending deferred commands
"Cancel DC-001" — abandons a deferred command
"Recompute A3" — re-runs A3's construction with current inputs
To remove geometry: use Undo (Preview Undo in toolbar)
— Undo removes geometry in correct dependency order automatically
— Undo arc before the lines it was built from