Sam Rolfe
eb300b6701
Phase 10 (the last phase of this project) is the project-docs pass. Update the Gitea README, add the Mermaid source and rendered PNG, build the interactive Archify map, add the Vikunja board tasks, and write the Outline AI-context collection in Simplified Technical English. Deliverables: - README.md: status header, Phase 4 gap statement, "Architecture" section with embedded Mermaid + image + Archify link, "Documentation set" table, an explicit two-plane MQTT section (1883 plain+anonymous, 8883 TLS+ACLs), and the Android client's Usage Access and VpnService paths. - AGENTS.md section 11: tick Phase 10, leave Phase 4 unticked, status line now "9 of 10 done - only Phase 4 outstanding". - docs/architecture.mmd + docs/diagrams/architecture.png (mmdc). - docs/archify/architecture.architecture.json + docs/architecture-map.html (Archify, showcase, 9/9 checks, 0 errors). - docs/outline/00-index.md .. 04-agent-runbook.md (STE). - docs/vikunja-tasks.json (Vikunja project "Internet Use Control", id 20). - Obsidian note written to 010 inbox on .27; the obsidian-sorter proposed a folder and waits for the vault owner's approval. Phase 4 (Python Windows computer client) is deliberately deferred and is NOT built. Every document says so. Co-Authored-By: Paperclip <noreply@paperclip.ing>
101 lines
3.8 KiB
Markdown
101 lines
3.8 KiB
Markdown
# 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.
|