# pi-para Configuration

Canonical user config lives at:

```text
~/.pi/para/config.jsonc
```

The wiki defaults to:

```text
~/.pi/wiki
```

## Precedence

Current implemented precedence:

1. built-in defaults,
2. `~/.pi/para/config.jsonc`,
3. migrated legacy `~/.pi/wiki/config.json` when canonical config is missing,
4. command-specific CLI flags.

Planned/project-level overrides may use `<project>/.pi/para.jsonc` in a later slice.

## Minimal config

```jsonc
{
  "version": 1,
  "wiki": {
    "dir": "~/.pi/wiki",
    "autoCapture": true,
    "captureOnCompact": true,
    "captureOnStartup": true
  },
  "context": {
    "maxTokens": 4000,
    "includeSchema": true,
    "includeIndex": true,
    "searchLimit": 10,
    "searchGraphBoost": true
  },
  "scheduler": {
    "enabled": true,
    "startupCatchup": true,
    "intervalMinutes": 15,
    "maxConcurrentTasks": 1
  },
  "models": {
    "capture": "auto",
    "summarize": "auto",
    "judge": "auto"
  },
  "qmd": {
    "mode": "sdk",
    "embedEnabled": true,
    "providerConfig": "pi-para-profiles"
  },
  "lint": {
    "autoFix": true,
    "staleDays": 90
  }
}
```

## Credential refs

Config stores references, not secret values.

```text
pi-auth:<provider>   # persisted Pi auth, e.g. ~/.pi/agent/auth.json
secret:<name>        # ~/.pi/para/secrets.json
none                 # local/no-auth endpoint
```

Examples:

```jsonc
{
  "models": {
    "capture": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514",
      "credentialRef": "pi-auth:anthropic"
    }
  }
}
```

```jsonc
{
  "qmd": {
    "embedding": {
      "provider": "openai",
      "model": "text-embedding-3-small",
      "dims": 1536,
      "apiFormat": "openai",
      "credentialRef": "secret:embedding"
    },
    "rerank": {
      "provider": "jina",
      "model": "jina-reranker-v2-base-multilingual",
      "credentialRef": "secret:rerank"
    }
  }
}
```

Store local secrets with:

```bash
pi-para providers set-secret embedding <key>
pi-para providers set-secret rerank <key>
```

Or interactively inside Pi via `/wiki-settings`:

- `[Secrets]` — lists stored keys (redacted), adds/updates/removes API keys. `~/.pi/para/secrets.json` is created automatically (0600) on first save.
- `[Embedding]` / `[Rerank]` → `Provider` — pick from presets (OpenAI, OpenRouter, Gemini, Mistral, Voyage, Jina, Ollama) to prefill base URL/API format/default model, then optionally paste the API key in the same flow; or choose `custom` for a manual provider id + base URL.

Inspect without leaking values:

```bash
pi-para providers
pi-para doctor
```

## Sections

### `wiki`

| Field | Meaning |
|---|---|
| `dir` | Wiki directory |
| `defaultScope` | Optional default project scope |
| `autoCapture` | Enable session capture features |
| `captureOnCompact` | Queue capture on Pi compaction |
| `captureOnStartup` | Catch up queued captures on startup |

### `context`

Controls wiki context injection and default search behavior.

| Field | Meaning |
|---|---|
| `maxTokens` | Context budget |
| `includeSchema` | Include schema/conventions in context |
| `includeIndex` | Include wiki index summary |
| `searchLimit` | Default search limit |
| `searchGraphBoost` | Enable wikilink graph boost in search |

### `scheduler`

Controls in-process background work. No OS daemon is required.

| Field | Meaning |
|---|---|
| `enabled` | Enable scheduler |
| `startupCatchup` | Enqueue/process missed sessions on startup |
| `intervalMinutes` | Periodic scheduler tick interval |
| `maxConcurrentTasks` | Local concurrency limit |

Startup maintenance (embed backlog drain and capture catch-up) runs only in interactive sessions, deferred 30 seconds after `session_start` (override with the `PI_PARA_STARTUP_DELAY_MS` environment variable). Non-interactive children (squad workers, RPC probes) skip it and only register their own completed sessions for the next interactive session to process. Sessions modified within the last 10 minutes are considered still active and stay queued for a later pass. Embedding failures caused by credentials/billing (`API 401/402/403`) pause embedding for 6 hours; BM25 search keeps working and embedding resumes automatically.

### `models`

Role-based model selections. Each value is either `"auto"` or a provider profile.

Currently used:

- `capture`: session capture model.

Planned/advanced:

- `summarize`,
- `judge`.

### `qmd`

QMD SDK configuration.

| Field | Meaning |
|---|---|
| `mode` | Always `sdk` for current runtime |
| `embedEnabled` | Whether to run background embeddings |
| `providerConfig` | `pi-para-profiles` or `legacy-qmd-compatible` |
| `embedding` | Optional embedding provider profile |
| `rerank` | Optional rerank provider profile or `null` |

`legacy-qmd-compatible` reads `~/.config/qmd/index.yml` for compatibility only. New installs and migrated local setups should use `pi-para-profiles`.

pi-para never uses QMD's local/node-llama-cpp LLM fallback. If no API provider is configured, BM25 search still works and vector/chat calls fail fast instead of downloading local models.

### `lint`

| Field | Meaning |
|---|---|
| `autoFix` | Default lint autofix behavior |
| `staleDays` | Age threshold for stale pages |

Legacy `webWiki` keys are accepted for compatibility but ignored with a one-line notice because Web Wiki was removed in 0.7.

## Diagnostics

```bash
pi-para doctor
pi-para doctor --fix
pi-para doctor --test-capture-model
```

Doctor checks config, wiki directory, scheduler DB, secrets permissions, generated-state `.gitignore`, provider profiles, capture model credentials, QMD SDK health, and capture backlog.