Phase 10: publish the documentation set + tick AGENTS.md 9 of 10

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>
This commit is contained in:
2026-10-14 12:13:21 +11:00
parent 5a9e56bb1f
commit eb300b6701
12 changed files with 14593 additions and 11 deletions

View File

@@ -0,0 +1,100 @@
# 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.