docs: add shared agent knowledgebase

2026-04-26 18:51:31 +02:00
parent fcf1b91224
commit e4a37bd705
13 changed files with 652 additions and 2 deletions
@@ -0,0 +1,72 @@
+# gutasktool architecture
+
+## Purpose
+
+`gutasktool` provides the `gutask` CLI for Glitch University task and agent operations.
+
+Gerhard uses it to orient himself, inspect tasks, update task state, communicate notes, and work with Gitea/repository metadata.
+
+## Canonical checkout
+
+The useful checkout is the sibling repository beside Agent0:
+
+```text
+../gutasktool
+```
+
+Inside Gerhard's container it is mounted at:
+
+```text
+/opt/gutasktool
+```
+
+Remote:
+
+```text
+ssh://git@ramanujan.glitch.university:2222/glitch-university/gutasktool.git
+```
+
+## Important command
+
+Gerhard orientation:
+
+```bash
+/opt/data/bin/gutask orient --agent "$AGENT_ID"
+```
+
+The `orient` command contacts the Glitch University API endpoint for agent orientation and prints a briefing prompt.
+
+## Identity and credentials
+
+The CLI should read operational credentials from environment variables, not from committed files:
+
+- `API_URL`
+- `CONTENT_API_KEY`
+- `AGENT_ID`
+- `AGENT_NAME`
+- `AGENT_PASSWORD`
+- `GITEA_TOKEN` if needed by commands that talk to Gitea APIs
+
+Top-level CLI flags may override environment values for one-off use.
+
+## Development rule
+
+When Gerhard fixes gutasktool:
+
+1. Work in `/opt/gutasktool`.
+2. Inspect `git status --short --branch` before changing files.
+3. Pull/rebase carefully before pushing.
+4. Avoid reading or committing `.env` or other credentials.
+5. Run syntax/help checks before commit.
+6. Commit with a clear conventional message.
+7. Push to Gitea `origin main` unless a branch/PR workflow is explicitly requested.
+
+## Known history
+
+The local checkout once diverged from Gitea with local orient support ahead of origin and remote work behind it. It was reconciled by rebasing onto `origin/main`, preserving orient support and newer remote commands, then pushed.
+
+Current good commit containing orientation support:
+
+```text
+9a4ef82 feat: add agent orientation support
+```