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

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

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

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

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