e4d91aadf9
- Full Obsidian vault content - Host configs (ice, grizzley, ubuntu, proxmox, truenas, panda, hyte) - Media stack documentation - Traefik HA setup - Automation scripts - Bachelor party planning
163 lines
6.9 KiB
Markdown
163 lines
6.9 KiB
Markdown
---
|
|
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
|