Comment destination map #61

New Issue

2026-09-24T19:08:23Z

haylan commented

2026-09-24 19:08:23 +00:00

Part of #55

Question

For every comment block in docker-compose.yml, .env.example and scripts/: which doc section it moves to, and what stays in code (pointer / one-line inline warning / nothing). AFK draft, then user review.

Part of #55 ## Question For every comment block in docker-compose.yml, .env.example and scripts/: which doc section it moves to, and what stays in code (pointer / one-line inline warning / nothing). AFK draft, then user review.

haylan added the wayfinder:task label 2026-09-24 19:08:23 +00:00

haylan added a new dependency 2026-09-24 19:08:33 +00:00

#60 Target doc structure

haylan referenced this issue

2026-09-24 19:08:35 +00:00

Docs cleanup: restructure, move code comments into docs, remove image generation #55

haylan referenced this issue

2026-09-24 19:10:10 +00:00

Removal inventory: image generation and Open WebUI #58

haylan self-assigned this 2026-09-24 19:33:37 +00:00

haylan commented

2026-09-24 19:35:08 +00:00

Resolution — comment destination map

Legend for Stays in code: ptr = one-line # see docs/<file>.md#<section> · warn = one-line inline warning + ptr (data-loss/security carve-out) · — = nothing.
Blocks for removed components (ComfyUI, downloader-comfyui, Open WebUI, Lazytainer, neo4j, switch-model.sh) are deleted with their code and aren't listed per line.

docker-compose.yml

Service → comment	Moves to	Stays in code
llama-server → `group_add` numeric GIDs	architecture.md#gpu-access	ptr
llama-server → `GPU_MAX_HW_QUEUES` / ROCm#5706	architecture.md#gpu-access	ptr
llama-server → `--cache-reuse 256` rationale	architecture.md#llama-server	ptr
llama-server → "no published host port"	network-access.md#backends	ptr
llama-server → lazytainer labels	deleted (Lazytainer removed)	—
qwen-classifier → header (why, CPU-only attempt, context caps, VRAM/flash-attn, `--reasoning off`)	architecture.md#qwen-classifier	ptr
downloader → one-off/`test -f`/named volume, `user: root`	operations.md#model-downloads	ptr
downloader-classifier → "same pattern"	covered by the section above	—
omniroute → header (replaced LiteLLM, provider connections in dashboard)	gateway.md#provider-connections (LiteLLM history dropped)	ptr
omniroute → split-port comment	network-access.md#gateway	—
omniroute → `OMNIROUTE_ALLOW_*_PROVIDER_URLS` (SSRF guard relaxed)	gateway.md#provider-connections	warn (security)
omniroute → `OMNIROUTE_WS_BRIDGE_SECRET` required	operations.md#secrets	—
omniroute → `OMNIROUTE_MEMORY_MB`, `mem_limit`	architecture.md#omniroute	ptr
omniroute → `STREAM_IDLE_TIMEOUT_MS`, `REQUEST_TIMEOUT_MS`	gateway.md#timeouts	ptr (one for both)
omniroute → `extra_hosts` search.home (stale LiteLLM ref)	gateway.md#web-search	ptr
omniroute → `stop_grace_period` SQLite WAL	architecture.md#omniroute	warn (data loss if shortened)
omniroute → healthcheck TCP probe	architecture.md#omniroute	ptr
qdrant → header (dead `docs/agents/...` link)	architecture.md#qdrant	ptr

.env.example

Key / block → comment	Moves to	Stays in code
File header (copy / update.sh fills it)	operations.md#env-sync	ptr
`LLAMA_GPU_LAYERS` (offload, mmap, MoE flags)	architecture.md#llama-server	ptr
`LLAMA_CTX_SIZE` (VRAM math)	architecture.md#llama-server	ptr
`LLAMA_PARALLEL` (slots, queueing, per-slot context)	architecture.md#llama-server	ptr
`LLAMA_CLASSIFIER_MODEL_FILE`	architecture.md#qwen-classifier	ptr
`SEARXNG_LAN_IP`	gateway.md#web-search	"auto-filled" marker (R2) + ptr
OmniRoute ports	network-access.md#gateway	ptr
OmniRoute timeouts	gateway.md#timeouts	ptr
OmniRoute secrets block (password, JWT, API key secret, salts, WS bridge)	operations.md#secrets	"auto-filled" marker (R2) + ptr
`OMNIROUTE_STORAGE_ENCRYPTION_KEY`	operations.md#secrets	warn (never change after first run)
Per-workload keys note	gateway.md#api-keys	—
`HOST_VIDEO_GID` / `HOST_RENDER_GID` (ComfyUI header dropped)	architecture.md#gpu-access	"auto-filled" marker (R2) + ptr

scripts/update.sh

