AGENTS.md@packages/client/src/components/settings/vault git:20261025.ef25c2aA

Immutable. This exact content never changes and is served at /api/v1/blob/35de7cbab6ffdb38.

# DOX — packages/client/src/components/settings/vault

Settings → Vault page. Never receives a stored value: listings carry ids, labels, names, states.

| File | Purpose |
|------|---------|
| `OperateRequiredCallout.tsx` | Info callout (`role="status"`, `aria-busy` while retrying) for an `operate_required` load refusal: fixed copy, one row per recognised remedy in server order (unknown dropped), `/auth/login` link on `sign-in`, single-flight Try again. Ids `vault-operate-{required,remedy,signin,retry}`. Gains `request-access` row (icon `mdiAccountArrowRight`; `<a data-testid="vault-operate-request-access">` from `requestAccessTarget(apiBase, origin)`, new context ⇒ `target=_blank rel="noopener noreferrer"`); prop `apiBase`. See change: surface-operate-required-remedy, add-request-access-remedy. Rendered by kit `SettingsNotice` (`remedies` with id/testId, `retryTestId`, `retrying`→`aria-busy`). See change: align-ui-contract-recipes. Variable link targets render via `SafeLink` (`classifyUrl`; blocked → inert text). See change: harden-client-sinks. |
| `VaultAccountsPanel.tsx` | Accounts tab: key accounts + Sign-in / Services groups (other kinds = count); add-key form (`vault-account-new` toggle, password field cleared on send, 8-char check, optional `<PROVIDER>_API_KEY` variable offer, partial-failure callout with idempotent Retry); rotate note; two-step revoke via `ConfirmImpact`. `useAddKeyForm` holds form state. See change: add-credential-vault, retro-ux-credential-vault. `tls-solver` accounts form a "TLS certificates" group (`TlsAccountRow`: label + provider + "Gateway source <id>" + link to `/settings/gateway`; no rotate/revoke, no value). See change: add-acme-dns01-certs. |
| `VaultImportPanel.tsx` | Import tab: known-location candidates (prop `candidates`, opaque ids) + file upload ≤64 KiB → names-only review (per-name notes, skipped with reasons) → confirm; optional same-name variables (not atomic; failures named); done callout. See change: add-credential-vault, retro-ux-credential-vault. |
| `VaultProjectPicker.tsx` | "Grant to a project": open + remembered projects (`GET /api/vault/projects`) as radios, blocked entries disabled with reason, manual repo (normalised via shared `vault-origin`) / folder entry, account override. Refuses a project that already has the variable (grant upserts, would drop its account). Older server → manual entry only. See change: retro-ux-credential-vault. `transport-insecure` → "no proven TLS connection". See change: prove-vault-bridge-tls. |
| `VaultSection.tsx` | Settings → Vault page (Network group, route `vault`): flow strip, APG tablist Variables / Accounts / Import (panels stay mounted, inactive `hidden`), loading skeleton, first-run guide, stale-server callout (`vault-error`, Restart server via `POST /api/restart`, Try again), corrupt callout, `OperateRequiredCallout` on `operate_required`. Tests: `__tests__/VaultSection.test.tsx`, e2e `vault-settings.spec.ts`. Stores refusal as `{remedies, base}` (`VaultResult.base`), passes `apiBase` to the callout so the link keeps targeting the refusing server. See change: add-credential-vault, surface-operate-required-remedy, retro-ux-credential-vault, add-request-access-remedy. |
| `VaultVariableCard.tsx` | One card per variable (`vault-binding-NAME`): default account (draft + Save default with impact), project grant rows (`data-state` ok / no-account, `data-status` delivering / pending / no-account / no-default), confirmed checkouts, plugin approvals (`role="switch"` checkbox), two-step delete. See change: retro-ux-credential-vault. |
| `VaultVariablesTab.tsx` | Variables tab: new-variable form (reserved / invalid names refused inline), plugin requests for missing variables, `vault-grants-list` of cards, other confirmed checkouts. See change: retro-ux-credential-vault. |
| `vault-ui.tsx` | Shared vault recipes: class tokens, `StatusPill`, `GrantStatusPill`, `BindingStatePill`, `Callout`, `ErrorLine`, `FieldError`, `ApprovalSwitch`, `ConfirmImpact` (`role="alertdialog"`, impact re-read on open, Cancel focused), `runOp`. Theme tokens only, text ≥ 12 px. See change: add-credential-vault, retro-ux-credential-vault. `StatusPill`/`Callout`/`ErrorLine`/`FieldError` are thin wrappers over kit `SettingsStatusPill`/`SettingsNotice`/`SettingsActionError` (call sites unchanged); `TONE_PILL` removed. See change: align-ui-contract-recipes. |
| `__tests__/vault-fixtures.ts` | Shared fetch stub (`stubVaultFetch`, `ok`/`fail`/`html` replies with JSON content-type), `makeOverview`, `callsTo`. See change: retro-ux-credential-vault. |
| `__tests__/VaultAccountsPanel.test.tsx` | E14, E15, X4, F6, X9 accounts tab. See change: retro-ux-credential-vault. E28 TLS solver group. See change: add-acme-dns01-certs. |
| `__tests__/VaultImportPanel.test.tsx` | E22, X5 import review and partial failure. See change: retro-ux-credential-vault. |
| `__tests__/VaultProjectPicker.test.tsx` | Picker lists, manual entry, already-granted, E21 refused sessions, X3 older server. See change: retro-ux-credential-vault. |
| `__tests__/VaultSection.test.tsx` | Page states: tabs F1, first run F2, skeleton F3, stale server X1, unreachable X2, corrupt X6. See change: add-credential-vault, retro-ux-credential-vault. |
| `__tests__/VaultVariablesTab.test.tsx` | E16–E19, F5 variables tab: name rules, grant status, service subjects, plugin request, delete impact. See change: retro-ux-credential-vault. |