oikos/.agents/shared/page-templates.md

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; the layer model (sources / wiki / index / log) lives in 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 the entity's attributes in the DB (seeded via seeds/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.

Page templates

Container page (containers/<id>-<name>.md)

# <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)

# <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)

# 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 (investigation entity in the DB; historically archive/knowledge/sources/investigations/YYYY-MM-DD-slug.md)

# 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 the DB and every relevant doc page in the same session. A change that touches a container must also update:

• The entities / relationships rows for the node (via the API/MCP) — this is the source of truth
• The document entity's at_glance and ## Changelog for the container
• The containers/index.md table in the archived wiki (IPs, host, mounts, status) — historical reference, update for consistency where still consulted
• 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 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.