# Sharing Imprint skills (and their credentials) across machines

Imprint skills are designed to ship without secrets. The generated tool folder contains:

- `workflow.json` — request templates with `${credential.NAME}` placeholders and named `${state.NAME}` captures
- `playbook.yaml` — DOM playbook (no secrets)
- `index.ts` — generated MCP tool (no secrets)
- `parser.ts` (optional) — response parser
- `backends.json` (optional) — backend configuration
- `cron.json` (optional) — scheduled execution config

Credential metadata (which secrets a site needs, their descriptions) is stored locally in `~/.config/imprint/manifests/<site>.json` on each machine — it is **not** shipped with the tool folder. Use `imprint credential list <site>` to see what credentials are required.

The *values* of those credentials live in the local credential manager on each machine that runs the skill. That can include named secrets, cookies captured by `imprint login`, and declared durable browser-storage keys. There are two supported provisioning paths.

Generated `index.ts` modules import Imprint's runtime via `imprint/runtime` (a node_modules symlink that Imprint maintains automatically — created on `emit`, self-healed at runtime if the link goes stale). Skill folders are portable — just install the `imprint` package on the receiving machine via `npm install imprint` or `bun install imprint`.

## Path A — interactive provisioning on the agent (simplest)

The user clones/copies the skill folder onto the consuming agent, then runs:

```bash
git clone <skill-repo>
cd <skill-repo>
imprint credential set southwest-seats username   # prompts (silent input)
imprint credential set southwest-seats password   # prompts (silent input)
```

The names come from the tool's `credentials.manifest.json`; credential values are still stored per site so several tools for one site can share the same login safely. Imprint stores values in the OS keychain (macOS Keychain / Linux Secret Service / Windows Credential Manager) when available; it falls back to a libsodium-encrypted file at `~/.config/imprint/secrets.enc` (passphrase from `IMPRINT_PASSPHRASE` env var, or interactive prompt) on headless boxes.

This path requires the user to know (or look up) each credential value on the agent. It's the right answer for one-off setup or when you don't want secrets to travel between machines.

## Path B — encrypted bundle transfer

For users who'd rather not re-type every secret on each agent, the bundle path lets you carry credentials across machines as an encrypted file, protected by a passphrase the user chooses:

```bash
# On the laptop where the skill was taught:
imprint credential export southwest-seats --out southwest.imprintbundle
# (prompts for passphrase + confirmation)

# Transfer the bundle file via any channel — Slack, email, scp, AirDrop, etc.
# It's a passphrase-encrypted JSON envelope (libsodium secretbox + argon2id).

# On the consuming agent:
imprint credential import southwest-seats southwest.imprintbundle
# (prompts for the same passphrase)
```

The bundle envelope:

```json
{
  "version": 1,
  "site": "southwest-seats",
  "createdAt": "2026-05-06T...",
  "kdf": { "alg": "argon2id", "t": 3, "m": 65536, "p": 4, "saltB64": "..." },
  "cipher": { "alg": "xsalsa20poly1305", "nonceB64": "...", "ctB64": "..." }
}
```

The decrypted plaintext contains every secret, every cookie, every exported storage value, and the manifest for the site. Wrong passphrases fail with a clear error; tampered ciphertext fails the same way (libsodium's authenticated encryption guarantees this).

A bundle is **safe to transmit over insecure channels**. Choose a strong passphrase (≥ 8 chars) and it stays opaque even if the file is intercepted. Avoid embedding the passphrase in the same channel.

## Use with OpenClaw / Hermes

Both paths work the same way for remote agents. The skill ships as a folder; the agent's credential backend is provisioned with one of the paths above. Imprint's runtime resolves `${credential.NAME}` placeholders from that backend and produces `${state.NAME}` values inside an isolated per-call cookie/state jar — no over-the-wire credential transfer per call.

For Hermes specifically, drop the skill folder under `~/.hermes/skills/imprint-<site>/` and the SKILL.md (generated by `imprint teach`) wires it into the agent. Run `imprint credential import` once, and the agent has working access for the lifetime of the credentials.

## Credential rotation

To rotate (e.g., the user changed their password):

```bash
imprint credential set southwest-seats password   # overwrites
```

The next tool invocation picks up the new value. There's no client-side cache to flush for named secrets; each workflow execution initializes its own mutable cookie/state jar from the current credential backend.

## Migrating from the legacy JSON store

Earlier versions of Imprint kept credentials in `~/.config/imprint/credentials/<site>.json` (plaintext). To move those into the OS keychain:

```bash
imprint credential migrate
```

Each migrated `<site>.json` is renamed to `<site>.json.migrated` (not deleted) so you can audit the move. Once you've confirmed everything works, delete the `.migrated` files manually.
