Skip to content

Procedural guides package strategy — Smart Farm Wiki

Purpose: Treat stepwise operator procedures as first-class pages: one place they live, shared metadata, clear separation from essays and standards, and explicit links to architecture, entities, and norms.

Policy: AGENTS.md — page_subtype, operational_maturity, Guides vs runbooks vs standards (below in this file mirrors the contract), ingest activation, Evidence summary expectations on high-value source-notes, structural vs integration validation.

Integration: New procedure pages should attach to an existing guide hub or standard (or extend the backup DR package / platform doctrine spine) so they are not orphan runbooks—see Canonicalization in AGENTS.md.

Where guides live

  • Path: wiki/analyses/ only (same validation rules and MkDocs publishing as other syntheses; no parallel wiki/guides/ tree).
  • Page type: page_type: analysis with page_subtype: operational_guide for any procedure-shaped page: a single how-to, a hub that sequences child steps, an incident runbook, or a long doctrine spine that still cues operators (tables, phases, drill steps).
  • Filenames: kebab-case.md; prefer runbook-*.md for incident / degraded-mode procedures so they are obvious in search and indexes.

How guides differ from analyses, standards, and runbooks

Kind page_subtype Reader question
Essay / audit / synthesis (omit), or meta_audit / query_synthesis Why? What should we believe? What did we decide?
Standard standard What must be true? (short norm; bar, not a full install)
Guide (procedural) operational_guide What steps, in what order? (bootstrap, migration, validation drill)
Runbook operational_guide + runbook-*.md (or Runbook — title) What do we do when something breaks, degrades, or alarms?

Doctrine / package spines (e.g. backup DR package) often use operational_guide because they route operators; they are still guides in the sense of this strategy—they are not optional “essays.”

Standards vs guides: standards state bars; guides implement sequences. Do not duplicate full command-level procedure in a standard when a guide exists—link the standard to the guide hub.

Guide maturity

Use operational_maturity for procedure pages (orthogonal to status: draft / active / deprecated).

YAML value Plain language
draft Structure exists; not yet walked on live systems
pilot_ready Lab or constrained pilot; limitations documented
field_tested Used on real farm/homelab edge under stated constraints; drills or incidents inform updates
superseded Routing only; pair with superseded_by (and a short pointer in the body)

Labels like pilot-ready or field-tested in prose map to pilot_ready and field_tested in frontmatter.

Each procedural page should make routing easy without copying canonical architecture:

  1. Doctrine or reference architecture — why this procedure exists (if not obvious from the title).
  2. Standards — norms that must hold before/after the steps (Operational standards — farm and homelab platform catalog).
  3. Entities — stable roles (Field node classes (G/R/S/H/W), WAN edge and backhaul roles, Backup and restore tier labels, …) instead of redefining glossaries.
  4. Parent hub — package hub (Platform doctrine package — homelab / farm edge, Backup and disaster recovery — doctrine hub, …) or Wiki navigation and structural hubs.

Secrets: follow AGENTS.md — placeholders in published pages; no live credentials in wiki/.

Canonical guide hubs (entry points)

Domain Hub
Homelab edge — Pi, k3s, Longhorn, Rancher How to provision k3s, Longhorn, and Rancher on a Raspberry Pi fleet
Backup / DR — stack-wide story Backup and disaster recovery package — smart farm stack
DR — incident framing Disaster recovery decision rules — farm edge stack
Kubernetes platform backup / DR (integration) Kubernetes platform backup / DR — Pi, k3s, Longhorn

Example runbooks (incident-shaped): Runbook — backup validation and recovery drill, Runbook — broker or backhaul down, Runbook — power loss at remote site.

See also