Config & docs audit: compose env gaps, pinned defaults drift, and an 11-item docs-parity sweep (multi-day deep dive)

[TheAmericanMaker]

Disclosure: filed by an AI coding agent operating on behalf of James Sesler (TheAmericanMaker), sharing the results of a multi-day deep-dive audit of this codebase at d75821e0747d1a6a09c277ee14d14d0446f3b7a7.
The audit was produced with CodeCartographer, James's open-source audit tool (https://github.com/HuginnIndustries/CodeCartographer): it reconstructs a codebase's intent, runs mechanical and semantic defect scans, then forces every candidate finding through claim-by-claim verification (path-join and regex simulations, type cross-references) before it is reported. Three findings were corrected or withdrawn during verification, so everything below has been re-checked against the source rather than pattern-matched.

Severity tags are the auditor's assessment. Line refs are from the committed snapshot, not the worktree (see item 2 note).

1. [medium] Documented env vars are not forwarded by compose; an explicit 0 is silently ignored

Evidence: TASK_MEMORY_MB, TASK_CPUS, TASK_PIDS_LIMIT, PI_IMAGE are documented (README.md:89, docs/reference/configuration.md:46-49) but absent from both compose files' environment: blocks (grep-verified at the audited sha) — reachable only by hand-editing compose or the code defaults. And server/src/executors/index.ts:164-168: memoryMb: Number(process.env.TASK_MEMORY_MB) || 2048 (and siblings) — an explicit 0 silently falls back to the default with no diagnostic.

Proposed fix: forward the four vars in the compose env blocks; parse with explicit validation (reject non-numeric/negative; treat 0 deliberately, never as "unset").

2. [medium] Portainer compose pins PI_* defaults; .env.example diverges from the main compose

Evidence: docker-compose.portainer.yml:21-23 hard-codes PI_PROVIDER=openrouter, PI_MODEL=anthropic/claude-sonnet-5, PI_THINKING_LEVEL=medium, overriding pi's own settings.json inheritance — contradicting the main compose's deliberately-empty-with-comment design (docker-compose.yml:23-25, docs/guide/deploying.md:110-113). .env.example:13-14 ships two of the same pins (PI_PROVIDER=openrouter, PI_MODEL=anthropic/claude-sonnet-5; no PI_THINKING_LEVEL entry at the audited sha), so the README quick-start (cp .env.example .env) produces pinned defaults the compose comments say should stay empty.

Note: a local (uncommitted) copy of docker-compose.yml/.env.example adds user:/group_add: and PUID/PGID/DOCKER_GID entries; the line numbers above are from the committed files at the audited sha.

Impact: Portainer and quick-start users silently lose per-install provider/model configuration from pi's settings.json.

Proposed fix: leave the PI_* entries empty in the portainer compose and .env.example (with the "overrides only" comment), or explicitly document the override as intended.

3. [low] Documentation drift and gaps (11 items)

Evidence — each item: doc location → code reality, verified at the audited sha:

1. BIN_DIR (server/src/index.ts:56) and PI_CODING_AGENT_DIR (server/src/pi-settings.ts:12-13) are honored but missing from docs/reference/configuration.md's env table.
2. README.md:87 claims PI_MODEL defaults to anthropic/claude-sonnet-5; the code default is "" (server/src/db.ts:558 — only PI_PROVIDER falls back to openrouter).
3. docs/reference/api.md:111: "GET starts pi if it is not already up" — the handler deliberately does not (index.ts:339-366; the comment explains the 600ms-boot rationale).
4. api.md omits implemented route families: /api/agent/setup (GET/POST), /api/agent/files/:name (PUT), /api/agent/sessions (POST), plus the people/audit/tool-rules, mcp, skills, and routines routers (index.ts:223-253, 486-491).
5. The 20k cold-load SSE replay cap (index.ts:54, 521-525) is undocumented; api.md:83 says the endpoint "replays everything after since".
6. channels/README.md:116-122 claims channel start() "is currently defined but never invoked"; the server boots a working supervisor (index.ts:589-592) and docs/channels/index.md describes it as operational — the two channel docs contradict each other.
7. docs/reference/architecture.md:99 says only the pithagoras.channel marker qualifies a package; the loader also accepts the pithagoras-channel- name prefix (server/src/channels/loader.ts:95).
8. LLAMA_BASE_URL (docker-compose.yml:29, .env.example:19) has no consumer in this repo's source (grep-verified); it is forwarded into the pi container, where pi's llama extension consumes it (per upstream 0.82.x dist/extensions/llama/provider.js — the 0.80.10 install lacks that file, so verify against the resolved package before citing). Absent from configuration.md's env table; document it as a pi-extension var, not a portal var.
9. index.ts:585-586 comment says a routine due while down "does not fire retroactively" — true for recurring, but one-offs deliberately catch up (server/src/routines/supervisor.ts:90-97). Comment-only; correct if touched.
10. Audit endpoint caps responses at 1000 (server/src/api/people.ts:54) while retention keeps 2000 (server/src/db.ts:731 AUDIT_KEEP); the oldest retained half is never displayable.
11. api.md's event-type list omits queue_update (ephemeral; session-manager.ts:53-57).

Proposed fix: one docs-parity PR — update api.md (routes, event list, config GET, replay cap), configuration.md (env table incl. BIN_DIR, PI_CODING_AGENT_DIR, LLAMA_BASE_URL), README.md (model default), channels/README.md (delete the stale status paragraph), architecture.md (marker rule), the audit-range note; fix the boot comment.

Already tracked upstream (no new issue filed)

The WORKSPACE_ROOT double-read (server/src/index.ts:42-44, where process.env.WORKSPACE_ROOT || process.env.WORKSPACE_ROOT || "/workspaces" never consults the legacy WORKSPACES_DIR) is already upstream issue #5, with the same diagnosis and fix this audit reached independently. This report confirms it and adds two corroborating details: .env.example documents WORKSPACES_DIR (:5-8 region), and the compose files mask the bug because the container mounts workspaces at /workspaces anyway — so it only bites outside Docker.

---

Reproducing

All refs were verified at d75821e: the four TASK_*/PI_IMAGE vars appear in neither compose file's environment block (they are only read in server/src/executors/index.ts); LLAMA_BASE_URL appears only in docker-compose.yml:29 and .env.example:19, with no consumer in source; the double-read is at index.ts:43.