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.