feat: add tokenless Tobserver change skill

2026-07-24 20:22:01 +07:00 · 2026-07-24 20:22:01 +07:00 · 886a885355
commit 886a885355
parent 8cc510b2c7
6 changed files with 1364 additions and 0 deletions
--- a/tobserver-change/references/setup.md
+++ b/tobserver-change/references/setup.md
@ -0,0 +1,100 @@
+# Tobserver Agent Setup
+
+Use this reference before first use and whenever SSH authentication, branch protection, AGit submission, or helper installation changes.
+
+## Security model
+
+The same Codeberg account, `oibot`, creates AGit pull requests and later performs a human web merge. Safety therefore depends on two separate capabilities:
+
+- SSH may submit AGit changes but protected `main` rejects direct, force, and deletion pushes.
+- The agent has no write-capable Codeberg API token or authenticated browser session. Only the human web session merges or changes repository settings.
+
+This model does not provide separate agent attribution or independently enforceable approval by another account.
+
+## Protect `main`
+
+In `oibot/Tobserver` → **Settings** → **Branches**, create an exact rule for `main` that:
+
+- forbids direct pushes for everyone, including `oibot` and repository owners;
+- has no user, team, deploy-key, or administrator push bypass;
+- forbids force pushes and branch deletion;
+- requires pull-request merging;
+- retains required checks and conversation resolution when configured.
+
+Inspect the saved rule in the UI. Do not test protection by making a potentially successful push to Tobserver `main`; use a disposable repository for a push-level test.
+
+## Configure the personal SSH identity
+
+Normal Codeberg remotes must select the personal key explicitly even if another key is loaded:
+
+```sshconfig
+Host codeberg.org
+  HostName codeberg.org
+  User git
+  IdentityFile ~/.ssh/id_ed25519
+  IdentitiesOnly yes
+```
+
+Verify without pushing:
+
+```sh
+ssh -T git@codeberg.org
+```
+
+Expected identity: `oibot`.
+
+## Install from the Agent Skills catalog
+
+Pin `https://codeberg.org/oibot/agent-skills.git` as a non-flake Nix input. Load `create-skill` and `tobserver-change` from that pinned source.
+
+Expose the helper on `PATH` by packaging the canonical bundled file `tobserver-change/scripts/tobserver-agent`; do not keep a second editable helper copy in dotfiles. Provide these runtime commands:
+
+- Bash
+- Git and OpenSSH
+- curl
+- jq
+- Nix
+- nixpkgs-fmt
+- Gitleaks
+- standard core utilities including `base64`
+
+Run after installation:
+
+```sh
+tobserver-agent --help
+```
+
+## Confirm tokenless operation
+
+The helper may perform unauthenticated `GET` requests to the public API under:
+
+```text
+https://codeberg.org/api/v1/repos/oibot/Tobserver
+```
+
+It must not read a Keychain Codeberg token, send an authorization header, call a write API, approve, or merge.
+
+AGit submissions use only:
+
+```text
+ssh://git@codeberg.org/oibot/Tobserver.git
+HEAD:refs/for/main/tobserver-agent-<unique-topic>
+```
+
+## Retire `oibot-agent`
+
+Retire old credentials only after the catalog-backed helper successfully creates and linearly revises one unmerged test PR:
+
+1. Confirm no open PR or active workspace still depends on `oibot-agent`.
+2. Remove the `codeberg-tobserver-agent` SSH alias.
+3. Unload the bot key with `ssh-add -d ~/.ssh/oibot-agent`.
+4. Revoke the bot API token and remove its macOS Keychain entry.
+5. Remove the bot SSH key and repository access in Codeberg.
+6. Archive or delete the account only after confirming it owns no required repository or audit artifact.
+7. Delete local bot key files only after explicit confirmation and any desired backup.
+
+Do not rewrite historical commits or PRs to erase the old account name.
+
+## Recovery
+
+Until the new workflow passes end to end, keep old credentials available but do not load the bot key globally. If cutover fails, restore the previous pinned skill revision; never weaken `main` protection as a rollback shortcut.