---
title: Configuration
description: PromptScript configuration file reference
---

# Configuration

Complete reference for `promptscript.yaml`.

## File Location

The CLI looks for configuration in this order:

1. `--config` command line option
2. `PROMPTSCRIPT_CONFIG` environment variable
3. `promptscript.yaml` in current directory
4. `promptscript.yml` in current directory
5. `.promptscriptrc.yaml` in current directory
6. `.promptscriptrc.yml` in current directory

## Full Configuration

```yaml
# ===================
# Input Configuration
# ===================
input:
  # Entry point file (required)
  entry: .promptscript/project.prs

  # Additional files to include
  include:
    - '.promptscript/**/*.prs'

  # Files to exclude
  exclude:
    - '**/node_modules/**'
    - '**/*.test.prs'

# ======================
# Registry Configuration
# ======================
registry:
  # Local registry path
  path: ./registry

  # Or remote HTTP registry URL
  # url: https://registry.example.com/promptscript

  # Or Git repository (recommended for teams)
  # git:
  #   url: https://github.com/org/promptscript-registry.git
  #   fallbackUrl: git@github.com:org/promptscript-registry.git  # SSH fallback
  #   ref: main                    # branch, tag, or commit
  #   path: registry/              # subdirectory in repo
  #   auth:
  #     type: token                # or "ssh"
  #     tokenEnvVar: GITHUB_TOKEN  # env var with PAT

  # Authentication for HTTP registries
  # auth:
  #   type: bearer
  #   tokenEnvVar: REGISTRY_TOKEN

  # Cache settings
  cache:
    enabled: true
    ttl: 3600000 # milliseconds (1 hour)

# =====================
# Target Configuration
# =====================
targets:
  # List format (matches prs init output)
  - github
  - claude
  - cursor

# =============================
# Named Build Profiles
# =============================
builds:
  plugin-factory:
    # Optional entry override for this build only
    entry: .promptscript/project.prs

    # Optional output directory for this build only
    output: plugins/logstrip

    # Optional target list for this build only
    targets:
      - factory:
          version: multifile
          skillBaseDir: skills
          includeSkills:
            - logstrip

# =========================
# Validation Configuration
# =========================
validation:
  # Treat warnings as errors
  strict: false

  # Warnings to ignore
  ignoreWarnings:
    - 'unused-shortcut'

  # Custom rules
  rules:
    require-syntax: error
    require-identity: warning
    max-shortcuts: 20

# ====================
# Watch Configuration
# ====================
watch:
  # Files to watch
  include:
    - '.promptscript/**/*.prs'
    - 'registry/**/*.prs'

  # Files to ignore
  exclude:
    - '**/node_modules/**'
    - '**/.git/**'

  # Debounce delay (ms)
  debounce: 300

  # Clear console on rebuild
  clearScreen: true

# =====================
# Output Configuration
# =====================
output:
  # Base directory for all outputs
  baseDir: '.'

  # File header comment
  header: |
    # Auto-generated by PromptScript
    # Do not edit manually

  # Overwrite existing files
  overwrite: true

# =========================
# Formatting Configuration
# =========================
formatting:
  # Auto-detect .prettierrc in project
  prettier: true

  # Or specify explicit path to .prettierrc
  # prettier: "./config/.prettierrc"

  # Or specify options directly
  # proseWrap: always    # 'always' | 'never' | 'preserve'
  # tabWidth: 4          # Number of spaces per indent
  # printWidth: 100      # Max line width for prose wrapping

# =============================
# Universal Directory & Skills
# =============================

# Universal directory for auto-discovering skills and commands.
# - true or omitted: Use default '.agents/' directory
# - false: Disable universal directory discovery
# - string: Custom path (relative to project root)
universalDir: true # default: '.agents'

# Include the bundled PromptScript language skill in compilation output.
# When enabled, a SKILL.md that teaches AI agents how to work with .prs
# files is automatically added to each target's native skill directory.
includePromptScriptSkill: true # default: true
```

## Configuration Sections

### input

Configures source file handling.

```yaml
input:
  entry: .promptscript/project.prs
  include:
    - '.promptscript/**/*.prs'
  exclude:
    - '**/*.test.prs'
```

| Field     | Type     | Default        | Description              |
| --------- | -------- | -------------- | ------------------------ |
| `entry`   | string   | Required       | Main entry point         |
| `include` | string[] | `["**/*.prs"]` | Glob patterns to include |
| `exclude` | string[] | `[]`           | Glob patterns to exclude |

