# Realm Experience Model

## A Realm is not an empty container

A Realm should arrive with enough intelligence, structure, and agency to help users achieve the kinds of outcomes for which the Realm exists.

A clinic should feel clinically informed and operationally capable. An organizing Realm should coordinate people, availability, communication, decisions, and follow-up. A project Realm should understand its purpose, sources, artifacts, commitments, timeline, and finish conditions.

The user should not have to assemble every database, prompt, tool, and workflow before the Realm becomes useful.

## Realm Intelligence Contract

Every designed Realm must define:

| Dimension | Required answer |
|---|---|
| Purpose | Why does this Realm exist, and what outcomes does it help create? |
| Audience | Who is it for, and who may participate? |
| Wisdom | What should it know, where does that knowledge come from, and how current is it? |
| Stance | How should it approach its work, tradeoffs, uncertainty, and people? |
| Abilities | What can it help create, analyze, decide, coordinate, or operate? |
| Automations | What may continue without repeated prompting, and under what limits? |
| Connections | Which external systems may it reach, and at what scope? |
| Actors | Which agents perform Realm work, for whom, and with what authority? |
| Elements | Which sources, artifacts, records, instruments, and Scenes are native to the Realm? |
| Roles and permissions | Who may see, propose, approve, execute, publish, or govern? |
| Privacy and trust | What is public, private, secret, or personal, and why may it be relied upon? |
| Actions and gates | Which outcomes are autonomous, confirmed, deliberate, governed, multisignature, or prohibited? |
| State and attention | What is happening now, what is blocked, and what needs a person? |
| Records | What must persist after work or action occurs? |
| Compute and treasury | What capacity or financial resources are available, when relevant? |

## Default Realm surface

Do not show every contract dimension at once. The default Realm surface should show:

1. Realm name and one-line purpose.
2. Current Focus or a calm invitation to state one.
3. Main conversation.
4. Zero to three items requiring attention.
5. One or two contextually useful next actions.
6. A quiet Pulse indicating whether the Realm is ready, working, waiting, or constrained.

Everything else belongs in a Realm Lens or appears through the work.

## Realm Lens

The Realm Lens is an expandable inspection surface. It may expose:

- purpose and current goals;
- active and recent work;
- Wisdom and source health;
- Stance;
- Abilities and available instruments;
- Automations and their status;
- Connections and credential health;
- Roles, permissions, and policies;
- Actors and authority paths;
- Realm Elements and Artifacts;
- governance, Treasury, and Compute when applicable; and
- history and Records.

The Lens is for understanding and adjustment. It is not the default task surface.

## Realm setup flow

1. User describes the Realm and desired outcomes.
2. Ki proposes a Realm Intelligence Contract.
3. The user reviews purpose, audience, privacy, and consequential authority first.
4. The system proposes required Wisdom, Stance, Abilities, Automations, Connections, Actors, and Elements.
5. Missing dependencies are stated as questions or readiness gaps.
6. The user approves or edits the assembled Realm.
7. The Realm opens with a first useful Focus, not an empty dashboard.
8. The contract evolves through proposed changes, diffs, approvals, and Records.

## Example: Inner Clinic

User intention: “Help me understand what the surgeon found and what the stents are doing.”

The Realm separates authorized patient records, clinician interpretation, current research, illustrative anatomy, and unknowns. It may propose a patient-specific Scene only when spatial or temporal representation materially improves understanding and the patient consent, source set, and clinician-review authority are explicit.

The Realm must not diagnose, predict, or fill gaps. Conflicting Sources constrain the representation and generate a clarification path and Record.

## Example: The Nature of Work

User intention: “Help the transformation team name what keeps blocking this decision.”

Ki coaches the participant privately, then offers to prepare a separate shareable contribution. A team or Program synthesis uses only eligible contributions, states its coverage and exclusions, preserves dissent, and passes an anti-reidentification check. Private Ki conversation never becomes an Organization source.

## Example: 2nd Cavalry living history

User intention: “Record what my crew remembers about 73 Easting before the anniversary.”

The Realm brings forward:

- an oral-history protocol and release;
- the original recording and distinct transcript/metadata derivatives;
- relevant official Sources and other attributed testimony;
- chosen attribution, visibility, rights, and sensitive-topic boundaries; and
- the archive/editorial authority needed for release.

Conflicting accounts remain linked and attributable. A historical Scene must distinguish official Sources, testimony, interpretation, reconstruction, and unknowns and preserve a Portal to the Sources and conversation.

## Readiness levels

| Level | Meaning |
|---|---|
| Seed | Purpose exists, but required intelligence or authority is incomplete. |
| Capable | The Realm can handle its primary intents with disclosed limits. |
| Connected | Necessary systems and source data are available. |
| Operating | Automations and Actors are performing authorized work. |
| Governed | Roles, policies, approvals, and Records cover consequential activity. |
| Evolving | Performance and feedback are improving Wisdom, Stance, and operations through reviewable changes. |

These levels are a proposed design tool, not canonical lifecycle status.
