haylan/LLM-Server
1
0 Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity

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

New Issue
Closed
opened 2026-09-24 19:08:02 +00:00 by haylan · 2 comments
haylan commented 2026-09-24 19:08:02 +00:00
Owner
Copy link
Copy source

Destination

A complete, decided cleanup plan for the docs/cleanup-and-restructure branch: target doc structure, where every existing code comment ends up, what gets deleted (image generation, Open WebUI, stale docs), which research docs are marked superseded, and the rules every doc follows — precise enough that one execution pass can carry it out without new decisions.

Notes

  • Planning only — tickets produce decisions, not the edits. Execution happens afterwards in one pass on docs/cleanup-and-restructure.
  • Source is the truth. Every doc opens with a Source of truth line linking the file (and service/key name — never line numbers). Docs explain why; they name keys/flags but never restate values. If doc and source disagree, the source wins.
  • Comments → docs. Explanatory comments in docker-compose.yml, .env.example, scripts/ move into docs; the code keeps a one-line # see docs/<file>.md#<section> pointer where a reader needs it. Exception: warnings about data loss, security, or edits that break the stack/script stay inline as one line + pointer; keys auto-filled by update.sh keep a short "auto-filled — leave blank" marker. ponytail: markers are converted like any other comment.
  • Removed from the stack: ComfyUI, Qwen-Image, downloader-comfyui, scripts/switch-model.sh, Open WebUI, Lazytainer, neo4j. qdrant becomes loopback-only (see Intent vs. source).
  • docs/research/ is kept verbatim (history) behind an index marking each doc current / superseded-by; the two image-generation research docs are deleted.
  • Keep docs/server-planing.md. Keep AGENTS.md and QWEN.md stubs (another harness reads QWEN.md).
  • Use terms as defined in CONTEXT.md once it exists.
  • Skills: /grilling + /domain-modeling for grilling tickets; /writing-for-agents for the agent guide.

