docs: tailored README + AGENTS.md signpost (pod-github-runner) (#286)

AGENTS.md

@@ -0,0 +1,68 @@
+# AGENTS.md — pod-github-runner
+
+Standalone candy repo for the `github-runner` candy — a GitHub Actions
+self-hosted runner that builds CI jobs rootless inside a disposable box. The
+candy lives in `charly.yml` at the repo root.
+
+Canonical files:
+
+- `charly.yml` — the `github-runner:` candy entity (description, `require`,
+  `distro`, `volume`, `env`, `env_accept`, `secret_accept`, `var`, `hook`,
+  `service`, `plan`) and its `skill:` entity.
+- `.github/workflows/tag-on-merge.yml` — CalVer tag + `CHANGELOG/` on merge.
+- `CHANGELOG/` — per-CalVer history.
+- `README.md` — user overview only; never agent guidance.
+
+## Load these skills first (R0)
+
+- `/charly-distros:github-runner` — the owning skill: candy properties, packages,
+  the token contract, the lifecycle hooks, and the org-runner routing playbook.
+  Load before editing, building, deploying, or troubleshooting this candy.
+- `/charly-distros:container-nesting` — the rootless nested podman/buildah/skopeo
+  stack the candy requires (`layer-container-nesting`).
+- `/charly-pod:pod` — the `kind: pod` / deploy schema reference (this candy is
+  composed into a box; tree-position nesting, volumes, ports).
+- `/charly-check:check` — the check/R10 framework: the `check:` step verbs and
+  `charly check run <bed>`.
+- `/charly-image:layer` — the candy authoring reference (`charly.yml` schema,
+  `plan:` step verbs, `env_accept` / `secret_accept`, lifecycle hooks).
+- `/charly-build:secrets` — the credential store backing `RUNNER_TOKEN`.
+- `/charly-internals:git-workflow` — before any git/PR action.
+
+## Build / validate / test
+
+- `charly box validate` at the repo root — the structural check: the manifest
+  must parse and validate at the installed charly.
+- The live R10 witness is a composing box's `check` bed; the candy's own `check:`
+  steps assert `config.sh` + `run.sh` presence, `config.sh --version` (proving the
+  `.NET` deps resolved), `skopeo`/`buildah`/`cosign`/`go` versions, the aarch64
+  qemu interpreter, rootless nested `podman`, the runner running as uid 1000, and
+  the `newuidmap` capability.
+- The merge gate is the **org-wide** `charly/pr-validator` (required check
+  `validate / validate`, defined in `opencharly/.github`); this repo has **no**
+  per-repo candy gate. Its only workflow file is
+  `.github/workflows/tag-on-merge.yml`.
+
+## Modify this repo
+
+- Edit the `github-runner:` candy entity in `charly.yml`; the `skill:` entity in
+  the same file is the owning skill's source — a candy change and its skill change
+  land together.
+- The runner version pin is the `RUNNER_VERSION` var; the registration logic is
+  the token-guarded `post_enable` / `pre_remove` hooks. Keep them token-guarded —
+  an empty `RUNNER_TOKEN` must stay a clean no-op for token-less beds.
+- `podman`/`buildah`/`skopeo`/`crun`/`fuse-overlayfs` come from
+  `layer-container-nesting`; do not redeclare them here (R3).
+- The `skill:` entity is the source for `/charly-distros:github-runner`; never
+  edit the generated `SKILL.md` — regenerate it.
+
+## Landing
+
+- PR-only. Every change lands through a pull request; the org-required
+  `charly/pr-validator` validates the diff and body and arms native auto-merge on
+  PASS. Direct pushes to `main` are blocked.
+- History lives in `CHANGELOG/` (written by `tag-on-merge` at merge time); the PR
+  body IS the changelog.
+- The authoritative rulebook is the umbrella `AGENTS.md` in
+  `opencharly/opencharly` and `charly/AGENTS.md` in the charly repo. Do not
+  restate its rules here.

README.md

@@ -1,6 +1,54 @@
 # pod-github-runner
 
-The `pod-github-runner` candy of the [opencharly/charly](https://github.com/opencharly/charly)
-candy library, as a standalone repo (the candy de-submodule cutover, kind-prefixed
-naming). The candy manifest lives at the repo root; the charly resolver fetches
-this repo at the pinned tag.
+The `github-runner` candy of the OpenCharly candy library, as a standalone repo
+(kind-prefixed naming). It ships a GitHub Actions self-hosted runner that builds
+CI jobs rootless inside a disposable box.
+
+## What it provides
+
+Installs the pinned `actions/runner` release (default `2.334.0`) under
+`${HOME}/actions-runner` (`config.sh` + `run.sh`, run as uid 1000) plus the CI
+toolchain — `jq`/`git`/`go`/`cosign`, `qemu-user-static` for aarch64 binfmt
+cross-builds, and the rootless nested container stack (`podman`/`buildah`/`skopeo`
+via `container-nesting`). The `.NET` runtime deps (`icu`/`krb5`/`openssl`/
+`libunwind`/`lttng-ust`) are declared explicitly because the runner's
+`installdependencies.sh` has no Arch branch.
+
+| Property | Value |
+|---|---|
+| Service | `github-runner` (`~/actions-runner/run.sh`, `restart: always`, uid 1000) |
+| Requires | `layer-supervisord`, `layer-container-nesting` |
+| Volume | `state` at `~/actions-runner` |
+| Env | `RUNNER_WORK_DIR=~/actions-runner/_work`, `RUNNER_GROUP=Default` |
+| env_accept | `RUNNER_ORG` — the org/user to register with |
+| secret_accept | `RUNNER_TOKEN` — the registration token (credential-store backed) |
+
+## Registration
+
+Registration is token-guarded. A deploy with `RUNNER_TOKEN` empty is a clean
+no-op (so a check bed brings the image up without registering); with a token,
+the `post_enable` hook runs `config.sh --unattended`, and `pre_remove`
+deregisters.
+
+```bash
+TOKEN=$(gh api -X POST /orgs/myorg/actions/runners/registration-token --jq .token)
+charly config <box> -e RUNNER_ORG=myorg -e RUNNER_TOKEN="$TOKEN"
+charly start <box>
+```
+
+## Layout
+
+- `charly.yml` — the `github-runner:` candy entity plus its `skill:` entity.
+- `.github/workflows/tag-on-merge.yml` — CalVer tag + `CHANGELOG/` on merge.
+- `CHANGELOG/` — per-CalVer history.
+- `README.md` — this user overview.
+
+## Related
+
+- Owning skill: `/charly-distros:github-runner` — the candy properties, the
+  packages, the token contract, the lifecycle hooks, and the org-runner routing
+  playbook.
+- `/charly-distros:container-nesting` — the rootless nested podman/buildah/skopeo
+  stack the candy requires.
+- [`opencharly/charly`](https://github.com/opencharly/charly) — the charly CLI and image builder
+- [`opencharly/opencharly`](https://github.com/opencharly/opencharly) — the umbrella