---
name: auth
description: Pin the Gitea login used by the tea CLI in this project. Run when the tea-guard hook reports no login is pinned, or when the user types /tea:auth. Enumerates available logins, makes the OPERATOR pick one, and persists it to .claude/settings.local.json. The pin takes effect immediately — no restart.
---

# /tea:auth — pin the project Gitea login

Goal: have the **operator** select exactly one `tea` login for this project and
persist it to `.claude/settings.local.json` under `env.GITEA_LOGIN`. The
`tea-guard` hook reads this file at call time and rewrites every
`--login "$GITEA_LOGIN"` to the pinned value, so the choice takes effect
**immediately, with no session restart**.

## The one hard rule: the operator chooses, never you

Picking the wrong identity is the exact failure this command exists to prevent.
So:

- **ALWAYS** present the choice with `AskUserQuestion` and let the operator
  pick — even if memory, context, the repo URL, or a previous session suggests
  a "likely" login. Do **not** auto-select from memory or infer it. A wrong
  guess writes under the wrong account.
- The only exception: exactly **one** login exists on the machine — then
  propose it and still confirm before writing.

## Steps

1. Enumerate logins (allowed by the guard even with no pin):
   `tea logins list -o json`
2. **No logins:** stop and ask the operator to run `tea logins add` themselves
   — it is interactive (prompts for URL/token). Do not run it for them.
3. **One login:** propose it; confirm before writing.
4. **Several logins:** `AskUserQuestion` with each login's `name`, `user`, and
   `url` so the operator's choice is unambiguous. Never decide for them.
5. Merge the chosen name into the **project root's**
   `.claude/settings.local.json` under `env` (do not clobber other keys):
   ```json
   { "env": { "GITEA_LOGIN": "<chosen-name>" } }
   ```
   **In a git worktree, write it to the main checkout, never to the worktree.**
   A worktree is deleted when the branch is done, taking a pin written into it
   with it, and one repository with two pins is one repository with two
   identities. Both the guard and the scripts already reach the main checkout's
   pin from inside any worktree — so there is nothing to pin a second time.
   `git rev-parse --path-format=absolute --git-common-dir` names the `.git` to
   write beside.
6. Done — it is live. The guard resolves the pin from the file on the next
   `tea` call; no restart needed. Tell the operator which login is now pinned,
   and which file it went in.

## Where the pin is looked for

One search order, written once in `scripts/pin.py` and imported by both the
`tea-guard` hook and the sync/wiki transport — they cannot disagree about a
directory, and a test asserts neither keeps a copy of the walk.

`$CLAUDE_PROJECT_DIR`, then the caller's hint (the hook passes the Bash call's
`cwd`), then the current directory. Each is searched up its parent chain; only
if that finds nothing does the search cross into the main working tree of a
linked worktree, via `gitdir:` in the `.git` file. The plugin's own directory
is never a source — a plugin pointed at somebody else's project must take the
identity from that project, not from where it happens to be installed.

If a script reports "no login pinned", that is the honest answer: nothing was
found anywhere on that order. Pin one — at the project root.

## Identity-safety rules

- NEVER run commands that mutate logins or global login state:
  `tea logins add/edit/delete/default`, `tea logout`. Read-only
  `tea logins list` is the only allowed login command.
- If a `tea` call fails with a permission/scope error, report it. Do NOT try to
  fix it by switching to, or editing, a different login.
- If you ever see `no gitea login detected, falling back to login '...'`, treat
  it as a hard failure: stop, do not act on the result, surface it.