# Interaction Pattern Library

## Core principle

Design capabilities as reusable interaction patterns before creating pages. A dedicated screen is the exception, not the default.

## Element lifecycle

Every visible Element should support the states appropriate to its type:

1. **Signal** — a compact mention, icon, chip, link, or Pulse.
2. **Preview** — enough identity, state, provenance, and relevance to choose it.
3. **Address** — attach the Element to the main conversation and ask about or act on it.
4. **Lens** — inspect metadata, relationships, history, permissions, dependencies, and controls.
5. **Stage** — make the Element the dominant work surface.
6. **Pin** — keep it present across several conversational turns.
7. **Compare or compose** — bring multiple Elements into one structured instrument.
8. **Propose** — preview a change or Action without executing it.
9. **Gate** — obtain required confirmation, approval, vote, signature, or governance.
10. **Execute** — show queued, working, partial, failed, cancelled, or complete state.
11. **Receipt** — preserve result, authority, provenance, and recovery path.
12. **Recede** — return the Element to context without losing continuity.

## Chatting with an Element

An Artifact, Source, schedule, proposal, or other non-agent Element does not literally become an agent. “Chat with this” means:

- select the Element as conversational context;
- route the exchange through Ki or the relevant Realm Actor;
- preserve the Element's identity and state in the thread;
- show which source or principal supplies answers when material; and
- expose authority before any Action changes the Element or external world.

## Twelve reusable patterns

| Pattern | Use |
|---|---|
| Calm start | No urgent work; invite the user to state an intention. |
| Attention brief | Ki summarizes only the few items that need the user now. |
| Guided conversation | Clarify intent and assemble structure without a long form. |
| Collection tray | Browse or filter a relevant set of Elements without leaving the Focus. |
| Inline instrument | Show a schedule, result set, proposal, source set, preview, or small editor in the conversation. |
| Element Lens | Inspect one Element deeply without changing the primary context. |
| Element Stage | Give one Element or composition dominant space for precise work. |
| Proposed change | Present a diff, rationale, sources, impact, and reversibility. |
| Action Gate | Confirm or govern a consequential Action in context. |
| Execution timeline | Show asynchronous or multi-step work, cancellation, retry, and partial completion. |
| Receipt and Record | Confirm what happened, under whose authority, with links to history and recovery. |
| Atlas | Orient across Realms, relationships, and active work, then return to the prior Focus. |

## Choosing a pattern

Use the smallest pattern that preserves clarity and safety:

- a fact stays conversational;
- a choice becomes an inline instrument;
- a complex Element opens a Lens;
- sustained composition opens a Stage;
- consequential work becomes a proposed change and Gate;
- long-running work becomes an execution timeline; and
- broad orientation opens the Atlas.

## Main conversation composition

A healthy conversational sequence alternates between:

- human or agent language;
- one relevant structured instrument;
- one explicit decision when required;
- visible progress; and
- a concise receipt.

Avoid stacking unrelated cards merely because several capabilities are available.

## Atlas behavior within the Field

The Atlas should be filtered by the current intention and context. It should not show every known object.

Atlas layers may include:

- Realms;
- active or recent work;
- relationships;
- invitations and possible paths;
- attention and blocked work;
- selected categories of Elements; and
- a trace of how the current Focus relates to the wider Field.

The user chooses layers. The system may suggest one layer based on intent, but it should not enable all layers by default.

## Context movement

Moving between surfaces must preserve:

- active Realm;
- active Focus;
- selected and pinned Elements;
- conversation position;
- pending Gates;
- current execution state; and
- privacy and authority context.

## Cross-cutting states

Every capability that creates, connects, generates, imports, publishes, transacts, synchronizes, or executes must consider:

- empty;
- ready;
- queued;
- working;
- awaiting input;
- awaiting approval;
- partially complete;
- complete;
- failed;
- blocked;
- cancelled;
- expired;
- stale;
- retrying; and
- recovered.

Only display the states meaningful to the active task. Preserve the rest in history and operational inspection.