### registry

Configures the inheritance registry. PromptScript supports three registry types:

1. **Local filesystem** - for development or monorepos
2. **HTTP/HTTPS** - for simple remote registries
3. **Git repository** - recommended for teams (supports versioning via tags)

#### Local Registry

```yaml
registry:
  path: ./registry
```

#### HTTP Registry

```yaml
registry:
  url: https://registry.example.com/promptscript
  auth:
    type: bearer
    tokenEnvVar: REGISTRY_TOKEN
```

#### Git Registry

```yaml
registry:
  git:
    url: https://github.com/org/promptscript-registry.git
    ref: main
    path: registry/
    auth:
      type: token
      tokenEnvVar: GITHUB_TOKEN
  cache:
    enabled: true
    ttl: 3600000
```

**Registry Fields:**

| Field                  | Type    | Default   | Description                          |
| ---------------------- | ------- | --------- | ------------------------------------ |
| `path`                 | string  | -         | Local registry path                  |
| `url`                  | string  | -         | HTTP registry URL                    |
| `git.url`              | string  | -         | Git repository URL                   |
| `git.fallbackUrl`      | string  | -         | Fallback URL (tried on auth failure) |
| `git.ref`              | string  | `main`    | Branch, tag, or commit               |
| `git.path`             | string  | -         | Subdirectory within the repo         |
| `git.auth.type`        | string  | -         | Auth type: `token` or `ssh`          |
| `git.auth.token`       | string  | -         | Personal access token (direct)       |
| `git.auth.tokenEnvVar` | string  | -         | Env var containing the token         |
| `git.auth.sshKeyPath`  | string  | -         | Path to SSH key (for SSH auth)       |
| `cache.enabled`        | boolean | `true`    | Enable caching                       |
| `cache.ttl`            | number  | `3600000` | Cache TTL in milliseconds            |

!!! tip "Version-tagged imports"
With Git registry, you can pin imports to specific versions using Git tags:

    ```
    @inherit @company/base@1.0.0
    @use @company/security@2.1.0 as sec
    ```

    This checkouts the specified tag before fetching the file.

### registries

Defines short aliases for Git repository URLs. Aliases are used as scope prefixes in `@use` and `@inherit` paths, resolving to their full Git URL at compile time.

#### Simple Form

```yaml
registries:
  '@company': github.com/acme/promptscript-base
  '@team': github.com/acme/team-frontend
  '@shared': gitlab.com/acme/shared-libs
```

#### Extended Form (with auth)

```yaml
registries:
  '@company':
    url: github.com/acme/promptscript-base
    auth:
      type: token
      tokenEnvVar: GITHUB_TOKEN
  '@internal':
    url: git@gitlab.internal.acme.com:platform/prs-registry
    auth:
      type: ssh
      sshKeyPath: *****************
```

#### Extended Form (with fallback URL)

When registry files reference HTTPS URLs but you authenticate via SSH (or vice
versa), set `fallbackUrl` so the clone is retried with the alternative URL
on auth failures:

```yaml
registries:
  '@acme':
    url: https://github.com/acme/standards.git
    fallbackUrl: git@github.com:acme/standards.git
  '@internal':
    url: https://gitlab.internal.com/team/monorepo.git
    fallbackUrl: git@gitlab.internal.com:team/monorepo.git
    root: packages/promptscript
```

**Alias Fields:**

| Field              | Type   | Description                                    |
| ------------------ | ------ | ---------------------------------------------- |
| (simple string)    | string | Bare Git host path, e.g. `github.com/org/repo` |
| `url`              | string | Bare Git host path (extended form)             |
| `fallbackUrl`      | string | Fallback Git URL (tried on auth failure)       |
| `root`             | string | Base path within the repository                |
| `auth.type`        | string | `token` or `ssh`                               |
| `auth.tokenEnvVar` | string | Env var containing a personal access token     |
| `auth.sshKeyPath`  | string | Path to SSH private key                        |

#### Three-Level Merge

The `registries` field is resolved by merging three sources in priority order:

| Priority | Source                          | Scope         |
| -------- | ------------------------------- | ------------- |
| Highest  | `promptscript.yaml` in project  | Project-level |
| Middle   | `~/.promptscript/config.yaml`   | User-level    |
| Lowest   | `/etc/promptscript/config.yaml` | System-level  |

