VAULTWARDEN-SETUP: document name-based retrieval contract #14

Merged

clawdie merged 1 commit from fix/vault-fetch-contract-docs into main

2026-06-19 18:36:44 +02:00

clawdie commented

2026-06-19 18:30:25 +02:00

Owner

What

Aligns docs/VAULTWARDEN-SETUP.md with the retrieval contract that clawdie-vault-fetch actually implements. Companion PR to clawdie-iso feat/vault-seed-fetch-fixed — they should land together.

Why

The fetch helper (clawdie-iso) retrieves secrets by item name via bw get password <NAME> and no longer scopes by collection ID. This doc still taught the old contract (bw list items --collectionid <UUID> + jq). A new agent following the doc would store items the helper cannot read, and the doc's own verification test would fail against the helper.

Changes

New "Retrieval contract" section: one login item per secret, ITEM NAME = env var name, value in the password field. Item names must be unique in the visible vault (fetch is fail-closed on ambiguity). agent-secrets collection is operator organization only; uniqueness is enforced at fetch time by name.
Rewrote the Verification Test to use clawdie-vault-fetch end-to-end (with a raw bw get password fallback for hosts without the helper yet).
Rewrote "Retrieve a secret" to fetch by name + prefer --write-env upsert over copy-paste.
Dropped the hard-coded collection UUID from every fetch path.

Checks

npx prettier@3 --check docs/VAULTWARDEN-SETUP.md   # clean
git diff --check

Old-contract remnants after the change: 0.

Cross-repo consistency

Point	clawdie-iso code (this pair)	clawdie-ai doc (this PR)
Retrieval	`bw get password <NAME>`	documents `bw get password <NAME>`
Collection scoping	none (fail-closed by name)	"not scoped by collection ID"
Item naming	name = env var name	documented as the contract

Co-Authored-By: Hermes & Sam <hello@clawdie.si>

## What Aligns `docs/VAULTWARDEN-SETUP.md` with the retrieval contract that `clawdie-vault-fetch` actually implements. **Companion PR to clawdie-iso `feat/vault-seed-fetch-fixed`** — they should land together. ## Why The fetch helper (clawdie-iso) retrieves secrets by item **name** via `bw get password <NAME>` and no longer scopes by collection ID. This doc still taught the **old** contract (`bw list items --collectionid <UUID>` + `jq`). A new agent following the doc would store items the helper cannot read, and the doc's own verification test would fail against the helper. ## Changes - **New "Retrieval contract" section**: one login item per secret, **ITEM NAME = env var name**, value in the password field. Item names must be unique in the visible vault (fetch is fail-closed on ambiguity). `agent-secrets` collection is operator organization only; uniqueness is enforced at fetch time by name. - **Rewrote the Verification Test** to use `clawdie-vault-fetch` end-to-end (with a raw `bw get password` fallback for hosts without the helper yet). - **Rewrote "Retrieve a secret"** to fetch by name + prefer `--write-env` upsert over copy-paste. - **Dropped the hard-coded collection UUID** from every fetch path. ## Checks ```sh npx prettier@3 --check docs/VAULTWARDEN-SETUP.md # clean git diff --check ``` Old-contract remnants after the change: `0`. ## Cross-repo consistency | Point | clawdie-iso code (this pair) | clawdie-ai doc (this PR) | |---|---|---| | Retrieval | `bw get password <NAME>` | documents `bw get password <NAME>` | | Collection scoping | none (fail-closed by name) | "not scoped by collection ID" | | Item naming | name = env var name | documented as the contract | Co-Authored-By: Hermes & Sam <hello@clawdie.si>

clawdie added 1 commit 2026-06-19 18:30:28 +02:00

docs(vault): align VAULTWARDEN-SETUP with clawdie-vault-fetch contract

CI / ci (pull_request) Has been cancelled

Details

47c661bbc7

The fetch helper (clawdie-iso) retrieves secrets by item NAME via
'bw get password' and no longer scopes by collection ID, but this doc still
taught the old contract (collectionid + jq). New agents following it would store
items the helper cannot read, and its verification test would fail.

- Document the retrieval contract: one login item per secret, ITEM NAME = env
  var name, value in the password field. Item names must be unique in the
  visible vault (fetch is fail-closed on ambiguity).
- Rewrite the Verification Test to use clawdie-vault-fetch end-to-end, with a
  raw 'bw get password' fallback for hosts without the helper yet.
- Rewrite 'Retrieve a secret' to fetch by name + prefer --write-env upsert.
- Drop the hard-coded collection UUID from the fetch path.

Companion to clawdie-iso fix(vault): wire seed bootstrap -> vault-fetch path.

Checks: npx prettier@3 --check (clean); git diff --check.

Co-Authored-By: Hermes & Sam <hello@clawdie.si>

clawdie merged commit 151f366cc2 into main

2026-06-19 18:36:44 +02:00

clawdie referenced this pull request from a commit

2026-06-19 18:36:46 +02:00

Merge pull request 'VAULTWARDEN-SETUP: document name-based retrieval contract' (#14) from fix/vault-fetch-contract-docs into main

No reviewers

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: clawdie/clawdie-ai#14

No description provided.

Rows
Columns