---
title: Homelab Wiki Schema
created: 2026-04-28
updated: 2026-04-28
type: meta
tags: [meta, wiki]
---

# Wiki Schema

This wiki follows [Karpathy's LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — 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)

```yaml
---
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