Velais 1Password

Keep the company’s 1Password account in the structure the owner chose. One vault per purpose, access that matches who works on what, items that say what they are.

Non-negotiable rules

1. Never display secret values. Read only username, and print it only after the strict filter in the scripts (a real email or a plain identifier, else (hidden)). Move, compare and convert values inside one script, in memory. If a value does get displayed, say so immediately and recommend rotating it.
2. Plan → owner approval → apply → verify. Show a table (vault/item → destination, title, type, tags) before any change. After applying, re-read and compare. op exit codes lie (404 after a successful write).
3. Reversible first: suspend before deleting users, archive (--archive) before deleting items, check --include-archive before deleting a vault, back up nothing that contains secrets to plain files.
4. One vault at a time, addressed by ID. Vault names are not unique.
5. Never open someone’s personal vaults. For company-named vaults another person created, grant yourself access only on the owner’s decision, move company items, then revoke yourself.
6. Keep it generic in shared artefacts: no client, project or employee names in skills, templates or docs meant for reuse.

Target structure (summary)

Vault	Who	What
Velais – Admin	owner	card, banks, company details, root accounts, company API keys
Velais – Engineering	owner + second admin	shared technical/company accounts
Velais – Team	everyone (Team Members group)	team-wide role accounts and tools
Client – <Name>	owner + people on that client	the client’s credentials and engagement accounts
Employee	each person	their identity and their own logins (firstname.lastname@), tagged client/<name> when used on a client

Every item has exactly one owner tag (velais | client/<name> | personal), plus optional project/<name>, env/prod|staging|dev|test|local and status/decommissioned. Titles follow <Service> – <What> (<qualifier>). API keys are API Credentials, never notes.

Read references/structure-and-conventions.md before classifying items or creating vaults. It has the placement rules, naming, types, tags and client lifecycle.

Workflow

Step 1: Connect

op vault list >/dev/null || echo "enable 1Password → Settings → Developer → Integrate with 1Password CLI"

Each session needs the owner’s Touch ID approval. Use the desktop-app integration, never a password typed into the terminal.

Step 2: Inventory

python3 scripts/op_inventory.py --out "$SCRATCH"/op    # all vaults incl. ones you're not a member of

It writes inventory.json (0600) and prints members per vault plus audit flags: Team Members on client vaults, empty vaults, duplicate vault names, junk tags, items without exactly one owner tag, untitled items, passwords sitting in username fields.

Step 3: Plan with the owner

Pick the procedure in references/procedures.md: periodic audit, new client, client status change, onboarding, offboarding, merging an import or a parallel structure, item cleanup, credential rotation. Build the plan, show the table, and ask only the questions that change the outcome: unknown client, unknown environment, test data, which duplicate is current.

Step 4: Apply and verify

python3 scripts/op_apply_plan.py plan.json            # dry run
python3 scripts/op_apply_plan.py plan.json --apply    # moves, renames, tags, conversions, archive; re-reads and retries
python3 scripts/op_duplicates.py --vault <id>         # identical vs differing duplicates, values compared in memory
python3 scripts/op_duplicates.py --vault <id> --archive-identical

Access changes (vaults, grants, users) go through plain op commands, listed in references/op-cli-gotchas.md. List members again after each one.

Step 5: Hand over

Report what changed with counts. Give a table of what must be done in the app (SSH keys, passkey items) and the open decisions (differing duplicates, rotation). Re-run the inventory once the owner says the manual part is done.

Examples

“Add a vault for our new client Acme; two of our developers work on it.” Create Client – Acme with the description Active client., grant the owner and those two people allow_viewing,allow_editing, and introduce the tag client/acme. No Team Members group.

“Someone left today.” Suspend them, list their direct grants and admin roles, make sure two administrators remain, and ask them for an export of company items. Delete only after the owner confirms. If they now work at a client, share the items they need via item share links instead of reactivating them.

“Clean up after the CSV import.” Inventory, classify by identity (placement rules), rename to <Service> – <What> (<qualifier>), replace import tags with the taxonomy, convert API-key notes, merge identical duplicates, and list the SSH keys and passkey items for the app.

Error Handling

Known op limits (SSH keys and passkey items not editable, no SSH key import, the Employee vault can’t be renamed, cached item counts, false 404s, Events API refused from a CLI session, invalid icons) and their workarounds are in references/op-cli-gotchas.md. Read it when a command fails, before retrying. Retry once at most. On a permission error (403), stop and tell the owner what to do on 1password.com.