docs(m74-002): zombiectl login verification code + --token-name

[indykish]

Reflects M74_002 (device-flow hardening) landing in usezombie/usezombie#331 — merged 2026-05-20.

What changed

• zombiectl login now requires a 6-digit terminal-side verification code in addition to the browser approval click. The code binds the approver to the typist; URL phishing alone no longer mints a credential.
• --token-name <label> flag persists a human-readable device label alongside the token. Shows up on the approval page and in auth status. Defaults to platform family (macos-cli / linux-cli / windows-cli).
• zombiectl logout description clarified: removes local credentials and aborts in-flight login sessions, does NOT revoke the active JWT (Clerk-revocation is not a client-side operation), does NOT touch ZMB_TOKEN / ZOMBIE_TOKEN env vars.
• auth status mentions token_name field in the decoded credential.
• Quickstart Step "Sign in" mirrors the new flow with a one-line tip about --token-name for device labeling.

Files

• cli/zombiectl.mdx — login flow + flag table + logout/auth status copy
• cli/install.mdx, zombies/install.mdx — install snippet bumps
• quickstart.mdx — Sign in step
• index.mdx, docs.json — minor sync
• changelog.mdx — entry removed (lead-PR #331 carries the canonical changelog entry)

Holdback cleared

Held until usezombie/usezombie#331 merged. That landed 2026-05-20 — docs can ship.

Out of scope

Stage 1 / Stage 2 of the dashboard token-model cleanup (post-M74_002, internal architecture only) — user-invisible, no doc surface.

Greptile Summary

Documents the M74_002 device-flow hardening shipped in usezombie/usezombie#331: zombiectl login now requires a terminal-side 6-digit verification code to bind the browser approver to the typist, and gains --token-name, --token, --force, and --no-input flags for device labeling and non-interactive use.

• cli/zombiectl.mdx rewrites the entire authentication section with the new device flow, flag table, token-resolution priority order, and clarified logout/auth-status semantics; env var naming is reconciled to the single canonical ZOMBIE_TOKEN.
• api-reference/introduction.mdx replaces the now-invalid programmatic auth-session API steps with a two-token-type description (long-lived tenant API key vs short-lived user JWT) that matches the new security model.
• changelog.mdx adds the required docs-site <Update> entry (May 22, 2026) at the top per AGENTS.md, and fixes a stale ZOMBIE_API_TOKEN reference in an older entry.

Confidence Score: 5/5

Documentation-only PR; no runnable code changes. All four changed files accurately reflect the shipped M74_002 behaviour and are internally consistent.

The env-var naming has been fully reconciled to ZOMBIE_TOKEN across all changed pages, the required changelog entry is present in the correct position, and the logout/auth-status semantics are clearly delineated. The one open question — whether --token accepts tenant API keys in addition to user JWTs — is a clarification gap rather than a mis-statement, and does not affect the correctness of any other documented behaviour.

cli/zombiectl.mdx — the --token flag description would benefit from explicitly stating which token types are accepted, given the two-token-type model introduced in api-reference/introduction.mdx.

Important Files Changed

Filename	Overview
cli/zombiectl.mdx	Major rewrite of authentication section documenting the verification-code device flow, --token-name, --token, --force, --no-input flags, updated logout semantics, and reconciled env var naming to ZOMBIE_TOKEN throughout
api-reference/introduction.mdx	Replaces the now-obsolete programmatic auth-session API flow with a clean two-token-type description (tenant API key vs user JWT), accurately reflecting the new device-flow security model
changelog.mdx	Adds M74_002 changelog entry (May 22, 2026) at the correct position per AGENTS.md; also fixes a stale ZOMBIE_API_TOKEN reference in an earlier entry to the canonical ZOMBIE_TOKEN
quickstart.mdx	Updates Sign-in step to describe the verification code UX and adds a Tip for --token-name device labeling

Sequence Diagram

sequenceDiagram
    participant U as User (terminal)
    participant CLI as zombiectl
    participant B as Browser
    participant S as usezombie server

    U->>CLI: zombiectl login [--token-name label]
    CLI->>S: Initiate device flow session
    S-->>CLI: login_url + session_id
    CLI->>B: Open login_url in browser
    CLI->>U: Waiting for browser approval...

    B->>S: User clicks Approve
    S-->>B: Display 6-digit verification code
    B->>U: User reads code from browser

    U->>CLI: Type 6-digit code into terminal
    CLI->>S: Submit code bound to session_id
    S-->>CLI: JWT token

    CLI->>CLI: Persist token + token_name label
    CLI->>S: GET /v1/tenants/me/workspaces
    S-->>CLI: workspace list
    CLI->>CLI: Write current_workspace_id to local state
    CLI->>U: Login complete

    note over U,S: Non-interactive path (CI / scripted)
    U->>CLI: Supply token via flag, env var, or piped stdin
    CLI->>S: Validate supplied token
    S-->>CLI: OK
    CLI->>CLI: Persist token (token_name flag ignored)
    CLI->>U: Login complete

Loading

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
cli/zombiectl.mdx:49
**`--token` flag doesn't specify accepted token types**

The flag description says "authenticate non-interactively with a token directly" without clarifying whether it expects a user JWT, a tenant API key (`zmb_t_…`), or both. The `api-reference/introduction.mdx` distinguishes those two token types with very different lifetimes (User JWT ~15 min, tenant API key long-lived) and recommends tenant API keys "for unattended access". A CI engineer reading only this page who supplies a short-lived user JWT via `--token` will get silent `TOKEN_EXPIRED` failures within 15 minutes without any pointer to the correct credential type.

_{Reviews (5): Last reviewed commit: "docs: correct programmatic-auth guidance..." | Re-trigger Greptile}

Context used:

• Context used - AGENTS.md (source)

[indykish]

Addressed the two latest review findings on `cli/zombiectl.mdx` in 688aff7:

• --token-name scope (line ~49) — broadened: it's ignored for any non-browser token source (--token, the ZOMBIE_TOKEN env var, or piped stdin), not just --token. Matches the handler, which emits the "ignored" note for any directly-resolved token.
• Non-interactive exit wording (line ~55) — a non-interactive shell can't prompt, so it now reads "exits immediately with an error instructing you to supply one via --token, ZOMBIE_TOKEN, or piped stdin" rather than "fails fast asking for one".