# Complete Context System

OpenLife's Complete Context System lets the runtime understand the
project it's working inside. After installing v1.12 → v1.14, every
`openlife ask` automatically injects three streams of relevant
context into the model's system prompt:

1. **Stories** matched on title/cluster/acceptance criteria
   (v1.12 — `openlife story …`).
2. **Code chunks** retrieved by embedding similarity
   (v1.13 — `openlife index …`).
3. **Symbols** from the codebase graph
   (v1.14 — `openlife graph …`).

The composer cross-ranks, budgets, and packs them into a single
"Contexto do projeto" block in the system prompt — handed to
whichever **CLI provider** the user has configured (claude / gemini
/ codex / ollama).

## Quick start

```bash
# 1. (optional) populate the RAG + graph indexes
openlife index build
openlife graph build

# 2. ask anything — first run auto-detects an installed CLI
openlife ask "how does the fast ack pattern work?"
```

That's it. The very first `openlife ask` writes
`~/.openlife/router.json` based on what's installed. You can
re-tune it any time:

```bash
openlife provider setup     # interactive wizard
openlife provider doctor    # status + install hints
openlife provider use claude --fast haiku --smart sonnet
```

## Architecture

```
                      openlife ask  /  bridge push chat
                                │
                                ▼
                  ┌──────────────────────────┐
                  │  Gatekeeper handleFastPath│
                  │  builds systemPrompt      │
                  └─────────────┬─────────────┘
                                │ (compose)
                                ▼
            ┌────────────────────────────────┐
            │  ContextComposer (cross-rank)  │
            └────┬─────────────┬──────────┬──┘
                 │             │          │
        ┌────────▼───┐  ┌──────▼─────┐  ┌─▼─────────┐
        │ Story      │  │ RAG        │  │ Graph     │
        │ Registry   │  │ Retriever  │  │ Store     │
        └────────────┘  └────────────┘  └───────────┘
                                │
                                ▼
                  ┌──────────────────────────┐
                  │ ModelTierRouter.pick(…)   │
                  │ + ProviderProbe           │
                  └─────────────┬─────────────┘
                                │
                                ▼
                  ┌──────────────────────────┐
                  │ Brain.think (CLI mode)   │
                  └──────────────────────────┘
```

## Environment variables

| Variable                          | Default                     | Effect                                                  |
|-----------------------------------|-----------------------------|---------------------------------------------------------|
| `OPENLIFE_CONTEXT_COMPOSER`       | _(on)_                      | Set to `off` to disable composer injection              |
| `OPENLIFE_INFERENCE_MODE`         | `cli-only`                  | `cli-only` / `hybrid` / `api-only` / `local-only`       |
| `OPENLIFE_PROVIDER_PREFERENCE`    | `anthropic,gemini-cli,…`    | Comma-separated provider priority                       |
| `OPENLIFE_EMBEDDING_PROVIDER`     | `ollama`                    | `ollama` or `openai`                                    |
| `OPENLIFE_VECTOR_STORE`           | `sqlite`                    | `sqlite` (only option in v1.14)                         |
| `OPENLIFE_INDEX_DIR`              | `~/.openlife/index`         | Location of `codebase.db`                                |
| `OPENLIFE_USER_ROLE`              | `dev`                       | Role used for story-status transitions                  |

## CLI surface added by the Complete Context System

| Command                                    | Release | Purpose                                       |
|--------------------------------------------|---------|-----------------------------------------------|
| `openlife story {list,show,validate,transition,epics}` | v1.12 | Read/transition stories at runtime |
| `openlife index {build,update,status,query,purge}` | v1.13 | Build/use the RAG index             |
| `openlife graph {build,status,find,callers,deps,usages}` | v1.14 | Build/use the codebase graph       |
| `openlife provider {list,detect,doctor,setup,use,models,set-mode,set-preference}` | v1.14 | Pick CLI + tier |

## Modes by example

### `cli-only` (default)

The user has signed in via `claude /login`. OpenLife uses that
session for both the user-facing answer (`sonnet`) and the
composer's sub-steps (`haiku`). No OPENAI_API_KEY required.

If nothing is signed in, `openlife ask` prints:

```
[OPENLIFE] cli-only mode active but no CLI provider is signed in.
Install one of: claude / gemini / codex, or switch with:
  openlife provider set-mode hybrid
```

### `hybrid`

Same as `cli-only` for the happy path, but gracefully falls back to
the existing API chain (or local Ollama) when no CLI is available.

### `local-only`

Inference exclusively via Ollama (or `llamacpp` / `vllm`). Useful
for fully air-gapped environments. Embeddings already default to
Ollama in any mode.

## Security notes

- Local embeddings by default → zero data leakage outside the
  machine.
- `~/.openlife/index/codebase.db` and `~/.openlife/graph/…` are
  chmod 600 — treated like `.env`.
- Story HTTP endpoints are gated by the existing `bridgeAuth`
  manifest token.
- Cloud providers (`OpenAIEmbeddingProvider`, `api-only` mode)
  reuse the same trust boundary as the existing API chain.
