# 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.