# Interaction Grammar

## Core Loop

1. Focus input (intent/query)
2. Association/highlight (candidate set)
3. Inspect (evidence + confidence)
4. Act (control path)
5. Reflect (trace + next step)

Smoothness rule:
- each step emits an immediate visible acknowledgement in <150ms
- long work emits progress every <=1s
- completion emits a durable artifact link (log/report/URL)

## State Labels

Every actionable state should show:
- `status` (ok / fallback / guard / failed)
- `evidence` (url, file path, or returned artifact)
- `timing` (latency/p50/p95 where available)
- `next` (single recommendation)

## Confidence Rule

Signals must be tagged:
- high: recent measured telemetry
- medium: partial telemetry + inferred fields
- low: mostly inferred/synthetic

## Error Handling

- No silent failures.
- Show concise failure summary first, raw detail second.
- Keep user inside the loop with a recoverable next action.
- If fallback is used, label it immediately and show what fidelity was lost.

## Progressive Disclosure

- Compact cards for scanning.
- Expand to inspector detail only when selected.
- Preserve context when switching between panels.

## Gesture And Control Affordances

- Every primary affordance has:
  - direct manipulation path (tap/swipe/click)
  - explicit button path
  - keyboard fallback where practical
- Gestures must have preview feedback before commit.
- Commit threshold must be visible (gauge, threshold line, or textual cue).