docs: add shared agent knowledgebase

shared/knowledge/runbooks/gutasktool-development.md

@@ -0,0 +1,97 @@
+# Runbook: gutasktool development and push
+
+Use this when an agent must inspect, fix, or push `gutasktool`.
+
+## Location
+
+Host:
+
+```text
+../gutasktool
+```
+
+Gerhard container:
+
+```text
+/opt/gutasktool
+```
+
+## Start clean
+
+```bash
+cd /opt/gutasktool
+git fetch origin
+git status --short --branch --untracked-files=all
+git log --oneline --decorate --max-count=10 --all
+```
+
+If local branch is behind origin, pull or rebase before editing.
+
+If local branch is ahead and behind, inspect the local commits before rebasing:
+
+```bash
+git log --oneline --decorate --graph --max-count=20 --all
+git diff --stat origin/main...HEAD
+git diff --name-status origin/main...HEAD
+```
+
+Create a backup branch before risky reconciliation:
+
+```bash
+git branch backup/local-before-rebase-$(date +%Y%m%d-%H%M%S)
+git rebase origin/main
+```
+
+Resolve conflicts deliberately. Do not discard local work unless the human asks.
+
+## Edit
+
+Make the smallest change that fixes the problem.
+
+Avoid secrets. Do not read `.env` unless explicitly needed and approved.
+
+## Verify
+
+At minimum:
+
+```bash
+python3 -m py_compile gutasktool/cli.py
+git diff --check
+```
+
+If `requests` is missing on the host, create a temporary venv:
+
+```bash
+tmpvenv=$(mktemp -d /tmp/gutasktool-venv.XXXXXX)
+python3 -m venv "$tmpvenv"
+"$tmpvenv/bin/python" -m pip install -q 'requests>=2.28'
+PYTHONPATH=. "$tmpvenv/bin/python" -m py_compile gutasktool/cli.py
+PYTHONPATH=. "$tmpvenv/bin/python" -c 'import sys; from gutasktool.cli import main; sys.argv=["gutask","orient","--help"]; main()'
+```
+
+For orientation support, verify help and env behavior:
+
+```bash
+PYTHONPATH=. "$tmpvenv/bin/python" -c 'import sys; from gutasktool.cli import main; sys.argv=["gutask","orient","--help"]; main()'
+AGENT_ID=123 API_URL=http://example.invalid CONTENT_API_KEY=dummy PYTHONPATH=. "$tmpvenv/bin/python" -c 'import sys; from gutasktool.cli import main; sys.argv=["gutask","orient"]; main()'
+```
+
+The second command should attempt a connection using env-provided `AGENT_ID`, not fail with missing agent identity.
+
+## Commit and push
+
+```bash
+git add <changed-files>
+git commit -m "feat: clear description"
+git push origin main
+```
+
+After push:
+
+```bash
+git fetch origin
+git status --short --branch
+git log --oneline --decorate --max-count=3
+```
+
+The branch should show no ahead/behind divergence.

shared/knowledge/runbooks/start-gerhard.md

@@ -0,0 +1,75 @@
+# Runbook: start Gerhard on Omega13
+
+## Preconditions
+
+Expected side-by-side layout:
+
+```text
+~/Projects/Agent0
+~/Projects/gutasktool
+```
+
+Local `.env` exists in `Agent0` and contains non-committed credentials:
+
+- `API_URL`
+- `CONTENT_API_KEY`
+- `AGENT_ID`
+- `AGENT_NAME`
+- `AGENT_PASSWORD`
+- model provider keys as needed
+
+SSH config/keys on the host can push to Gitea if Gerhard is expected to push repository changes.
+
+## Pull latest
+
+```bash
+cd ~/Projects/Agent0
+git pull --ff-only
+cd ../gutasktool
+git pull --ff-only
+```
+
+## Start Gerhard first
+
+```bash
+cd ~/Projects/Agent0
+docker compose up -d gerhard gerhard-dashboard
+```
+
+## Validate
+
+```bash
+docker compose ps gerhard gerhard-dashboard
+docker logs gerhard --tail=100
+docker logs gerhard-dashboard --tail=100
+```
+
+Check gutask wrapper:
+
+```bash
+docker compose exec gerhard /opt/data/bin/gutask --help
+docker compose exec gerhard /opt/data/bin/gutask orient --agent "$AGENT_ID"
+```
+
+Check shared knowledge mount:
+
+```bash
+docker compose exec gerhard test -f /knowledge/README.md
+```
+
+## Dashboard
+
+Gerhard dashboard should be reachable from Omega13 at:
+
+```text
+http://localhost:50007
+```
+
+## Then tunnel and rest
+
+Only after Gerhard is stable:
+
+```bash
+docker compose up -d glitch-tunnel
+docker compose up -d
+```