dtoro
e3a0326c78
Full review (plans/2026-07-17-codebase-review-and-cleanup.md) covering Go, web SPA, and docs. Applied low-risk doc/tooling fixes; code refactors and dead-code deletions are listed as actionable recommendations pending approval. Doc fixes: - AGENTS.md: remove ghost of retired request_execution (contradicted the retire notice above it); fix knowledge/wiki/ -> archive/knowledge/; replace brittle counts (33 tools, 36 docs, 20 checks) with pointers to source; drop point-in-time dates. - OIKOS.md: fix broken plan link (now in done/); 001-011 -> 001-020; 15 MCP tools -> pointer; replace hardcoded knowledge counts. - README.md: 15 tools -> pointer; fix wails plan link (now in done/); complete internal/ package list (add checkdefaults, observability, safego); add cmd/desktop/ to repo layout. - commands.md, page-templates.md: fix broken links; HERMES.md -> NOMOS.md. Plans housekeeping: - Move 4 done 2026-07-14 plans from plans/ to plans/done/. - Reconcile plans/index.md: add the 2 missing 2026-07-14 entries and the 2 missing 2026-07-15 done entries; add this review. - Fix stale plan path in migrations/020 comment. New docs: - docs/index.md and docs/operations/README.md (folder READMEs per writing-style.md). Tooling: - web/package.json: add check/typecheck/lint scripts + svelte-check devDep. - Makefile: desktop-package version now reads from VERSION file instead of hardcoded 0.1.0. VERSION 0.7.6 -> 0.7.7 (patch: docs + tooling only).
175 lines
5.6 KiB
Markdown
175 lines
5.6 KiB
Markdown
# Page templates for the Homelab Wiki
|
|
|
|
The structural templates for each page type. Prose voice, vocabulary, and cross-reference rules live
|
|
in [writing-style.md](writing-style.md); the layer model (sources / wiki / index / log) lives in
|
|
[llm-wiki.md](llm-wiki.md).
|
|
|
|
## File naming
|
|
|
|
**Foundational / entry-point files:** ALL-CAPS
|
|
|
|
- **Root level:** `AGENTS.md`, `README.md` — discovery paths for agents and humans.
|
|
- **Agent instruction** (under `.agents/`): `OIKOS.md`, `NOMOS.md` — foundational docs agents read before acting.
|
|
- **Reference docs:** `GLOSSARY.md` — lookup reference (like classic repo conventions: LICENSE, CHANGELOG, GLOSSARY).
|
|
|
|
**Content / narrative pages:** lowercase-with-dashes, date-prefixed as needed
|
|
|
|
- **Container pages:** `<id>-<name>.md` (e.g. `101-jellyfin.md`, `132-rclone.md`). The `<id>` is the LXC/VM ordinal from `inventory.yaml`.
|
|
- **Infrastructure / cross-cutting pages:** `<topic>.md` (e.g. `dns.md`, `auto-deploy.md`, `mesh.md`). Describes a system, not a specific node.
|
|
- **Plans / investigations:** `YYYY-MM-DD-<slug>.md` (e.g. `2026-07-05-oikos-prometheus-lxc.md`). Date-sorted; slug is lowercase.
|
|
- **Section indices:** `README.md` (lowercase, conventional). Prefer in folders; `index.md` only if both intro prose and listing coexist.
|
|
|
|
**Skills / runbooks:** special case
|
|
|
|
- **Folder structure:** `<name>/SKILL.md` where `<name>` is lowercase-with-dashes (e.g. `client-enrollment/SKILL.md`).
|
|
- **The filename SKILL.md is always uppercase** — it acts as a signpost so tools and humans instantly recognize it as a skill.
|
|
|
|
**General rules:** All paths use lowercase letters, numbers, and hyphens (no underscores). Uppercase is reserved for foundational docs (entry points + instruction) and filenames that signify document type (SKILL.md, GLOSSARY.md, etc.).
|
|
|
|
## Voice
|
|
|
|
Concise, technical, sysadmin-to-sysadmin. No marketing prose, no exclamation marks. Full rules in
|
|
[writing-style.md](writing-style.md).
|
|
|
|
## Page templates
|
|
|
|
### Container page (`containers/<id>-<name>.md`)
|
|
|
|
```markdown
|
|
# <id> — `<name>`
|
|
|
|
One-sentence purpose.
|
|
|
|
## At a glance
|
|
- **Hostname:** `<name>`
|
|
- **IP:** `192.168.8.x`
|
|
- **Privilege:** privileged | unprivileged
|
|
- **Resources:** N cores / M GiB RAM / D GiB rootfs
|
|
- **Mounts:** `/mnt/library` ↔ `/mnt/library` (if any)
|
|
- **Public hostname:** `<sub>.hubris.network` (if proxied)
|
|
|
|
## Role
|
|
What it does, what it talks to.
|
|
|
|
## Service / port map
|
|
| Service | Listen | Notes |
|
|
|
|
## Storage / config paths
|
|
|
|
## Auto-deploy
|
|
(if any) — link to [auto-deploy](../infrastructure/auto-deploy.md)
|
|
|
|
## Related
|
|
- [Caddy](121-caddy.md) (if proxied)
|
|
- [DNS](../infrastructure/dns.md) (if has subdomain)
|
|
- [Authentik](124-authentik.md) (if SSO)
|
|
- ...
|
|
|
|
## Changelog
|
|
### YYYY-MM-DD — short title
|
|
What changed, why, link to investigation if any.
|
|
```
|
|
|
|
### Cross-cutting page (`infrastructure/<topic>.md`)
|
|
|
|
```markdown
|
|
# <Topic>
|
|
|
|
One-sentence summary.
|
|
|
|
## Why
|
|
Design rationale — what it replaces, what it solves.
|
|
|
|
## Components
|
|
Where it runs, what files matter.
|
|
|
|
## How to apply / use
|
|
Recipes.
|
|
|
|
## Gotchas
|
|
|
|
## Related
|
|
Links to nodes that host or depend on this.
|
|
|
|
## Changelog
|
|
```
|
|
|
|
### Plan (`plans/YYYY-MM-DD-slug.md`)
|
|
|
|
```markdown
|
|
# YYYY-MM-DD — <title>
|
|
|
|
## Goal
|
|
What this change achieves and why.
|
|
|
|
## Current topology / state
|
|
Diagram or description of what exists now.
|
|
|
|
## Target topology / state
|
|
What it looks like after.
|
|
|
|
## Pre-flight checklist
|
|
|
|
## Step-by-step procedure
|
|
|
|
## Verification
|
|
|
|
## Post-migration
|
|
Changelog entries to write, index status to update.
|
|
```
|
|
|
|
### Investigation (`knowledge/sources/investigations/YYYY-MM-DD-slug.md`)
|
|
|
|
```markdown
|
|
# YYYY-MM-DD — <title>
|
|
|
|
## Summary
|
|
1-3 sentences.
|
|
|
|
## Timeline
|
|
|
|
## Root cause
|
|
|
|
## Mitigations applied
|
|
|
|
## Open questions
|
|
```
|
|
|
|
## Linking discipline
|
|
|
|
- Every container page links to every cross-cutting page it participates in.
|
|
- Every cross-cutting page lists the nodes that participate.
|
|
- Every investigation links to the nodes it implicates *and* gets back-linked from each node's changelog.
|
|
- Every plan links to the infrastructure pages it affects. When done, update the plan's status in `plans/index.md` and write changelog entries on affected node pages.
|
|
|
|
## Changelog hygiene
|
|
|
|
- Reverse-chronological (newest first).
|
|
- One entry per discrete change, even if you make several in one day.
|
|
- If a change spans nodes, repeat the entry on each affected page (different perspective is fine).
|
|
- Don't rewrite history — entries are append-only. Mistakes get a follow-up entry that supersedes them.
|
|
|
|
## Same-session update rule
|
|
|
|
When you make a change to a node — migrate an LXC, update an IP, change a
|
|
mount, deploy a new service — **update every relevant doc page in the same
|
|
session.** A change that touches a container page must also update:
|
|
|
|
- The `containers/index.md` table (IPs, host, mounts, status)
|
|
- The `README.md` table (if the change affects listed columns)
|
|
- The Caddy page site list (if the change affects `*.hubris.network` routing)
|
|
- The DNS / ingress infrastructure pages (if the change affects routing)
|
|
- The `hosts/{hubris,strong}.md` host page (if container count changes)
|
|
- The `inventory.yaml` host entry (single source of truth)
|
|
- The `infrastructure/topology.md` (generated from inventory, but regen if needed)
|
|
|
|
The pattern of updating only one page and leaving stale references on others
|
|
is a bug. If you're doing a multi-step migration, document the intermediate
|
|
state with a changelog entry that says "pending — will finalize after Phase
|
|
N."
|
|
|
|
This rule is why Phase 2 of the strong migration (2026-07-05) caused
|
|
widespread stale data: individual container pages were updated in the
|
|
changelog but never had their At-a-glance sections, IPs, mount paths, or
|
|
host attribution updated. Don't repeat that.
|