fix: address verified review findings (docs-deps-surface-1)

Signed-off-by: bircni <bircni@icloud.com>

docs/migration-1.0.md

@@ -34,7 +34,7 @@ that need a newer endpoint fail with the server's HTTP error instead of a
 
 Older releases kept logins and preferences in one file, `config.yml` in the `tea`
 directory under the platform configuration directory (`~/.config/tea/config.yml`
-on Linux; very old releases used `~/.tea/tea.yml`). tea 1.0 stores preferences in
+on Linux; releases up to 0.16 also fell back to `~/.tea/tea.yml` when that file was missing). tea 1.0 stores preferences in
 `config.yml` and instances and accounts in `hosts.yml`, in the same directory by
 default; `tea config path` prints both paths. When it finds an old-format file it
 stops with:
@@ -47,6 +47,7 @@ Nothing is imported automatically. Either archive the old file:
 
 ```sh
 mv ~/.config/tea/config.yml ~/.config/tea/config.yml.old   # adjust the path on macOS and Windows
+mv ~/.tea/tea.yml ~/.tea/tea.yml.old                       # if you still use the oldest location
 ```
 
 or keep it and give tea 1.0 its own directory with `TEA_CONFIG_DIR`. Do not run
@@ -104,7 +105,7 @@ Managing accounts:
 
 | Variable | tea 1.0 |
 |---|---|
-| `GITEA_TOKEN`, `GITEA_INSTANCE_URL` | supported; `TEA_HOST` is an alternative to `GITEA_INSTANCE_URL` |
+| `GITEA_TOKEN`, `GITEA_INSTANCE_URL` | supported; `TEA_HOST` is an alternative to `GITEA_INSTANCE_URL`. A `GITEA_TOKEN` without either was ignored; it now makes authenticated commands fail with exit 4, so set the instance or unset the token to use stored credentials |
 | `GITEA_INSTANCE_INSECURE`, `GITEA_INSTANCE_SSH_HOST` | supported |
 | `GH_TOKEN` | no longer read: use `GITEA_TOKEN` |
 | `GITEA_SERVER_URL`, `GITEA_SERVER_TOKEN`, `GITEA_SERVER_USER`, `GITEA_SERVER_PASSWORD`, `GITEA_SERVER_OTP`, `GITEA_SCOPES` | removed with `tea login add` |
@@ -145,8 +146,8 @@ current repository.
 | `--debug` / `--vvv` | `--debug` |
 | `--confirm` / `-y`, `--force` / `-f` on destructive commands | `--yes` / `-y` |
 
-`-R` now means `--repo`: `tea issue list -R origin` fails with
+`-R` now means `--repo`: `tea issue list -R origin` fails with a usage error
-`invalid repository URL` instead of selecting the `origin` remote. Use
+(`did you mean --remote origin?`) instead of selecting the `origin` remote. Use
 `--remote origin`.
 
 New global flags: `--no-input` disables prompts, editors and browsers, `--yes`
@@ -211,7 +212,8 @@ Subcommands:
 | `times list [user\|#issue]` | `time list [--username USER\|--issue N]` |
 | `repos search` | `search repo` |
 | `repos create-from-template` | `repo create --template OWNER/REPO` |
-| `actions secrets create` | `secret set` |
+| `actions secrets create` | `secret set` (value: see below) |
+| `actions variables set` | `variable set` (value: see below) |
 | `actions variables list --name NAME` | `variable view NAME` |
 | `actions runs delete` (alias `cancel`) | `run delete`; `run cancel` cancels without deleting |
 | `actions workflows dispatch` | `workflow run` |
@@ -240,12 +242,17 @@ Renamed flags that appear on many commands:
 | `--inactive` (webhook) | `--active=false` |
 | `--out` (man) | `--output-file` / `-o` |
 
-The long names are unchanged unless listed here. The short flags follow gh
+Other long names changed too, mostly on `admin user`, `repo fork`, `repo edit` and
+`repo migrate`; an old name fails with an unknown-flag error, so check `--help`
+of each command you script. The short flags follow gh
 instead of old tea: `-L` limit, `-s` state, `-l` label, `-a` assignee, `-A`
 author, `-m` milestone, `-t` title, `-b` body, `-F` body file, `-e` editor, `-w`
 web, `-S` search, plus the global `-R`, `-q` and `-y`. Some old shorthands now
-mean something else: `-L` is `--limit` (was `--labels`), and `-d` on `pr create`
+mean something else: `-L` is `--limit` (was `--labels`), `-d` on `pr create` is
-and `pr list` is `--draft` (was `--description`). Two flags kept their name but
+`--draft` (was `--description`), `-b` on `pr create` is `--body` (was `--base`;
+use `-B`, otherwise the pull request silently targets the default branch), `-r`
+on `pr create` is `--reviewer` (was `--repo`; use `-R`) and `-o` on `secret` and
+`variable` is `--org` (was `--output`). Two flags kept their name but
 changed meaning:
 
 - `workflow run`: `-f` was `--follow` and now means `--field KEY=VALUE`;
@@ -266,6 +273,7 @@ changed meaning:
 | `team view\|edit\|delete`, `team member\|repo ...` | team ID | `ORG/TEAM` or team ID |
 | `repo delete` | `--name NAME --owner OWNER` | optional `OWNER/REPO` argument (or `--repo`) |
 | `issue comment` | optional body argument | `--body`, `--body-file` or `--editor` |
+| `secret set`, `variable set` | `<name> [<value>]`, `--file`, `--stdin` | value from `--body`, `--body-file FILE\|-` or piped standard input |
 
 A number is read as an ID; pass `--by-name` to match a milestone, label or asset
 whose name is a number. Destructive commands still ask for confirmation unless
@@ -362,6 +370,9 @@ archive, or run `make docs`.
 - `pr review` takes the review type as `--approve` / `-a`, `--request-changes` /
   `-r` or `--comment` / `-c`; on a terminal, leaving it out starts an
   interactive review.
+- `label list` shows only the labels of the selected scope: the repository, or
+  the organization with `--org ORG`. 0.16 also listed the organization labels of
+  an organization-owned repository; `--exclude-org` was removed.
 - `notification` commands act on your whole inbox by default (the old
   `--mine`). `-R OWNER/REPO` or `--this-repo` limits them to one repository.
 - `config get KEY` prints only the value; `--show-source` adds where it comes
@@ -387,8 +398,9 @@ archive, or run `make docs`.
 - More input is checked before anything is sent: release titles, issue titles
   and comment bodies cannot be empty, a review needs a body or inline comments
   (unless it approves), team creation needs a permission, migrations from
-  GitHub, Gitea, GitLab and Gogs need an access token, and `workflow run` needs
+  GitHub, Gitea, GitLab and Gogs need an access token, and `workflow run` must find
-  a ref (`--ref` or a checked-out branch).
+  its workflow and check the inputs (without `--ref` it uses the checked-out
+  branch, else the default branch).
 - `pr merge` merges the head it read and refuses when the branch moved in the
   meantime; run it again to merge the new head.
 - Preferences follow the git/gh order: an explicit `tea config set` value wins