Contribute

Operating modes

Autograph defines three modes that determine how the agent relates to the project and the engine.

Activation profiles

Each agent container declares a Docker Compose profile: the dev agent uses dev, the metalab agent uses metalab, and shared services like Phoenix are available to both.

env/.env.augr holds engine meta-configuration: the environment name, container CLI, Compose command and variant, network names, and the AUGR_NET_* corporate network block. Setup pre-fills its proxy and bypass values from the host shell without printing the proxy URL, which may contain credentials. This is distinct from per-package settings in env/dev/env.d/. For standalone Compose v1 selection and the known v2-only package-task limitation, see Compose runtimes.

Using metalab

# Launch the metalab agent
task augr:pkg:metalab:chat

# Or open a shell for manual work
task augr:pkg:metalab:shell

Both agents run simultaneously in separate containers with the full security model. They share Phoenix for observability, with sessions tagged by mode.

The metalab agent and the dev agent share the same Docker image but operate with inverted volume configurations: engine and packages are L1 (mutable) for metalab, while your project workspace is L2 (frozen context).

Safety model

Each source entity (engine submodule, West packages) has an observable state that determines what operations are safe. The system tracks these states and blocks destructive commands when entities are at risk.

Entity states

Resilience model

The dev agent and metalab agent run on independent networks with independent runtime state. If one breaks, the operator uses the other to inspect and recover. At least one agent must remain functional at all times during metalab contribution.

Run task augr:engine:diagnos to see the current state of every entity in the ecosystem. The report shows states, HEAD positions, dirty counts, local-only branches, agent health, and config freshness.

Updating the shared image

Both agents share one Docker image: the dev agent owns it, metalab consumes it. Update it in two steps so an agent is always available:

1. Rebuild and recreate the owner: task augr:pkg:agent:rebuild. Validate the dev agent still works.
2. Adopt the validated image on metalab: task augr:pkg:metalab:reup.

Note: task augr:build only aggregates and validates env configuration - it does not build images. Image builds happen inside task augr:up, or are forced per package with :rebuild (no-cache rebuild + recreate) and :reup (recreate on the current image, no rebuild).

The forge workflow

Forge is to metalab what "build" is to dev mode: the transition from working state to delivered artifact. The metalab agent produces changes in autograph sources; the operator forges them into upstream contributions.

Exchange zones

Each agent mode has a dedicated exchange directory for proposing changes to files it cannot modify directly (L2 read-only files). The agent writes to its exchange zone; the operator reviews and applies via cp.

Both zones follow the mirror path convention: proposed changes replicate the host-relative path structure so it is unambiguous which file is being replaced.

Operation guards

Destructive task commands check source entity states before running. If any entity is in an unsafe state, the command refuses to proceed. Guards apply to task commands only - direct git and west commands are the operator's responsibility.

Runtime snapshots

Before risky operations (infrastructure validation, lifecycle tests, teardown), checkpoint the runtime state so you can restore sessions, auth, and agent configuration if something breaks.

Manual git workflow

For direct contributions (without the metalab agent), follow the dedicated git flow.

1 Set up the remote

After task augr:install, West modules are in detached HEAD with a container-internal remote. Fix it:

cd engine/deps/modules/<package-name>
git remote -v                          # check current remote
git remote set-url origin <real-url>   # fix if needed
git fetch origin
git checkout -B main origin/main

2 Create a feature branch

git checkout -b feat/<Exx-slug>/<specialization>

# Make changes, then commit
git add -A && git commit -m '[Exx.Tyy] type: message'

# Push your branch
git push origin feat/<Exx-slug>/<specialization>

3 Apply merged changes

# For packages (West-managed)
task augr:update      # west update + env-collect
task augr:reup        # if compose/env changed

# For the engine (submodule)
git submodule update --remote engine
git add engine && git commit -m 'chore: update engine submodule'

Pitfalls

Key tasks