# User-Level Configuration

PromptScript supports user-level configuration at `~/.promptscript/config.yaml`. This provides default settings that apply across all your projects, reducing repetitive configuration.

## Config File

Create `~/.promptscript/config.yaml`:

```yaml
version: '1'
telemetry: false

registry:
  git:
    url: https://github.com/your-org/your-registry.git
    ref: main
    auth:
      type: token
      tokenEnvVar: GITHUB_TOKEN
  cache:
    enabled: true
    ttl: 3600000 # 1 hour

defaults:
  targets:
    - github
    - claude
  team: frontend
```

## Fields

### `telemetry`

Controls anonymous aggregate usage telemetry for every project unless a project
also opts out. Default is `true`.

```yaml
telemetry: false
```

Any telemetry opt-out is a hard veto rather than a normal priority override.
`DO_NOT_TRACK`, user config, and project config can each disable delivery.

### `registry`

Default registry configuration used when no project-level registry is configured.

| Field                           | Description                              |
| ------------------------------- | ---------------------------------------- |
| `registry.git.url`              | Git repository URL                       |
| `registry.git.ref`              | Branch, tag, or commit (default: `main`) |
| `registry.git.path`             | Subdirectory within repo                 |
| `registry.git.auth.type`        | Authentication: `token` or `ssh`         |
| `registry.git.auth.tokenEnvVar` | Env var containing the token             |
| `registry.git.auth.sshKeyPath`  | Path to SSH key                          |
| `registry.url`                  | HTTP registry URL                        |
| `registry.cache.enabled`        | Enable caching (default: `true`)         |
| `registry.cache.ttl`            | Cache TTL in milliseconds                |

### `registries`

Registry aliases available in every project. A project alias with the same name
wins. `prs registry add --global` writes here.

```yaml
registries:
  '@company': github.com/acme/promptscript-base
```

### `defaults`

Default values used by `prs init --yes` when no CLI flags are provided.

| Field              | Description                 |
| ------------------ | --------------------------- |
| `defaults.targets` | Default compilation targets |
| `defaults.team`    | Default team namespace      |

## System Config

IT or platform teams can provision a config file with the same format at
`/etc/promptscript/config.yaml` (`%ProgramData%\promptscript\config.yaml` on
Windows). It sits under the user config:

- user values win, and `registries` and `defaults` merge key by key
- a user `registry.git` or `registry.url` replaces the system registry backend
- `telemetry: false` at any layer is a hard opt-out, so a system `false` cannot be
  turned back on by the user, a project or a CLI flag

`prs registry list` shows system aliases with `(system)`.

## Priority Order

Configuration is merged from multiple sources with this priority (highest wins):

1. **CLI flags** (`--registry`, `--targets`, etc.)
2. **Environment variables** (`PROMPTSCRIPT_REGISTRY_GIT_URL`, etc.)
3. **Project config** (`promptscript.yaml`)
4. **User config** (`~/.promptscript/config.yaml`)
5. **System config** (`/etc/promptscript/config.yaml`)

## Environment Variables

Override any config value with environment variables:

| Variable                        | Maps to                  |
| ------------------------------- | ------------------------ |
| `PROMPTSCRIPT_REGISTRY_GIT_URL` | `registry.git.url`       |
| `PROMPTSCRIPT_REGISTRY_GIT_REF` | `registry.git.ref`       |
| `PROMPTSCRIPT_REGISTRY_URL`     | `registry.url`           |
| `PROMPTSCRIPT_CACHE_TTL`        | `registry.cache.ttl`     |
| `PROMPTSCRIPT_CACHE_ENABLED`    | `registry.cache.enabled` |
| `PROMPTSCRIPT_TELEMETRY`        | `telemetry`              |
| `DO_NOT_TRACK`                  | Disables telemetry       |

Example:

```bash
PROMPTSCRIPT_REGISTRY_GIT_URL=https://github.com/my-org/reg.git prs init --yes
```

## How It Works with `prs init`

When running `prs init --yes`:

1. Loads user config from `~/.promptscript/config.yaml`, with the system config merged under it
2. Uses `registry` from user config if no `--registry` flag provided
3. Uses `defaults.targets` if no `--targets` flag provided
4. Uses `defaults.team` if no `--team` flag provided
5. Attempts to fetch manifest from configured registry for suggestions