internet_use_control/docs/outline/04-agent-runbook.md

Internet Use Control — Agent Runbook

Target: AI agents. Writing style: ASD-STE100 Simplified Technical English.

Before You Start

1. Read docs/outline/00-index.md. Inject only the file that you need.
2. Read AGENTS.md, section 11. Confirm the phase checklist and the status line.
3. Read README.md for the technical reference.
4. Work in /home/sam/paseo/projects/internet_use_control only.
5. Bound every Docker command with timeout, for example timeout 60 docker compose ps. Never run a Docker command without a bound.

Build and Test

There is no host Go toolchain. Use the cached builder image.

make test           # go test ./... in golang:1.25-alpine
make vet            # go vet ./...
make build          # build the container image

make test and make vet run the container as the current user. The module cache stays in .gocache/, which is gitignored. No root-owned file enters the repository.

Run and Restart

timeout 60 docker compose up -d --build   # start or update
timeout 60 docker compose restart control # restart the container
timeout 60 docker compose logs --tail=100 control
timeout 60 docker compose ps
curl -sS http://127.0.0.1:8791/health

The compose file starts the container webrestrict-control on port 8791. The image tag is webrestrict/control:0.7.0-phase9.

Verify the Behaviour

Target	Proves
make mqtt-verify	TLS, credentials and topic ACLs on a scratch broker.
make verify-phase8	An API lock reaches a device in under one second.
make verify-phase9	The Hub answers and the Apprise alerts deliver.

make mqtt-verify uses a scratch broker on 127.0.0.1:18883. It never touches the shared Mosquitto. The two verify-phase* targets read the broker credentials from deploy/mosquitto/clients.env.

Useful Subcommands

timeout 60 docker exec webrestrict-control /app/control rollup
timeout 60 docker exec webrestrict-control /app/control alerts --limit 10
timeout 60 docker exec webrestrict-control /app/control usage --day 2026-10-13 --detail
timeout 60 docker exec webrestrict-control /app/control mqtt-clients

Documentation Commands

# Render the Mermaid diagram.
timeout 120 mmdc -i docs/architecture.mmd -o docs/diagrams/architecture.png --scale 2 -b white

# Validate and deliver the Archify map.
node ~/.agents/skills/archify/bin/archify.mjs validate architecture \
  docs/archify/architecture.architecture.json --quality showcase --json
node ~/.agents/skills/archify/bin/archify.mjs deliver architecture \
  docs/archify/architecture.architecture.json docs/architecture-map.html \
  --quality showcase --json

# Publish docs/ to the maps site.
~/.agents/skills/project-docs/scripts/publish-maps.sh

The visual-check of docs/architecture-map.html reports a 1-pixel vertical overflow at 1440×900. All larger viewports pass. The delivered map passes the 9-check showcase profile with 0 errors.

Rules That Stop a Task

1. Never hard-delete a device or its history (AGENTS.md section 10, rule 10).
2. Only the Control Service publishes device config. Everything else writes to it over HTTP.
3. /ask is read-only. It writes nothing.
4. Do not change the router, Pi-hole or DNS. The project is device-side only.
5. The children's client never changes its own rules. It obeys and reports.
6. One commit and one push for a documentation change. Add the co-author trailer Co-Authored-By: Paperclip <noreply@paperclip.ing>.

Resume Steps

1. Read docs/outline/00-index.md, then docs/outline/01-system-overview.md.
2. Run git status and git log -n 5 --oneline.
3. Run make test.
4. Read AGENTS.md section 11. Phase 4 is the only unfinished phase.
5. Check the issue board before you start new work. Do not create tasks ad hoc.