# init — Initialize a Data Store from a YAML Definition

**Script name:** `init`

**Script location:** [`scripts/init.ts`](../../../scripts/init.ts)

**Invoke:**
```bash
npx --yes tsx .opencode/skills/templating-vault/scripts/init.ts \
  --source DEFINITION.yaml --target DATA_DIR [--on-exists MODE]
```

**CRITICAL:** Always invoke the script using bash and the format noted above.

## Synopsis

```
init.ts --source PATH --target PATH [--on-exists ignore|validate|fix]
```

Creates or validates a data directory from a YAML definition. The definition
describes store-level defaults, per-key metadata, and optional preset values.
This is the primary way to bootstrap a store with the correct metadata
(literal/non-literal flags, type validators, write-once locks) before agents use it.

## Arguments

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--source PATH` | string | required | YAML definition file |
| `--target PATH` | string | required | Data directory to create/validate |
| `--on-exists MODE` | string | `ignore` | What to do if the target already exists |

### on-exists Modes

| Mode | Behavior |
|------|----------|
| `ignore` | If target exists, do nothing and return success |
| `validate` | Check that existing store matches the definition; error on divergence |
| `fix` | Bring the store into agreement with the definition (add missing keys/metadata, fix changed metadata, don't delete extra keys) |

## Definition Format

```yaml
defaults:
  literal: true
  type: string
  write_once: false

keys:
  global.credentials.forgejo_pat:
    literal: true
    write_once: true
    type: hex
    validate:
      regex: "^[0-9a-fA-F]{40}$"
      message: "Must be a 40-character hex token"
    description: "Primary bot Forgejo PAT"

  global.config.max_workers:
    literal: false
    type: positive_integer
    on_absent: "4"
    description: "Maximum parallel workers"

  templates.imp_supervisor:
    template: true
    readonly: true
    value: |
      Repository base url: {{ forgejo_url }}
      forgejo pat: {{ forgejo_pat }}
      ...
```

Keys listed under `keys:` get their metadata written to `meta.yaml` files. If `value:` is
specified, the value is also written. The `defaults:` section is written to `.store.yaml`.

## Output (stdout)

```json
{
  "initialized": true,
  "action": "fix",
  "target": "/tmp/my-store",
  "actions": ["wrote .store.yaml", "wrote meta for global.credentials.forgejo_pat", ...]
}
```

## Usage Examples

```bash
# Bootstrap the global store from the shipped definition
npx --yes tsx .opencode/skills/templating-vault/scripts/init.ts \
  --source .opencode/skills/templating-vault/definitions/global.yaml \
  --target /tmp/templating-vault --on-exists fix

# Validate an existing store hasn't diverged
npx --yes tsx .opencode/skills/templating-vault/scripts/init.ts \
  --source definitions/global.yaml \
  --target /tmp/templating-vault --on-exists validate
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Fatal error or validation failure (when --on-exists validate) |
