docs: tighten the completion and 1.0 migration notes

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

README.md

@@ -69,7 +69,7 @@ Alternatively, `tea auth login --host https://your-instance --oauth` authorizes
 
 ### Shell completion
 
-If you installed from source or the package does not provide the completions with it you can add them yourself with `tea completion <shell>` command. Completion offers commands, flags, flag values such as `--state` and `--json` fields, and values from your instance such as repositories. Add the line for your shell to its startup file:
+If you installed from source or the package does not provide the completions with it you can add them yourself with `tea completion <shell>` command. Add the line for your shell to its startup file:
 
 ```shell
 # ~/.bashrc (on macOS, ~/.bash_profile)
@@ -86,7 +86,7 @@ tea completion fish > ~/.config/fish/completions/tea.fish
 tea completion powershell | Out-String | Invoke-Expression
 ```
 
-The bash script needs the bash-completion package. On macOS, install `bash-completion` with Homebrew for the system bash 3.2 (or `bash-completion@2` for a Homebrew bash 4.2+), and use `eval` as above: bash 3.2 cannot `source <(...)`. Without `compinit`, zsh reports `command not found: compdef`. `tea completion <shell> --help` shows these steps and how to install the script system-wide.
+The bash script needs the bash-completion package. `tea completion <shell> --help` shows the details for each shell.
 
 ### Man Page
 

docs/migration-1.0.md

@@ -124,13 +124,10 @@ from that helper and falls back to prompting. Register the new helper:
 tea auth setup-git --host https://gitea.example.org
 ```
 
-`tea auth setup-git` replaces every credential helper configured for the
+It replaces every helper configured for the instance URL, the old entry
-instance URL, the old `!tea login helper` entry included, so that other helpers
+included. With `--keep-helpers` it adds tea's helper after them instead; then
-neither answer for tea nor keep a copy of its token. Pass `--keep-helpers` to
+remove the old entry with
-add tea's helper after the existing ones instead; then remove the old entry
-yourself with
 `git config --global --unset-all credential.https://gitea.example.org.helper '^!tea login helper$'`.
-`tea auth status` reports whether the helper is configured.
 
 `tea repo clone`, `tea pr checkout`, `tea pr clean`, `tea repo sync` and
 `tea pr create --agit` authenticate Git without any helper; `tea auth setup-git`
@@ -159,12 +156,9 @@ discovery, and `--sudo USER` acts as another user (administrators only).
 ## Renamed commands
 
 All command groups are singular, and the old built-in aliases (`c`, `e`, `i`,
-`ms`, `lgtm`, …) are gone. Subcommands take gh's verb aliases instead: `ls` for
+`ms`, `lgtm`, …) are gone. Subcommands take gh's verb aliases instead (`ls`,
-`list`, `rm` for `delete`, `new` for `create`, `add` for `issue comment create`,
+`rm`, `new`, `add`, `co`, `search issues`, `search prs`); `tea <command> --help`
-`pr comment create`, `ssh-key create` and `time create`, `co` for
+lists them. `tea alias set NAME EXPANSION` defines your own top-level shortcuts, for example
-`pr checkout`, and `search issues` / `search prs` for `search issue` /
-`search pr`. `tea <command> --help` lists the aliases of each command.
-`tea alias set NAME EXPANSION` defines your own top-level shortcuts, for example
 `tea alias set prs 'pr list --author @me'`.
 
 Top-level groups:
@@ -293,7 +287,7 @@ tea notification list -q '.[].title' | xargs -n1 notify-send
 `--json` alone prints every field; `--json a,b` selects fields and rejects unknown
 names; `--jq` / `-q` filters the result and implies `--json`. Commands that
 produce no resource, such as deletes, reject `--json` with a usage error instead
-of printing nothing. See `tea help formatting`.
+of printing nothing.
 
 When stdout is not a terminal, lists print tab-separated values without header,
 color or links, with times in RFC 3339 UTC, and a `--page` hint goes to stderr;
@@ -343,8 +337,7 @@ tea completion fish > ~/.config/fish/completions/tea.fish
 tea completion powershell | Out-String | Invoke-Expression      # PowerShell profile
 ```
 
-`tea completion <shell> --help` explains the requirements of each shell and how
+`tea completion <shell> --help` explains each shell's requirements.
-to install the script system-wide.
 
 Packagers can ship the pre-generated scripts and man pages from the release docs
 archive, or run `make docs`.
@@ -364,10 +357,8 @@ archive, or run `make docs`.
   `--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
   from.
-- `auth status` groups accounts by instance, marks each as usable or not, and
+- `auth status` exits with 4 when there is no account or a credential is
-  reports whether the Git credential helper is configured. It exits with 4 when
+  missing or rejected. `auth token` prints the active account's token.
-  there is no account or a credential is missing or rejected. `auth token`
-  prints the token of the active account for scripts.
 - `webhook edit` must be told what to do with the delivery authorization header
   on every call, because Gitea replaces it: pass `--authorization-header`,
   `--authorization-header-file` or `--clear-authorization`. The signing secret
@@ -377,7 +368,7 @@ archive, or run `make docs`.
 - `--no-input` disables prompts, editors and browsers. With `--json`, tea never
   prompts unless `--interactive` is given; required values must come from flags.
 - Destructive commands and `pr merge` confirm on a terminal and need `--yes`
-  (`-y`) elsewhere; the help of each such command lists `--yes`.
+  (`-y`) elsewhere.
 - `--limit` (`-L`) accepts 1 to 1000 and `--page` a positive number; other
   values are usage errors instead of being passed to the server. tea pages
   through the server's smaller pages to reach the limit.