# Glossary
> Every term ivar uses, one short definition each, covering the model, sessions, planning, delivery and hall health.
Source: https://ivar.run/docs/reference/glossary

The five terms that carry the model are **hall, repo, feature, promote and
session**. [What is ivar](/docs/what-is-ivar) explains them with an example;
this page defines them and the rest in a line or two, so you can look one up
when a command or a skill mentions it.

## The model

**Hall**: a directory that owns a set of repos, features and sessions, defined
by a committed `ivar.json`. The hall is itself a git repo, so a teammate gets
yours with `git clone` and `ivar sync`. Keep one per scope of work: a team, a
product, an initiative.

**Repo**: a git repository listed in `ivar.json` by name, URL and default
branch. `ivar` clones it bare into `.ivar/repos/<name>/.bare/`, and every
checkout, the default branch included, is a worktree of that clone.

**Feature**: one branch across the repos a change touches. Its name is the
branch name. It outlives sessions and agents, because it is a file plus
branches, not a conversation.

**Promote**: make a repo writable for a feature. `ivar feature promote` cuts
the feature's branch in that repo (or adopts one that exists), creates its
worktree and runs the repo's setup script. **Demote** removes the repo from the
feature and leaves the worktree on disk.

**Subfeature, child, parent**: a feature created with `--parent` is a child.
Its branch starts from the parent's branch, and its work lands there through
**integrate**. A feature with no parent is a **root**; only roots deliver.

**Provider**: the agent harness a session runs: `claude-code`, `opencode` or
`omp`. `ivar init --provider` picks the hall's default, `ivar provider add`
adds another, and `ivar session start --provider` picks one for a session.

**Manifest**: `ivar.json`. It holds the hall's name, repos, providers, and
optionally skills and MCP servers. It is parsed strictly: an unknown key is an
error.

## Sessions

**Session**: a view directory with an agent working in it, bound to at most
one feature. Several sessions can share a feature and its worktrees.

**View directory**: the session's directory of symlinks, one per repo. A
promoted repo points at the feature's worktree; every other repo points at
its default-branch worktree, read-only. The harness config (`.claude/`,
`.opencode/`, `.omp/`) and the instruction file live there too.
`$IVAR_SESSION_PATH` names it.

**Discovery session**: a session with no feature. Every repo is read-only and
promotion is off. `/ivar-discovery` opens one for exploring a problem.

**Feature session**: a session bound to a feature, with its promoted repos
writable.

**Convert**: bind a discovery session to a feature, once. It cannot be undone.

**Detached session**: a session created without launching a provider, so an
agent that is already running can use it. It stays until `ivar session stop`.
A session that `ivar session start` launched ends when you quit the harness.

**Relay**: a fresh session on the same feature under a different provider,
usually because the first one ran out of tokens. The branch, worktrees and plan
carry over; the conversation does not.

**Guard**: what stops a session writing where it should not. Non-promoted
repos have their write bits cleared, and the harness hook (plus Landlock on
Linux) refuses writes outside the session's writable set.

## Repos and refreshing

**Sync**: `ivar sync` brings the local hall in line with `ivar.json`: clones
missing repos, writes harness config, runs setup scripts. It does not fetch.

**Pull**: `ivar repo pull` fetches and fast-forwards default branches. It never
touches a feature worktree.

**Setup script**: `.ivar/setups/<repo>.sh`, committed with the hall. It prepares
a fresh worktree: dependencies, codegen, env files. `ivar` runs it with `bash`
on `sync` and on promote, and records a receipt so it re-runs only when the
script changes. See [setup scripts](/docs/guide/hall-upkeep#author-a-setup-script).

**Session hook**: `.ivar/setups/<repo>.session.sh`, run in each promoted
worktree on every session start, for per-session state such as a local
database.

**Secrets directory**: `.ivar/secrets/`, ignored by git and passed to scripts
as `IVAR_SECRETS_DIR`.

## Planning

**Requirements, analysis, plan**: the three planning artifacts under
`.ivar/features/<feature>/`. Requirements say what must be true, analysis
what the code looks like today, the plan how the change is built.

**Approval gate**: your explicit approval of one artifact, recorded with
`ivar plan approve`. Approving records a fingerprint, so editing an approved
artifact sends it back for approval. Integrate and deliver both check the plan
gate.

**Short path**: writing only `plan.md` for a small change. A gate whose artifact
was never written does not block.

**Run receipt**: the record `/ivar-execute` keeps under
`.ivar/features/<feature>/execution/`: the plan it ran, each wave's checkpoint,
and the outcome.

## Delivering

**Integrate**: land a child's work on its parent's branch, one repo at a time,
from the parent's session. Each repo's result is recorded in a receipt, so a
failed run resumes where it stopped.

**Deliver**: push a root feature's branches and open or update one pull request
per repo. `--preview` shows what would happen and prints a **fingerprint**;
the apply step takes that fingerprint and refuses if anything changed since.

**Land**: `ivar feature deliver --land` fast-forwards each default branch to
the feature and pushes it, instead of opening pull requests.

**Close**: end a feature with an outcome: `delivered`, `integrated` or
`abandoned`. **Delete** removes its worktrees and state; **prune** deletes
features whose work has landed.

## Health

**Doctor**: `ivar doctor` diagnoses the hall: failed promotions, stale
integrate staging, branches two features share, worktrees whose directory is
gone. Each finding comes with a fix.

**Stale**: a repo's remote has commits its clone lacks. `ivar repo pull`
catches up.

**Degraded**: a clone or worktree is missing. `ivar sync` repairs it.

## Not supported

Windows, and Codex or Cursor as providers. `ivar` runs on Linux and macOS with
Claude Code, OpenCode and OMP.