# @smithers-orchestrator/accounts — src

The account registry behind `smithers agents`: Claude Code / Antigravity /
Codex / Kimi subscription accounts and Anthropic / OpenAI / Gemini API-key
accounts, persisted as `~/.smithers/accounts.json` (mode 0600 — it may contain
plaintext API keys). `SMITHERS_HOME` overrides the root for tests and CI.

How the pieces fit, bottom-up:

- `accountsRoot.js` / `accountsFilePath.js` / `defaultConfigDir.js` compute paths.
- `readAccounts.js` (via `parseAccountsFile.js`) and `writeAccounts.js`
  (atomic tmp+rename) do the file I/O.
- `addAccount.js` / `removeAccount.js` are read-modify-write mutations
  serialized by `withAccountsLock.js` (O_EXCL lock file with stale-break).
- `listAccounts.js` / `getAccount.js` are the read API.
- `accountToProviderEnv.js` maps an account to the env vars its provider CLI
  honors — mirrored (not imported) by packages/usage `getAccountUsage` and the
  CLI's `runAgentAdd`, which must stay aligned with it.

Types: `Account.ts`, `AccountProvider.ts`, `AccountsFile.ts`, and
`UnknownAccount.ts` are type-only sidecars. `index.d.ts` is generated by
`tsup --dts-only` into this directory — never hand-edit it. `index.js` contains
a tool-managed `@smithers-type-exports` block; preserve it byte-for-byte.

Gotchas: `parseAccountsFile` excludes (with a once-per-process warning) legacy
entries whose provider is no longer recognized from `accounts`, returning them
verbatim in `unknownAccounts`; `writeAccounts` merges those back in, so add and
remove never destroy them. `removeAccount(label)` deletes a preserved entry and
`addAccount(account, { replace: true })` supersedes one — those are the cleanup
and migration paths. Malformed entries for recognized providers still throw
`ACCOUNTS_FILE_INVALID` instead.

`tsup --dts-only` silently re-emits an existing `index.d.ts` unchanged instead
of regenerating it; delete the file first, and note that tsup injects
`baseUrl: "."`, which TS6 rejects (TS5101) unless this package's tsconfig sets
`ignoreDeprecations`.