Section → comment	Moves to	Stays in code
File header (purpose, sync/conflict/`--force`, what's never touched, no rollback)	operations.md	2 lines: purpose + ptr
`git pull` must run first (self-update race)	operations.md#self-update	warn (R3)
gum vendoring + plain-bash fallback	operations.md#gum	ptr
Conflict-collection loop / `set_if_blank` mechanics	operations.md#env-sync	—
Secrets block (incl. storage-key repeat)	operations.md#secrets	— (warning lives in .env.example)
`SEARXNG_LAN_IP` resolution	gateway.md#web-search	ptr
GID resolution	architecture.md#gpu-access	ptr
Key-minting ponytail (#37)	gateway.md#api-keys	—

Review decisions (confirmed by user)

R1 — ponytail: markers are converted like any other comment (Q2(b)); no marker is kept.
R2 — keys auto-filled by update.sh keep a short inline "auto-filled by update.sh — leave blank" marker, because it's an instruction for whoever edits .env.
R3 — the inline-warning carve-out also covers edits that break the script or stack (e.g. git pull must stay first).

## Resolution — comment destination map Legend for **Stays in code**: **ptr** = one-line `# see docs/<file>.md#<section>` · **warn** = one-line inline warning + ptr (data-loss/security carve-out) · **—** = nothing. Blocks for removed components (ComfyUI, downloader-comfyui, Open WebUI, Lazytainer, neo4j, switch-model.sh) are deleted with their code and aren't listed per line. ### docker-compose.yml | Service → comment | Moves to | Stays in code | |---|---|---| | llama-server → `group_add` numeric GIDs | architecture.md#gpu-access | ptr | | llama-server → `GPU_MAX_HW_QUEUES` / ROCm#5706 | architecture.md#gpu-access | ptr | | llama-server → `--cache-reuse 256` rationale | architecture.md#llama-server | ptr | | llama-server → "no published host port" | network-access.md#backends | ptr | | llama-server → lazytainer labels | deleted (Lazytainer removed) | — | | qwen-classifier → header (why, CPU-only attempt, context caps, VRAM/flash-attn, `--reasoning off`) | architecture.md#qwen-classifier | ptr | | downloader → one-off/`test -f`/named volume, `user: root` | operations.md#model-downloads | ptr | | downloader-classifier → "same pattern" | covered by the section above | — | | omniroute → header (replaced LiteLLM, provider connections in dashboard) | gateway.md#provider-connections (LiteLLM history dropped) | ptr | | omniroute → split-port comment | network-access.md#gateway | — | | omniroute → `OMNIROUTE_ALLOW_*_PROVIDER_URLS` (SSRF guard relaxed) | gateway.md#provider-connections | **warn** (security) | | omniroute → `OMNIROUTE_WS_BRIDGE_SECRET` required | operations.md#secrets | — | | omniroute → `OMNIROUTE_MEMORY_MB`, `mem_limit` | architecture.md#omniroute | ptr | | omniroute → `STREAM_IDLE_TIMEOUT_MS`, `REQUEST_TIMEOUT_MS` | gateway.md#timeouts | ptr (one for both) | | omniroute → `extra_hosts` search.home (stale LiteLLM ref) | gateway.md#web-search | ptr | | omniroute → `stop_grace_period` SQLite WAL | architecture.md#omniroute | **warn** (data loss if shortened) | | omniroute → healthcheck TCP probe | architecture.md#omniroute | ptr | | qdrant → header (dead `docs/agents/...` link) | architecture.md#qdrant | ptr | ### .env.example | Key / block → comment | Moves to | Stays in code | |---|---|---| | File header (copy / update.sh fills it) | operations.md#env-sync | ptr | | `LLAMA_GPU_LAYERS` (offload, mmap, MoE flags) | architecture.md#llama-server | ptr | | `LLAMA_CTX_SIZE` (VRAM math) | architecture.md#llama-server | ptr | | `LLAMA_PARALLEL` (slots, queueing, per-slot context) | architecture.md#llama-server | ptr | | `LLAMA_CLASSIFIER_MODEL_FILE` | architecture.md#qwen-classifier | ptr | | `SEARXNG_LAN_IP` | gateway.md#web-search | "auto-filled" marker (R2) + ptr | | OmniRoute ports | network-access.md#gateway | ptr | | OmniRoute timeouts | gateway.md#timeouts | ptr | | OmniRoute secrets block (password, JWT, API key secret, salts, WS bridge) | operations.md#secrets | "auto-filled" marker (R2) + ptr | | `OMNIROUTE_STORAGE_ENCRYPTION_KEY` | operations.md#secrets | **warn** (never change after first run) | | Per-workload keys note | gateway.md#api-keys | — | | `HOST_VIDEO_GID` / `HOST_RENDER_GID` (ComfyUI header dropped) | architecture.md#gpu-access | "auto-filled" marker (R2) + ptr | ### scripts/update.sh | Section → comment | Moves to | Stays in code | |---|---|---| | File header (purpose, sync/conflict/`--force`, what's never touched, no rollback) | operations.md | 2 lines: purpose + ptr | | `git pull` must run first (self-update race) | operations.md#self-update | **warn** (R3) | | gum vendoring + plain-bash fallback | operations.md#gum | ptr | | Conflict-collection loop / `set_if_blank` mechanics | operations.md#env-sync | — | | Secrets block (incl. storage-key repeat) | operations.md#secrets | — (warning lives in .env.example) | | `SEARXNG_LAN_IP` resolution | gateway.md#web-search | ptr | | GID resolution | architecture.md#gpu-access | ptr | | Key-minting ponytail (#37) | gateway.md#api-keys | — | ### Review decisions (confirmed by user) - **R1** — `ponytail:` markers are converted like any other comment (Q2(b)); no marker is kept. - **R2** — keys auto-filled by `update.sh` keep a short inline "auto-filled by update.sh — leave blank" marker, because it's an instruction for whoever edits `.env`. - **R3** — the inline-warning carve-out also covers edits that break the script or stack (e.g. `git pull` must stay first).

haylan closed this issue

2026-09-24 19:35:09 +00:00

haylan referenced this issue

2026-09-24 19:41:49 +00:00

Execution hand-off checklist #64

haylan referenced this issue from a commit

2026-09-24 19:52:48 +00:00

chore: move code comments into docs, leave one-line pointers

haylan referenced this issue

2026-09-24 19:53:03 +00:00

Docs cleanup: restructure, move code comments into docs, remove image generation #65

Sign in to join this conversation.