# Admin & Database Operations Guide

*How to administer Trackmint's users and data. The tool is `agent-tool/trackmint-admin.js` (Node + firebase-admin, same service-account key as the agent CLI). These are the standard operating workflows — modeled on how ops teams run comparable SaaS backends (user lifecycle, surgical record edits, backup-before-destructive, audit trail).*

## The data model in one paragraph

One Firebase **Auth user** per account; one Firestore document per account at **`workspaces/{uid}`** holding the entire workspace: `setup` (company), `members[]`, `projects[]`, `payments`, `currency`, `reminders`, `colNames`/`startCol` per pack, and `data.{dev|legal|trade|general}` each with `items[]`, `budgets`, `invoices[]`, `expenses[]`, `timeEntries[]`. The app defensively normalizes whatever it loads (`repo.ts`), so a hand-edited doc with a missing field self-heals — but stick to the workflows below anyway.

## Workflow 1 — User lifecycle

**Add a user** (e.g. onboarding a beta tester): `users:add tester@firm.com <temp-password>` → send them the password → their first login runs the setup wizard and creates their workspace doc automatically.
**Reset a password**: `users:reset-password <uid> <new>` (find the uid with `users:list`).
**Suspend / restore**: `users:disable <uid>` blocks sign-in without touching data; `users:enable` restores.
**Delete a user (GDPR/offboarding)**: `users:delete <uid> --with-data` — deletes the Auth account AND the workspace doc, writing a JSON backup first automatically. Without `--with-data` the workspace doc is kept (e.g. company account transfers).

## Workflow 2 — Inspect and edit any record or field

**Find the workspace**: `ws:list` (shows company, pack, member/item counts) → `ws:get <uid>` for the whole doc, or `ws:get <uid> members` / `ws:get <uid> data.dev.items.3` for one branch.
**Change a specific field on a specific record** — the dot-path addresses anything, numeric segments index arrays:

```
ws:set <uid> currency '"EUR"'                       # workspace field
ws:set <uid> members.1.rate 150                     # 2nd member's hourly rate
ws:set <uid> members.1.role '"manager"'             # promote to manager
ws:set <uid> data.dev.items.3.completed true        # complete a task
ws:set <uid> data.dev.items.3.title '"New title"'   # rename a record
ws:set <uid> projects.0.budget 12000                # fix a project budget
ws:delete-field <uid> data.dev.items.3.assignStatus # clear a field
```

Every `ws:set` runs in a transaction (re-read → modify → write) because the workspace is a single document — the same safety rule agents follow (AGENT_SOP.md).

## Workflow 3 — Backup, restore, disaster recovery

**Before any bulk or destructive edit**: `ws:backup <uid>` → timestamped JSON on disk. **Restore**: `ws:restore <uid> backup-….json` (full overwrite). Destructive commands (`ws:delete`, `users:delete --with-data`) auto-backup first — a delete is always reversible from the snapshot. For fleet-wide backups, loop `ws:list` output through `ws:backup` on a nightly cron.

## Workflow 4 — Support playbooks (the requests you'll actually get)

"**I renamed my company wrong**" → `ws:set <uid> setup.companyName '"Right Name LLC"'`.
"**My worker left, remove them**" → check nothing open: `ws:get <uid> data.dev.items`, reassign via `ws:set … assigneeId`, then remove the roster entry by writing the filtered array: `ws:get <uid> members` → edit → `ws:set <uid> members <json>`.
"**An invoice was marked paid by mistake**" → `ws:set <uid> data.dev.invoices.2.status '"Sent"'` and `ws:delete-field <uid> data.dev.invoices.2.paidVia`.
"**Wipe my demo data but keep my account**" → `ws:backup` then `ws:delete <uid>`; next app launch reseeds a clean workspace through the wizard.

## Workflow 5 — Governance & safety rules

The Admin SDK bypasses Firestore security rules entirely: the service-account key IS root. Keep it off shared machines, never commit it (gitignored), rotate it from Firebase Console if exposure is suspected. One operator at a time for writes on the same workspace (single-doc model). Log what you change: each command's stdout line into an ops journal is the audit trail until a proper audit log ships. Agents never get this tool — they use `trackmint-agent.js`, which can only touch task-level fields under the SOP.

## What's intentionally NOT here (roadmap)

A web admin panel (this CLI is the v1 admin UI), automated nightly backups, an immutable audit log, and bulk anonymization for GDPR export requests. All straightforward extensions of the same key + Admin SDK foundation.