Cairn Documentation
Manual and AI Paths
Cairn is an AI-native tool. It also gives you a deterministic manual path for nearly every editing action. This page explains why both exist and how to pick between them.
The Principle
Every important action — adding a node, connecting two nodes, renaming a subsystem, editing a state machine — has both an AI path and a manual path. AI is faster when the change is large or you don't yet know its shape. Manual is faster when you do. Neither is a second-class citizen.
Why Both Exist
Speed and cost. Manual edits commit instantly and cost nothing. AI calls take seconds and burn API credits. For a one-line title fix, opening the palette is overkill — click the title and type. For decomposing a subsystem into seven children with property estimates, AI saves an hour and is worth the call.
Exploratory vs. known intent. AI shines when you're thinking out loud — "decompose the power subsystem, I'm not sure into what exactly." The model has the breadth to surface plausible options. Manual shines when you've already decided — "rename this to Battery Management Subsystem" doesn't need a specialist round-trip.
Delegated reasoning vs. direct intent. When you delegate to AI, you're asking the model to reason about what should happen, and the ChangeSet review then checks its work before anything lands. When you act manually, you're saying "I've already done the reasoning; just apply this change." Skipping the review step is the right default for surgical edits.
Where the Choice Appears
Most editing surfaces in Cairn pair the two paths:
- Adding a child node: ⌘K "decompose into…", or right-click → Add child
- Decomposing: ⌘K "decompose…", or right-click → Decompose with AI (still AI, just a different entry point)
- Renaming a node: Inspector title click-to-edit, or right-click → Rename in the tree
- Editing fields (description, type, priority, protocol, signal rate): Inspector click-to-edit only — fields commit immediately
- Connecting interfaces: ⌘K "connect X to Y", or canvas right-click → Connect to… (manual)
- Creating a fresh interface: ⌘K, canvas right-click → Connect to… (manual), or — once any interface is selected — its Inspector's + New Interface button
- Adding a requirement: ⌘K "add requirements for…", or the Requirements lens's + Add button (inline form for title, type, priority)
- Adding a verification: ⌘K "add verification for…", or the Verification lens's + Add button
- Adding a state or transition: ⌘K, or right-click on the Behavior lens canvas / state / transition row (the Add transition from/to here items pre-fill the palette with the source state). Inline manual creation forms remain a follow-up — for now the right-click items still route through ⌘K.
- Editing a state or transition: click in the Behavior lens to open the Inspector. The state name, type, description, and timing and the transition trigger, guard, action, and timing are all editable.
- Deleting: Inspector Delete, or right-click → Delete on the tree / Architecture canvas / Behavior canvas / transition row — all surface the same cascade preview before anything is removed
A few surfaces are AI-only by design — the initial Inception flow, system briefs, dendritic alternatives — because they require the model's synthesis to make sense. A few are manual-only because they're too narrow to spec in natural language profitably (signal metadata fields, cascade confirmation). The middle ground is wide and intentional.
How They Route Differently
AI changes always produce a ChangeSet — an in-memory list of proposed operations. Nothing touches the model until you apply the ChangeSet. See AI Governance for the propose/review/apply contract.
Manual changes commit to the model immediately. There's no review gate — the act of clicking and typing is the confirmation. The History tool tracks every change either way, so you can roll back a manual edit if you change your mind.