hermes-ice/homelab/SCHEMA.md

title, created, updated, type, tags

title	created	updated	type	tags
Homelab Wiki Schema	2026-04-28	2026-04-28	meta	meta wiki

Wiki Schema

This wiki follows Karpathy's LLM Wiki pattern — a persistent, compounding knowledge base as interlinked markdown files. Unlike RAG, knowledge is compiled once and stays current. Cross-references already exist. Contradictions are flagged.

Location: WIKI_PATH env var (defaults to ~/wiki). All hosts point to the Obsidian vault at /home/bear/homelabagentroot/obsidian-vault.

Directory Structure

obsidian-vault/          ← WIKI_PATH for all hosts
├── SCHEMA.md            ← This file (schema, conventions)
├── log.md               ← Append-only action log (rotate yearly)
├── homelab/
│   ├── entities/        ← Layer 2: host and service entities
│   ├── concepts/        ← Layer 2: concepts, techniques, topics
│   ├── comparisons/     ← Layer 2: side-by-side analyses
│   ├── queries/         ← Layer 2: filed Q&A worth keeping
│   └── raw/             ← Layer 1: immutable source material (optional)
└── [other vault dirs]   ← ai-assistant/, automation/, agents/, etc.

Layer 1 — Raw Sources: Immutable source material (docs, configs, articles). The agent reads but never modifies these. Layer 2 — The Wiki: Agent-owned markdown files. Created, updated, and cross-referenced by the agent. Layer 3 — The Schema: This file constrains agent behavior and ensures consistency.

Conventions

• File names: lowercase, hyphens, no spaces (e.g., ice.md, hermes-gateway.md)
• Wikilinks: Use [[pagename]] for all internal links. Minimum 2 outbound links per page.
• Frontmatter: Required on every wiki page (see below).
• Index: Every new page must appear in homelab/entities/index.md (for entities) or the relevant section index.
• Log: Every action (ingest, create, update, query, lint) must be appended to homelab/log.md.
• Provenance markers: On pages synthesizing 3+ sources, append ^[raw/articles/source-file.md] at paragraph ends to trace claims.
• Confidence: Set confidence: medium or low for opinion-heavy, fast-moving, or single-source claims. Don't mark high unless well-supported.
• Contradictions: When new information conflicts with existing content, note both with dates/sources, set contradictions: [page-slug] in frontmatter, flag for review.
• Staleness: Pages not updated in 90+ days with newer source info should be refreshed.
• Page size: Split pages over ~200 lines into sub-topics with cross-links.
• Tags: Use the taxonomy below. Add new tags here before using.

Tag Taxonomy

Hosts

• hosts — physical or virtual host machines
• rpi — Raspberry Pi hardware
• hypervisor — VM/container hypervisors (Proxmox)
• nas — network-attached storage
• control-plane — primary control node (ice)
• edge — edge computing node (grizzley)
• primary — primary instance of a service (ubuntu as main Docker host)
• vm — virtual machine workloads

Services

• services — software services running on hosts
• networking — network services (Traefik, DNS, VPN)
• media — media streaming services (Jellyfin, Sonarr, etc.)
• storage — storage services (S3, NFS, ZFS)
• sso — identity/SSO services
• identity — identity and authentication services
• git — Git hosting and CI/CD
• ai — AI/ML services
• gateway — API/gateway services
• monitoring — observability stack
• docker — Docker containerization
• reverse-proxy — reverse proxy services (Traefik)
• jellyfin — Jellyfin media server
• traefik — Traefik ingress controller
• ubuntu — Ubuntu host services
• proxmox — Proxmox hypervisor services
• s3 — S3-compatible object storage
• ci-cd — continuous integration and deployment

Smart Home / IoT

• iot — Internet of Things devices and infrastructure
• smart-home — smart home automation and orchestration
• home-assistant — Home Assistant platform
• matter — Matter smart home protocol
• thread — Thread mesh networking protocol
• zigbee — Zigbee wireless protocol
• zigbee-device — individual Zigbee end devices
• wifi-device — Wi-Fi connected IoT devices
• ecosystem — vendor/platform ecosystems (Apple Home, Google Home, Alexa)
• sensor — sensor devices (motion, door, vibration)
• actuator — actuators (switches, lights, locks)
• voice-assistant — voice assistant platforms and devices
• hub — smart home hub or coordinator hardware
• inventory — device inventory and census pages
• vlan — VLAN segmentation and network zoning
• policy — formal placement/security/operational policies

Techniques & Roles

• concept — architectural patterns, techniques
• runbook — operational procedures
• comparison — feature/comparison analyses
• automation — automation scripts and workflows
• alerting — alerting and notification systems
• agents — AI agent configurations
• watchdog — watchdog/monitoring patterns
• ha — high availability configurations
• cli — command-line tools and interfaces
• scripts — shell/python scripts
• tools — development and operations tools
• homelab — homelab-specific infrastructure patterns

Meta

• meta — wiki housekeeping (schema, log, index)

Frontmatter (Required)

---
title: Page Title
created: YYYY-MM-DD
updated: YYYY-MM-DD
type: entity | concept | comparison | query | summary | meta
tags: [from taxonomy above]
sources: [raw/articles/source-name.md]   # optional, list source files
confidence: high | medium | low         # optional
contested: true                          # optional, set when contradictions exist
contradictions: [page-slug]              # optional
---

Entity Pages

One page per notable host or service. Include:

• Role, IP/URL, host location
• Overview of what it is/does
• Key facts and relationships
• Troubleshooting notes (known issues, gotchas)
• Source references

Concept Pages

One page per architectural pattern, technique, or topic. Include:

• Definition/explanation
• Current state of knowledge
• Open questions or debates
• Related concepts via [[wikilinks]]

Update Policy

When new information conflicts with existing content:

1. Check dates — newer sources generally supersede older
2. If genuinely contradictory, note both positions with dates and sources
3. Mark contradictions: [page-slug] in frontmatter
4. Flag for user review

Page Thresholds

• Create a page when an entity/concept appears in 2+ sources OR is central to one source
• Add to existing page when a source mentions something already covered
• DON'T create a page for passing mentions, minor details
• Split a page when it exceeds ~200 lines
• Archive a page when fully superseded — move to _archive/, remove from index