Hermes & Sam 5c5df32101 Populate layered-soul: identity, memories, skills, plan (Hermes & Sam)

- SOUL.md: full agent identity, operating principles, voice
- IDENTITY.md: runtime identity, hosts, boundaries
- USER.md: operator context imported from hermes-soul
- AGENTS.md: actual operating rules, infrastructure, quick reference
- memories/curated/: 5 topics (tailscale, forgejo, agents, projects, vaultwarden)
- skills/: 9 cross-harness skills imported from hermes-soul after review
- docs/PLAN-CONFIGURE-PRIVATE-REPO.md: configuration plan
- Validate: passes clean

2026-06-14 00:21:26 +02:00

3.1 KiB

Raw Blame History

Agent Onboarding

Full workflow for adding a new agent to a self-hosted Forgejo instance.

Prerequisites

Admin API token with write:admin scope (user creation, key registration)
For collaborator management: write:repository scope OR web UI access
Forgejo API at https://<forgejo>/api/v1
SSH port is often non-standard (e.g. 2222)

New Agent Onboarding (full workflow)

When adding a new agent to the Forgejo matrix:

1. Create user (admin API)

curl -s -X POST "https://<forgejo>/api/v1/admin/users" \
  -H "Authorization: token <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"username":"<username>","email":"<email>","password":"<random>","must_change_password":false,"send_notify":false}'

2. Register SSH key (admin API)

curl -s -X POST "https://<forgejo>/api/v1/admin/users/<username>/keys" \
  -H "Authorization: token <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"key":"<public-key>","title":"<username>","read_only":false}'

3. Add collaborator on repos

Admin API for collaborators requires write:repository scope (not write:admin). If the admin token lacks it, use web UI:

# API (if token has write:repository)
curl -X PUT "https://<forgejo>/api/v1/repos/<owner>/<repo>/collaborators/<username>" \
  -H "Authorization: token <token-with-repo-scope>" \
  -H "Content-Type: application/json" \
  -d '{"permission":"write"}'

Web UI fallback: <forgejo>/<owner>/<repo>/settings/collaboration → Add Collaborator → select user → Write.

4. Update AGENTS.md

Add the new agent to the machine-user permissions table in the repo's AGENTS.md and FORGEJO-SETUP.md.

5. Agent verifies

ssh -T git@<forgejo>
# Expected: "Hi there, <username>!"
git push origin HEAD:refs/heads/<username>-push-test  # create then delete

Browser vs SSH-only agent users

If an agent needs web UI access (Hermes for PR review), give a real password, untick must_change_password. SSH-only agents (Claude, Codex) get random passwords.

Pitfalls

SSH key != repo permission. After registering a key and adding a user, the agent still needs explicit collaborator write access on each repo.
Ask before setting read vs write. Don't assume code editors are read-only or validators are write-only. Ask the operator what the agent's role is.
Admin token scope gaps: write:admin handles users and keys but NOT repo collaborators (needs write:repository), NOT branch protection API (403 — web UI only), NOT PR creation (needs write:repository), NOT reading SSH keys (GET /user/keys needs read:user), NOT listing collaborators (GET /repos/.../collaborators needs read:repository). Bottom line: admin scope is narrow — use the right token per task.
Token immutability: Forgejo tokens cannot be edited. Delete and recreate to change scopes. Keep admin tokens short-lived: generate → use → delete. Stash 1-2 days max for stabilization.
Org vs user namespace: if admin user clawdie exists, an org named clawdie cannot. User-namespace repos are functionally identical when per-agent SSH keys provide the audit trail.

3.1 KiB Raw Blame History