Tickets

  • Audit: contradictions and duplicates across docs and code comments (#56)
  • Research-doc index: current vs. superseded (#57)
  • Removal inventory: image generation and Open WebUI (#58)
  • Glossary: pin down domain terms in CONTEXT.md (#59)
  • Target doc structure (#60)
  • Comment destination map (#61)
  • Agent guide: writing docs and extending the glossary (#62)
  • Execution hand-off checklist (#64)
  • Intent vs. source: fix the config or fix the doc? (#63)

Decisions so far

  • Execution hand-off checklist — 7 phases (removals → source → docs → comments → agent guide → done-check/PR → server deploy by user), each pointing at its deciding ticket. Map complete — ready to execute.
  • Agent guide: writing docs and extending the glossary — docs/agents/writing-docs.md (6 rules + done-check) behind a CLAUDE.md pointer; new-term procedure goes into domain.md.
  • Comment destination map — every comment block in compose, .env.example, update.sh mapped to a doc section with pointer / inline warning / nothing; carve-out widened to breakage warnings + auto-filled markers.
  • Target doc structure — README (intro/quickstart/index) + architecture, gateway, network-access, operations, coding-cli-setup, research index; request-priority doc moves to research; both build plans labelled background research.
  • Intent vs. source: fix the config or fix the doc? — dashboard stays LAN-published (docs fixed, not internet-routed); neo4j and Lazytainer removed; qdrant bound to loopback.
  • Glossary: pin down domain terms in CONTEXT.md — CONTEXT.md drafted on the branch: Gateway, Workload, API key, Backend, Provider connection, Main/Classifier model, Slot, Server; no service renames.
  • Audit: contradictions and duplicates across docs and code comments — stale OMNIROUTE_PORT:-4000 everywhere, dashboard port wrongly called unpublished, lazytainer presented as working, classifier VRAM story contradicts itself; six duplicate clusters (GID rationale, classifier, per-slot ctx, key minting, timeouts, LiteLLM history).
  • Research-doc index: current vs. superseded — 15 current, 9 superseded (mostly LiteLLM-era → OmniRoute), 2 image-gen docs deleted; several inbound links need retargeting; flags a research doc calling server-planing.md superseded.
  • Removal inventory: image generation and Open WebUI — per-file removal checklist; GID vars, gum and scripts/vendor stay (still used); server-side leftovers (volumes, dashboard provider/key, proxy routes) listed as manual steps.

Not yet specified

Out of scope

  • Triaging the rest of the issue tracker. Obsolete maps/tickets (LiteLLM → OmniRoute migration, LiteLLM search/knowledgebase, the two "Verify … on the real R9700 box" tickets, the image-generation map and its ComfyUI ticket) were closed while charting this map.
## Destination A complete, decided cleanup plan for the `docs/cleanup-and-restructure` branch: target doc structure, where every existing code comment ends up, what gets deleted (image generation, Open WebUI, stale docs), which research docs are marked superseded, and the rules every doc follows — precise enough that one execution pass can carry it out without new decisions. ## Notes - **Planning only** — tickets produce decisions, not the edits. Execution happens afterwards in one pass on `docs/cleanup-and-restructure`. - **Source is the truth.** Every doc opens with a *Source of truth* line linking the file (and service/key name — never line numbers). Docs explain *why*; they name keys/flags but never restate values. If doc and source disagree, the source wins. - **Comments → docs.** Explanatory comments in `docker-compose.yml`, `.env.example`, `scripts/` move into docs; the code keeps a one-line `# see docs/<file>.md#<section>` pointer where a reader needs it. **Exception:** warnings about data loss, security, or edits that break the stack/script stay inline as one line + pointer; keys auto-filled by `update.sh` keep a short "auto-filled — leave blank" marker. `ponytail:` markers are converted like any other comment. - **Removed from the stack:** ComfyUI, Qwen-Image, `downloader-comfyui`, `scripts/switch-model.sh`, Open WebUI, Lazytainer, neo4j. qdrant becomes loopback-only (see Intent vs. source). - `docs/research/` is kept verbatim (history) behind an index marking each doc current / superseded-by; the two image-generation research docs are deleted. - Keep `docs/server-planing.md`. Keep `AGENTS.md` and `QWEN.md` stubs (another harness reads `QWEN.md`). - Use terms as defined in `CONTEXT.md` once it exists. - Skills: `/grilling` + `/domain-modeling` for grilling tickets; `/writing-for-agents` for the agent guide. ## Tickets - [x] Audit: contradictions and duplicates across docs and code comments (#56) - [x] Research-doc index: current vs. superseded (#57) - [x] Removal inventory: image generation and Open WebUI (#58) - [x] Glossary: pin down domain terms in CONTEXT.md (#59) - [x] Target doc structure (#60) - [x] Comment destination map (#61) - [x] Agent guide: writing docs and extending the glossary (#62) - [x] Execution hand-off checklist (#64) - [x] Intent vs. source: fix the config or fix the doc? (#63) ## Decisions so far - [Execution hand-off checklist](https://git.arthurerlich.de/haylan/LLM-Server/issues/64) — 7 phases (removals → source → docs → comments → agent guide → done-check/PR → server deploy by user), each pointing at its deciding ticket. **Map complete — ready to execute.** - [Agent guide: writing docs and extending the glossary](https://git.arthurerlich.de/haylan/LLM-Server/issues/62) — `docs/agents/writing-docs.md` (6 rules + done-check) behind a `CLAUDE.md` pointer; new-term procedure goes into `domain.md`. - [Comment destination map](https://git.arthurerlich.de/haylan/LLM-Server/issues/61) — every comment block in compose, `.env.example`, `update.sh` mapped to a doc section with pointer / inline warning / nothing; carve-out widened to breakage warnings + auto-filled markers. - [Target doc structure](https://git.arthurerlich.de/haylan/LLM-Server/issues/60) — README (intro/quickstart/index) + architecture, gateway, network-access, operations, coding-cli-setup, research index; request-priority doc moves to research; both build plans labelled background research. - [Intent vs. source: fix the config or fix the doc?](https://git.arthurerlich.de/haylan/LLM-Server/issues/63) — dashboard stays LAN-published (docs fixed, not internet-routed); neo4j and Lazytainer removed; qdrant bound to loopback. - [Glossary: pin down domain terms in CONTEXT.md](https://git.arthurerlich.de/haylan/LLM-Server/issues/59) — `CONTEXT.md` drafted on the branch: Gateway, Workload, API key, Backend, Provider connection, Main/Classifier model, Slot, Server; no service renames. - [Audit: contradictions and duplicates across docs and code comments](https://git.arthurerlich.de/haylan/LLM-Server/issues/56) — stale `OMNIROUTE_PORT:-4000` everywhere, dashboard port wrongly called unpublished, lazytainer presented as working, classifier VRAM story contradicts itself; six duplicate clusters (GID rationale, classifier, per-slot ctx, key minting, timeouts, LiteLLM history). - [Research-doc index: current vs. superseded](https://git.arthurerlich.de/haylan/LLM-Server/issues/57) — 15 current, 9 superseded (mostly LiteLLM-era → OmniRoute), 2 image-gen docs deleted; several inbound links need retargeting; flags a research doc calling `server-planing.md` superseded. - [Removal inventory: image generation and Open WebUI](https://git.arthurerlich.de/haylan/LLM-Server/issues/58) — per-file removal checklist; GID vars, gum and `scripts/vendor` stay (still used); server-side leftovers (volumes, dashboard provider/key, proxy routes) listed as manual steps. ## Not yet specified ## Out of scope - Triaging the rest of the issue tracker. Obsolete maps/tickets (LiteLLM → OmniRoute migration, LiteLLM search/knowledgebase, the two "Verify … on the real R9700 box" tickets, the image-generation map and its ComfyUI ticket) were closed while charting this map.
haylan added the wayfinder:map label 2026-09-24 19:08:02 +00:00
haylan commented 2026-09-24 19:53:08 +00:00
Author
Owner
Copy link
Copy source

Execution done (phases 1–6 of the hand-off checklist): PR #65. Remaining: review/merge, then phase 7 deploy on the server (steps in the PR body).

Execution done (phases 1–6 of the hand-off checklist): PR https://git.arthurerlich.de/haylan/LLM-Server/pulls/65. Remaining: review/merge, then phase 7 deploy on the server (steps in the PR body).
haylan commented 2026-09-24 19:58:28 +00:00
Author
Owner
Copy link
Copy source

Deployed: PR #65 migrated onto the server and confirmed working by the user. All tickets resolved — closing the map.

Deployed: PR #65 migrated onto the server and confirmed working by the user. All tickets resolved — closing the map.
Sign in to join this conversation.
No Branch/Tag Specified
Labels
Clear labels
wayfinder:grilling
Wayfinder grilling ticket
 wayfinder:map
Wayfinder map issue
 wayfinder:prototype
Wayfinder prototype ticket
 wayfinder:research
Wayfinder research ticket
 wayfinder:task
Wayfinder task ticket
No labels wayfinder:map
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
haylan (Arthur Erlich)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: haylan/LLM-Server#55