Project aliases override user aliases, which override system aliases. This allows IT to provision company-wide aliases (system level) while teams or projects can add or override specific aliases.

#### User-Level Config (`~/.promptscript/config.yaml`)

```yaml
# ~/.promptscript/config.yaml
registries:
  '@company': github.com/acme/promptscript-base
  '@shared': github.com/acme/shared-libs

auth:
  github.com:
    type: token
    tokenEnvVar: GITHUB_TOKEN
```

Setting aliases in user config makes them available in every project on the machine without adding them to individual `promptscript.yaml` files.

#### Usage in .prs Files

Once aliases are configured, use them in any import path:

```promptscript
# Resolves @company to github.com/acme/promptscript-base
@inherit @company/@org/base

# Versioned alias import
@use @company/@stacks/react@^1.0.0
```

### targets

Configures output targets. Targets can be specified as a simple list of names or with detailed configuration.

**List format (recommended, matches `prs init` output):**

```yaml
targets:
  - github
  - claude
  - cursor
```

**Object format (advanced, for custom options):**

```yaml
targets:
  - github:
      convention: xml
      output: custom/path/instructions.md
  - claude:
      convention: markdown
  - cursor:
      version: legacy
```

**Available Targets:**

| Target        | Default Output                    | Default Convention | Supported Versions          |
| ------------- | --------------------------------- | ------------------ | --------------------------- |
| `github`      | `.github/copilot-instructions.md` | `markdown`         | simple / multifile / full   |
| `claude`      | `CLAUDE.md`                       | `markdown`         | simple / multifile / full   |
| `cursor`      | `.cursor/rules/project.mdc`       | `markdown`         | modern / multifile / legacy |
| `antigravity` | `.agent/rules/project.md`         | `markdown`         | simple / frontmatter        |
| `opencode`    | `OPENCODE.md`                     | `markdown`         | simple / multifile / full   |
| `gemini`      | `GEMINI.md`                       | `markdown`         | simple / multifile / full   |

**Cursor Versions:**

| Version     | Output Files                                                                                        |
| ----------- | --------------------------------------------------------------------------------------------------- |
| `modern`    | `.cursor/rules/project.mdc` + `.cursor/commands/*.md` for multi-line shortcuts                      |
| `multifile` | Main + `.cursor/rules/*.mdc` (glob-based) + `.cursor/rules/shortcuts.mdc` + `.cursor/commands/*.md` |
| `legacy`    | `.cursorrules` (deprecated, no slash commands)                                                      |

