aivault

<!-- Generated by scripts/sync-skills.js. Edit docs/ sources, then run pnpm skills:sync. -->

# aivault Runtime And Integration

This skill covers secure setup and day-to-day use of `aivault` for agent workflows. The detailed
reference files are generated from this repository's `docs/` sources; update docs first, then run
`pnpm skills:sync`.

## Quick Reference

| Resource                | Path                           |
| ----------------------- | ------------------------------ |
| CLI binary              | `aivault`                      |
| Daemon binary           | `aivaultd`                     |
| Vault root (default)    | `~/.aivault/data/vault/`       |
| Daemon socket (default) | `~/.aivault/run/aivaultd.sock` |
| Repo docs source        | `docs/`                        |
| Generated skill refs    | `skills/aivault/references/`   |

## Default Workflow

1. Check status and provider setup:
   - `aivault status`
   - `aivault provider list -v`
2. Store secrets in the vault, not in agent-readable env files:
   - `aivault secrets create --name OPENAI_API_KEY --value "sk-..." --scope global`
3. Inspect available capabilities:
   - `aivault capability list`
   - `aivault capability describe openai/chat-completions`
4. Invoke through the policy boundary:
   - `aivault invoke openai/chat-completions --body '{"model":"gpt-5.2","messages":[{"role":"user","content":"hello"}]}'`
5. Verify audit trail:
   - `aivault audit`

## Detailed References

Load only what is needed:

- [references/getting-started.md](references/getting-started.md) - installation, first-run setup, and secure invocation flow.
- [references/cli-reference.md](references/cli-reference.md) - command groups and practical command patterns.
- [references/provider-plugins.md](references/provider-plugins.md) - optional provider binaries, including Postgres setup and invocation.
- [references/registry-custom-providers.md](references/registry-custom-providers.md) - built-in registry model, schema, and custom provider flow.
- [references/security-and-isolation.md](references/security-and-isolation.md) - zero-trust properties, scope resolution, encryption, audit, and threat boundaries.
- [references/operations.md](references/operations.md) - daemon behavior, environment flags, storage layout, and testing commands.

## Essential Patterns

### Registry-backed secret provisioning

Use canonical secret names such as `OPENAI_API_KEY` so aivault can pin to a provider and
auto-enable capabilities.

### Capability-first invocation

Call `aivault invoke <capability-id>`, `aivault json <capability-id>`, or
`aivault markdown <capability-id>` instead of direct upstream calls with raw keys.

### Scoped tenancy controls

Use `--scope workspace` and `--scope group` for tenant isolation, then pass
`--workspace-id` and `--group-id` on invoke.

### Provider plugin activation

If a capability starts with a plugin namespace such as `postgres/`, check
`aivault provider list -v`, then install and enable the official provider before configuring
credentials:

```bash
aivault provider install postgres --enable
```

### Custom provider fallback

Only create manual credentials and capabilities when a provider is not in the built-in registry or
available as an official provider plugin.

## Common Mistakes To Avoid

1. Storing API keys in `.env` for untrusted agent code.
2. Invoking raw URLs instead of declared capabilities.
3. Forgetting scope context when debugging credential resolution.
4. Assuming caller-provided auth headers are allowed; the broker owns auth headers.
5. Treating custom providers as equally tamper-resistant as compiled registry providers.
6. Importing database client libraries or reading `DATABASE_URL` in agent-owned code when
   `postgres/*` capabilities are available.

## Maintenance

Run `pnpm skills:sync` after docs changes. Run `pnpm skills:check` in CI or before releases to
ensure `skills/aivault` still matches `docs/`.