Add credential preflight, categorized errors and operations guides

Sync workflow: every failure is now reported as `ERROR: [category] message`
with the categories configuration, credentials (HTTP 401), permissions
(HTTP 403) and api (other HTTP errors, unreachable service); HTTP 404 is a
configuration error. Before changing anything the workflow checks that the
GitHub token can administer the mirror repository and stops with a
permissions error otherwise. No secret value is printed.

Guides: onboarding (with runner labels, prerequisites and offline runner
symptoms), credentials (minimum permissions, preflight, rotation) and
troubleshooting (every message mapped to a category and a fix). README
capability table updated. MIL-002 records the verification of scoped
workflow support: Gitea 1.27.3 runs the workflow in this repository;
delivery to other repositories is not yet verified.

Task: MIL-002#2
Task: MIL-002#3
Task: MIL-002#4
Task: MIL-002#5
Task: MIL-002#6
Task: MIL-002#7
Refs #9
Refs #10
Refs #11
Refs #12
Refs #13
Refs #14

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

guides/onboarding.md

@@ -0,0 +1,71 @@
+# Onboarding a repository
+
+How a DevOps professional makes a TirSystem repository use the shared
+**Sync GitHub mirror metadata** workflow, and which runners it needs. Only
+this workflow exists today; the quality-check and release workflows are
+planned (see the [Project Plan](../docs/project-plan.md)).
+
+## What has been verified
+
+| Item | Status |
+| --- | --- |
+| Gitea version | 1.27.3 |
+| `.gitea/scoped_workflows/sync-github-metadata.yml` runs in this repository | Verified: run 16, `workflow_dispatch`, succeeded |
+| The same workflow applies to other repositories automatically | **Not verified.** Confirm how scoped workflows are delivered on the instance (admin or organization settings) before relying on it. |
+
+Until delivery is verified, onboard a repository by copying the workflow (below).
+
+## Steps
+
+1. **Check the prerequisites** in the repository: Actions are enabled, and a
+   runner with the label `ubuntu-latest` and `python3` is online (see
+   [Runners](#runners)).
+2. **Configure exactly one GitHub push mirror** in the repository settings
+   (Settings, Repository, Mirror settings, Push mirror). The workflow fails
+   when there are zero or several GitHub mirrors.
+3. **Add the two secrets** in the repository (or organization) settings,
+   using the scopes in [credentials.md](credentials.md):
+   - `TOKEN_FOR_GITEA`
+   - `CREDENTIALS_FOR_GITHUB` (JSON with `GITHUB_PAT`)
+4. **Deliver the workflow:**
+   - *If scoped workflows apply to the repository:* nothing to copy.
+   - *Otherwise:* copy `.gitea/scoped_workflows/sync-github-metadata.yml`
+     from this repository to `.gitea/workflows/` in the target repository.
+     Pin the copy to a reviewed version of this repository and re-copy
+     when it changes.
+5. **Set a description and topics** on the Gitea repository, so there is
+   something to sync.
+6. **Run it once manually:** Actions, **Sync GitHub mirror metadata**,
+   Run workflow. The log must end with `Synced description and topics to
+   <owner>/<repo>.` and the GitHub repository must show the same description
+   and topics.
+7. If it fails, use [troubleshooting.md](troubleshooting.md).
+
+## Runners
+
+| Item | Value |
+| --- | --- |
+| Label the workflow uses | `ubuntu-latest` |
+| Labels offered by the runner on this instance | `ubuntu-latest`, `ubuntu-24.04`, `ubuntu-22.04` |
+| Tools the workflow needs | `python3` (standard library only), outbound HTTPS to the Gitea API and `api.github.com` |
+| Needed for `actions/checkout` (used by the validation workflow) | `git` and Node.js, normally in the runner image |
+
+**Check that a suitable runner is online** (needs permission to view runners):
+
+```bash
+curl -s -H "Authorization: token $GITEA_TOKEN" \
+  https://git.tirsystem.com/api/v1/repos/<owner>/<repo>/actions/runners
+```
+
+For runners shared by the whole instance, an administrator uses
+`/api/v1/admin/actions/runners`. At the time of writing the repository and
+organization lists are empty and one instance-level runner (`36cd20104923`)
+is `online`.
+
+**Offline or incompatible runner**
+
+| Symptom | Likely cause | Action |
+| --- | --- | --- |
+| Run stays `waiting` | No online runner has the label in `runs-on` | Start the runner, or register one with the label |
+| Job fails at the start with a missing command | Runner image lacks `python3`, `git` or Node.js | Use an image that has them |
+| Job cannot reach the API | Runner has no outbound HTTPS | Fix runner network or proxy settings |