Initial commit: homelab infrastructure wiki
- Full Obsidian vault content - Host configs (ice, grizzley, ubuntu, proxmox, truenas, panda, hyte) - Media stack documentation - Traefik HA setup - Automation scripts - Bachelor party planning
This commit is contained in:
Hermes Agent
162
homelab/SCHEMA.md
Normal file
162
homelab/SCHEMA.md
Normal file
@@ -0,0 +1,162 @@
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user