Documentation review: 30 PRs (#175–#267, June 2026) — staleness check

[onel]

Summary

Reviewed 30 merged PRs from the last 7 days (#175–#267) and 0 new releases against the current spec tree (docs/specs/). This is the first docs-agent run.

PRs reviewed

PR	Topic	Docs touched in PR?
#228	Per-instance cgroup resource limits	✅ ENVIRONMENT.md
#232	Cloud VM boot proofing in QEMU	✅ BUILD.md
#235	Caddy/acmedns hosted cert	✅ MALMO_NETWORK.md, ENVIRONMENT.md
#236	ACME DNS-01 wildcard cert	✅ MALMO_NETWORK.md
#243	nftables cloud-image toggling	✅ BUILD.md, ENVIRONMENT.md
#245	nftables cloud-image toggling (cont.)	✅ BUILD.md
#248	Cloud-image CI build lane	✅ BUILD.md
#249	Cloud-image lean check widening	✅ BUILD.md
#251	Cloud metadata egress blocking	✅ ENVIRONMENT.md
#252	First-boot seed ingestion	✅ ENVIRONMENT.md, FIRST_RUN.md
#254	Cloud on-ramp fix	✅ ENVIRONMENT.md
#256	Cloud-image egress blocking	✅ ENVIRONMENT.md
#257	Windmill catalog entry	progress doc only
#258	Managed MongoDB decline	✅ SERVICE_PROVISIONING.md, DECISIONS.md
#259	Host-agent slim build (strip godbus)	PR notes "no spec change needed"
#263	Postiz catalog entry	progress doc only
#264	Manifest config block	✅ APP_MANIFEST.md
#265	Manifest config block (cont.)	✅ APP_MANIFEST.md
#266	Setup secret URL-prefill	✅ DECISIONS.md
#267	Manifest config block (cont.)	✅ APP_MANIFEST.md, DASHBOARD.md, BRAIN_UI_PROTOCOL.md
#250	Unleash catalog entry	progress doc only
#233–#242, #244, #246–#247, #253, #255, #260–#262	Various code/CI/fixes	code-only or progress docs

Finding: docs are in good shape

Almost every PR that changed spec-worthy behavior already included the spec update in the same PR. The catalog additions (#257 Windmill, #263 Postiz, #250 Unleash) are progress-doc-only, which is correct — APP_STORE.md describes the catalog schema and uses PhotoPrism/Immich as examples, not an exhaustive app list.

One gap identified

APP_ISOLATION.md — "Resource limits" section could cross-reference hosted CPU capping (#228)

PR #228 updated ENVIRONMENT.md to describe the per-instance cgroup limit mechanism: memory is capped in both profiles; CPU is capped only in hosted. The APP_ISOLATION.md "Resource limits" section was not touched by #228, and it says:

CPU in particular is never capped — it's time-shared, so a CPU-hungry app simply runs slower and harms nothing; throttling it only makes it feel needlessly sluggish.

This is correct for the appliance profile (which the doc describes), and ENVIRONMENT.md already cross-references APP_ISOLATION.md # Resource limits. But APP_ISOLATION.md does not cross-reference back to ENVIRONMENT.md for the hosted profile's CPU capping. A reader of APP_ISOLATION.md alone would not know that hosted caps CPU.

Proposed fix: Add a one-line cross-reference note in APP_ISOLATION.md # Resource limits, near the "CPU is never capped" paragraph, pointing to ENVIRONMENT.md # Per-instance resource limits for the hosted profile's CPU capping behavior. No content rewrite — just a pointer.

Plan

On "go":

1. Create a branch docs/issue-NNN-resource-limits-xref
2. Add the cross-reference note to APP_ISOLATION.md
3. Open a PR referencing this issue
4. Record all reviewed PR numbers (M0 — build malmo-brain + malmo-ui images + bake into the QEMU image #175–manifest: config: block for user-supplied app configuration (#264) #267) and release tags (none) to docs-update-state.md

---

Reply go to proceed, or tell me to skip/adjust anything.

[onel]

/docs go

[onel]

The approved plan — add a cross-reference note in APP_ISOLATION.md # Resource limits pointing to ENVIRONMENT.md # Per-instance resource limits for the hosted profile's CPU capping — is already open as PR #287 (#287). That PR was opened from the earlier (now-deleted) issue #286 with the same plan; the diff is the exact one-line blockquote block this plan calls for.

Rather than open a duplicate, I'll leave PR #287 as the delivery for this plan. It is ready for review/merge.

— Docs Agent. Reply go to proceed, or /docs <what to change> to revise.