merge: separate the API-only flags from the ones needing a checkout

skills/use/SKILL.md

@@ -58,6 +58,37 @@ The pin takes effect immediately — no restart. Only `tea logins list` and
 per-project by the operator (see `/tea:auth`) and injected by the guard.
 Config lives in `$XDG_CONFIG_HOME/tea`.
 
+### `--repo` takes a slug — except where a checkout is required
+
+A few commands touch local git, not just the API, and for those `--repo`
+**must be a path to a checkout**; a slug is rejected:
+
+```
+Error: local repository required: execute from a repo dir, or specify a path with --repo
+```
+
+The message reads like the flag is missing even when it was passed. Confirmed
+for `pulls create`, `pulls checkout` and `pulls clean` (tea 0.14.x). Everything
+that is only an API call — `pulls list`, `milestones`, `releases`, `times`,
+`labels`, `issues` — takes the slug from any directory.
+
+Three working forms for `pulls create`:
+
+```bash
+# 1. cwd inside the checkout, no --repo at all
+tea pulls create --login "$GITEA_LOGIN" --head feat/x --base main \
+  --title "…" --description "…"
+
+# 2. from anywhere, --repo as a PATH (this is also the git-worktree answer:
+#    point it at the main checkout)
+tea pulls create --login "$GITEA_LOGIN" --repo /path/to/checkout \
+  --head feat/x --base main --title "…" --description "…"
+
+# 3. no checkout in reach — POST it, where owner/repo is a slug again
+tea api --login "$GITEA_LOGIN" -X POST -d @tmp/pull/x.json \
+  repos/{owner}/{repo}/pulls
+```
+
 ## Index
 
 - [tea CLI overview](references/tea/index.md) — global flags, common options, output formats
@@ -125,7 +156,11 @@ are still fine via entity commands. Always the placeholder, never a login name.
 
 ## Tips
 
-- Pass `-o json` for structured output when parsing programmatically.
+- Pass `-o json` for structured output when parsing programmatically — on
+  **entity commands only**. On `tea api`, `-o` is a *file name*: `-o json`
+  writes the response body to a file called `json` and leaves stdout empty.
+  The response is already JSON, so there is nothing to format; use `-` for
+  stdout, or leave the flag off.
 - Use `--fields, -f` to narrow columns.
 - Pagination: `--page, -p <n>` and `--limit, --lm <n>` (defaults 1 / 30).
 - If a `tea` command is blocked by `tea-guard`: either you forgot

skills/use/references/tea/entities.md

@@ -19,9 +19,16 @@ Without args lists PRs; with `<index>` shows PR detail. Fields: `index,state,aut
 
 Subcommands:
 - `list, ls` (`--state`)
-- `checkout, co <idx>` — check out PR locally. `--branch/-b` creates a local branch if missing.
-- `clean <idx>` — delete local and remote feature branches for a closed PR. `--ignore-sha` matches branch by name instead of commit hash.
+- `checkout, co <idx>` — check out PR locally. `--branch/-b` creates a local branch if missing. Needs a checkout, same as `create`: `--repo` is a path here, not a slug.
+- `clean <idx>` — delete local and remote feature branches for a closed PR. `--ignore-sha` matches branch by name instead of commit hash. Needs a checkout, same as `create`.
 - `create, c` — create a PR. `--head <user:branch>`, `--base/-b`, `--allow-maintainer-edits/--edits`, `--agit`, `--topic`, plus all issue-style fields (`--title`, `--description`, `--assignees`, `--labels`, `--milestone`, `--deadline`, `--referenced-version`).
+  **Needs a local checkout.** `--repo owner/repo` is *not* accepted here — the
+  slug fails with `local repository required: execute from a repo dir, or
+  specify a path with --repo`, whose advice reads like the flag was missing.
+  Run it with cwd inside the checkout and no `--repo`, or pass `--repo
+  /path/to/checkout`. From a git worktree, point `--repo` at the main
+  checkout. With no checkout in reach, `POST repos/{owner}/{repo}/pulls`
+  through `tea api`, which takes the slug.
 - `close <idx>...`, `reopen, open <idx>...`
 - `edit, e <idx>...` — like `issues edit` plus `--add-reviewers/-r`, `--remove-reviewers`.
 - `review <idx>` — interactive review.

skills/use/references/tea/helpers.md

@@ -26,5 +26,5 @@ Authenticated HTTP request to the Gitea API. Endpoints are auto-prefixed with `/
 - `--data/-d` — raw JSON body (`@file` / `@-`). Incompatible with `-f`/`-F`.
 - `--header/-H key:value` (repeatable)
 - `--include/-i` — write status + response headers to stderr.
-- `--output/-o <file>` — write response body to file (`-` = stdout).
+- `--output/-o <file>` — write response body to file (`-` = stdout). **Not the entity commands' format flag**: `-o json` here creates a file named `json` and prints nothing. The body is already JSON.
 - Quote the endpoint if it contains `?` or `&` to prevent shell expansion.

skills/use/references/tea/index.md

@@ -14,9 +14,9 @@ Version: `tea 0.14.1` (go-sdk v0.25.1). Source: recursive `--help` traversal. Up
 | Flag | Purpose |
 |---|---|
 | `--login, -l <name>` | use a specific login from the config |
-| `--repo, -r <owner/repo>` | override repository context (local path or slug) |
+| `--repo, -r <owner/repo>` | override repository context (local path or slug). **A slug only works where the command is pure API.** `pulls create`, `pulls checkout` and `pulls clean` need a real checkout and read this flag as a path — see [SKILL.md](../../SKILL.md) |
 | `--remote, -R <name>` | discover login from this git remote |
-| `--output, -o <fmt>` | output format: `simple, table, csv, tsv, yaml, json` |
+| `--output, -o <fmt>` | output format: `simple, table, csv, tsv, yaml, json`. **Entity commands only** — on `tea api` the same flag is a FILE NAME, see [HELPERS](./helpers.md) |
 | `--page, -p <n>` / `--limit, --lm <n>` | pagination (defaults 1 / 30) |
 | `--fields, -f <list>` | which columns to print |