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