!!! tip "Cursor Slash Commands"
Multi-line `@shortcuts` are automatically converted to executable slash commands in `.cursor/commands/`.
Type `/` in Cursor chat (1.6+) to invoke them. See [Language Reference](language.md#cursor-slash-commands-16).

!!! info "Cursor Identity Handling"
The Cursor formatter handles `@identity` blocks intelligently:

    - If the identity starts with "You are...", the **full content** is used as the intro
    - Otherwise, a generated intro like "You are working on {project}" is created
    - Multiline strings are automatically dedented to remove source indentation

    This means your `@identity` content appears exactly as written (without extra indentation).

**Target Configuration:**

Targets can be specified as simple names (list format) or with configuration (object format).
The list format is recommended for most projects and matches `prs init` output:

```yaml
targets:
  # List format (recommended)
  - github
  - claude
  - cursor
  - antigravity

  # Object format (for custom options)
  - github:
      convention: xml
      output: custom/path/instructions.md
  - claude:
      convention: markdown

  # With version for format variants
  - cursor:
      version: legacy # Use .cursorrules for Cursor < 0.45
  - antigravity:
      version: frontmatter # Use YAML frontmatter with activation types

  # GitHub Copilot versions
  - github:
      version: simple # Single file
  - github:
      version: multifile # Main + path-specific instructions + prompts
  - github:
      version: full # Multifile + skills + AGENTS.md (default)

  # Claude Code versions
  - claude:
      version: simple # Single CLAUDE.md
  - claude:
      version: multifile # Main + modular rules in .claude/rules/
  - claude:
      version: full # Multifile + skills + CLAUDE.local.md (default)

  # OpenCode versions
  - opencode:
      version: simple # Single OPENCODE.md
  - opencode:
      version: multifile # Main + commands
  - opencode:
      version: full # Multifile + skills + agents

  # Gemini CLI versions
  - gemini:
      version: simple # Single GEMINI.md
  - gemini:
      version: multifile # Main + commands + skills
  - gemini:
      version: full # Same as multifile (no agent concept)
```

**GitHub Copilot Versions:**

| Version     | Output Files                                                                    |
| ----------- | ------------------------------------------------------------------------------- |
| `simple`    | `.github/copilot-instructions.md` (single file)                                 |
| `multifile` | Main + `.github/instructions/*.instructions.md` + `.github/prompts/*.prompt.md` |
| `full`      | Multifile + `.github/skills/<name>/SKILL.md` + `AGENTS.md`                      |

**Claude Code Versions:**

| Version     | Output Files                                                                                      |
| ----------- | ------------------------------------------------------------------------------------------------- |
| `simple`    | `CLAUDE.md` (single file)                                                                         |
| `multifile` | Main + `.claude/rules/*.md` with path-specific rules (from `@guards.globs`)                       |
| `full`      | Multifile + `.claude/skills/<name>/SKILL.md` (from `@skills`) + `CLAUDE.local.md` (from `@local`) |

**OpenCode Versions:**

| Version     | Output Files                                                                  |
| ----------- | ----------------------------------------------------------------------------- |
| `simple`    | `OPENCODE.md` (single file)                                                   |
| `multifile` | Main + `.opencode/commands/<name>.md`                                         |
| `full`      | Multifile + `.opencode/skills/<name>/SKILL.md` + `.opencode/agents/<name>.md` |

**Gemini CLI Versions:**

| Version     | Output Files                                                             |
| ----------- | ------------------------------------------------------------------------ |
| `simple`    | `GEMINI.md` (single file)                                                |
| `multifile` | Main + `.gemini/commands/<name>.toml` + `.gemini/skills/<name>/skill.md` |
| `full`      | Same as multifile (Gemini CLI has no agent concept)                      |

**Target Options:**

| Field           | Type                | Default         | Description                                            |
| --------------- | ------------------- | --------------- | ------------------------------------------------------ |
| `enabled`       | boolean             | `true`          | Whether target is enabled                              |
| `output`        | string              | (see above)     | Custom output path                                     |
| `convention`    | string              | `markdown`      | Output convention ('xml' or 'markdown')                |
| `version`       | string              | `full`          | Format version (varies by target, see below)           |
| `skillBaseDir`  | string              | target-specific | Custom base directory for generated skill files        |
| `includeSkills` | boolean or string[] | `true`          | Emit all skills, no skills, or only listed skill names |

!!! tip "Disabling Targets"
Setting `enabled: false` skips the target during compilation.
This is equivalent to removing the target from the list.

    ```yaml
    targets:
      - github               # Will compile
      - claude:
          enabled: false     # Will NOT compile (skipped)
      - cursor               # Will compile
    ```

See [Formatters API](../api-reference/formatters/src/README.md) for more details.

!!! tip "Building skills into plugin or library folders"
Use `skillBaseDir` when you want a target to place generated skills outside
its default directory. For example, this writes Factory skills under
`plugins/logstrip/skills` when combined with a build profile output:

    ```yaml
    builds:
      logstrip-factory:
        output: plugins/logstrip
        targets:
          - factory:
              version: multifile
              skillBaseDir: skills
              includeSkills:
                - logstrip
    ```

    Run it with:

    ```bash
    prs compile --build logstrip-factory
    # or
    prs build logstrip-factory
    ```

**Built-in Conventions:**

| Convention | Section Format                         | Description               |
| ---------- | -------------------------------------- | ------------------------- |
| `markdown` | `## Section Name`                      | Markdown headers          |
| `xml`      | `<section-name>content</section-name>` | XML tags wrapping content |

### customConventions

Define custom output conventions for specialized formatting needs.

```yaml
customConventions:
  my-format:
    name: my-format
    section:
      prefix: '### '
      suffix: ''
      contentPrefix: "\n"
      contentSuffix: "\n\n"
    list:
      itemPrefix: '→ '
      itemSuffix: ''
      listPrefix: ''
      listSuffix: "\n"
    codeBlock:
      prefix: '~~~'
      suffix: '~~~'
      languageSupport: true

# Use custom convention in target
targets:
  - github:
      convention: my-format
```

**Custom Convention Structure:**

| Field                       | Type    | Description                            |
| --------------------------- | ------- | -------------------------------------- |
| `name`                      | string  | Convention identifier                  |
| `section.prefix`            | string  | Text before section name               |
| `section.suffix`            | string  | Text after section name                |
| `section.contentPrefix`     | string  | Text before section content            |
| `section.contentSuffix`     | string  | Text after section content             |
| `list.itemPrefix`           | string  | Text before each list item             |
| `list.itemSuffix`           | string  | Text after each list item              |
| `list.listPrefix`           | string  | Text before the list                   |
| `list.listSuffix`           | string  | Text after the list                    |
| `codeBlock.prefix`          | string  | Code block start marker                |
| `codeBlock.suffix`          | string  | Code block end marker                  |
| `codeBlock.languageSupport` | boolean | Whether to include language identifier |

### builds

Defines named build profiles for compiling a specific entry point to a
specific set of targets and output directories. Build profiles are useful when
one repository needs to generate extra artifacts for subpackages, plugins, or
tool-specific distribution folders without changing the default project build.

```yaml
builds:
  logstrip-factory:
    entry: .promptscript/project.prs
    output: plugins/logstrip
    targets:
      - factory:
          version: multifile
          skillBaseDir: skills
          includeSkills:
            - logstrip
```

Run a profile with either command:

```bash
prs compile --build logstrip-factory
prs build logstrip-factory
```

**Build Profile Fields:**

| Field     | Type          | Default          | Description                             |
| --------- | ------------- | ---------------- | --------------------------------------- |
| `entry`   | string        | `input.entry`    | Entry file to compile for this profile  |
| `output`  | string        | `output.baseDir` | Base output directory for this profile  |
| `targets` | TargetEntry[] | `targets`        | Target list to compile for this profile |

CLI flags still take precedence: `--target`/`--format` override the profile's
target list, and `--output` overrides the profile's `output`.

### validation

Configures validation behavior.

```yaml
validation:
  strict: false
  ignoreWarnings:
    - 'unused-shortcut'
  rules:
    require-syntax: error
```

| Field            | Type     | Default | Description             |
| ---------------- | -------- | ------- | ----------------------- |
| `strict`         | boolean  | `false` | Warnings as errors      |
| `ignoreWarnings` | string[] | `[]`    | Warning codes to ignore |
| `rules`          | object   | `{}`    | Rule severity overrides |

### watch

Configures watch mode.

```yaml
watch:
  include:
    - '.promptscript/**/*.prs'
  debounce: 300
  clearScreen: true
```

| Field         | Type     | Default        | Description         |
| ------------- | -------- | -------------- | ------------------- |
| `include`     | string[] | `["**/*.prs"]` | Patterns to watch   |
| `exclude`     | string[] | `[]`           | Patterns to ignore  |
| `debounce`    | number   | `300`          | Debounce delay (ms) |
| `clearScreen` | boolean  | `true`         | Clear on rebuild    |

### formatting

Configures output formatting to match your project's Prettier configuration.

```yaml
formatting:
  # Option 1: Auto-detect .prettierrc in project
  prettier: true

  # Option 2: Explicit path to Prettier config
  prettier: "./config/.prettierrc"

  # Option 3: Inline options (overrides .prettierrc)
  proseWrap: always
  tabWidth: 4
  printWidth: 100
```

**Prettier Detection:**

When `prettier: true`, PromptScript searches for Prettier configuration files in this order:

1. `.prettierrc`
2. `.prettierrc.json`
3. `.prettierrc.yaml`
4. `.prettierrc.yml`

**Configuration Fields:**

| Field        | Type                                    | Default      | Description                          |
| ------------ | --------------------------------------- | ------------ | ------------------------------------ |
| `prettier`   | boolean \| string \| object             | -            | Enable auto-detect, path, or options |
| `proseWrap`  | `'always'` \| `'never'` \| `'preserve'` | `'preserve'` | How to wrap prose in markdown        |
| `tabWidth`   | number                                  | `2`          | Number of spaces per indentation     |
| `printWidth` | number                                  | `80`         | Maximum line width for wrapping      |

**ProseWrap Options:**

| Value        | Description                                 |
| ------------ | ------------------------------------------- |
| `'always'`   | Wrap prose at `printWidth`                  |
| `'never'`    | Do not wrap prose (single long lines)       |
| `'preserve'` | Preserve original line wrapping from source |

!!! tip "Option Priority"
Explicit options (`proseWrap`, `tabWidth`, `printWidth`) override values from `.prettierrc`.
This allows you to use your project's Prettier config as a base while customizing specific options.

**Example: Match Project Prettier Config**

If your project already has a `.prettierrc`:

```yaml
formatting:
  prettier: true
```

**Example: Custom Formatting Without Prettier File**

```yaml
formatting:
  tabWidth: 4
  proseWrap: always
  printWidth: 100
```

### universalDir

Configures the universal directory for auto-discovering skills and commands. Skills are discovered from `<universalDir>/skills/` and commands from `<universalDir>/commands/`.

```yaml
# Use default .agents/ directory
universalDir: true

# Custom directory path
universalDir: '.my-agents'

# Disable universal directory discovery
universalDir: false
```

| Value    | Type    | Default     | Description                          |
| -------- | ------- | ----------- | ------------------------------------ |
| `true`   | boolean | `true`      | Use default `.agents/` directory     |
| `false`  | boolean | -           | Disable universal directory          |
| (string) | string  | `'.agents'` | Custom path relative to project root |

### includePromptScriptSkill

Controls whether the bundled PromptScript language skill is included in compilation output. When enabled, a `SKILL.md` that teaches AI agents how to work with `.prs` files is automatically added to each target's native skill directory.

```yaml
# Include the PromptScript skill (default)
includePromptScriptSkill: true

# Disable the PromptScript skill
includePromptScriptSkill: false
```

| Field                      | Type    | Default | Description                                 |
| -------------------------- | ------- | ------- | ------------------------------------------- |
| `includePromptScriptSkill` | boolean | `true`  | Include bundled PromptScript language skill |

## Environment Variables

Configuration values can reference environment variables:

```yaml
registry:
  auth:
    token: ${REGISTRY_TOKEN}

targets:
  github:
    output: ${OUTPUT_DIR:-.github}/copilot-instructions.md
```

| Syntax            | Description           |
| ----------------- | --------------------- |
| `${VAR}`          | Required variable     |
| `${VAR:-default}` | Variable with default |

## Minimal Configuration

The simplest valid configuration:

```yaml
input:
  entry: .promptscript/project.prs

targets:
  - github
```

## Extending Configuration

You can extend another configuration file:

```yaml
extends: ./base.config.yaml

targets:
  github:
    output: custom/path.md
```

Extended configurations are deep-merged.

## Schema Validation

The configuration file is validated against a JSON schema. Enable editor support by adding the schema reference at the top of your `promptscript.yaml`:

```yaml
# yaml-language-server: $schema=https://getpromptscript.dev/latest/schema/config.json

input:
  entry: .promptscript/project.prs
```

This provides:

- **Autocomplete** - suggestions for all configuration options
- **Validation** - errors for invalid fields or values
- **Documentation** - hover tooltips with field descriptions

!!! tip "Schema is the source of truth"
The JSON schema is automatically generated from TypeScript types in `@promptscript/core`.
When in doubt about configuration options, the schema reflects the current implementation.

    Schema URL: [`schema/config.json`](https://getpromptscript.dev/latest/schema/config.json)

## Examples

### Minimal Project

```yaml
input:
  entry: .promptscript/project.prs

targets:
  - github
```

### Multi-Team Setup

```yaml
input:
  entry: .promptscript/${TEAM}/project.prs

registry:
  path: ./shared-registry

targets:
  - github:
      output: .github/copilot-instructions.md
  - claude:
      output: CLAUDE.md
```

### CI/CD Configuration

```yaml
input:
  entry: .promptscript/project.prs

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

validation:
  strict: true

targets:
  - github
  - claude
  - cursor
  - antigravity
  - opencode
  - gemini
```

### Private Git Registry with SSH

```yaml
registry:
  git:
    url: git@github.com:org/private-registry.git
    ref: v1.0.0 # Pin to specific version
    auth:
      type: ssh
      sshKeyPath: *****************
```

### HTTPS Registry with SSH Fallback

When registry references use HTTPS URLs but you authenticate via SSH keys,
configure a `fallbackUrl` so PromptScript automatically retries the clone
with SSH on auth failure:

```yaml
registry:
  git:
    url: https://github.com/org/registry.git
    fallbackUrl: git@github.com:org/registry.git
    ref: main
```

The same pattern works for registry aliases:

```yaml
registries:
  '@acme':
    url: https://github.com/acme/standards.git
    fallbackUrl: git@github.com:acme/standards.git
```
