{"key":"change_documentation_guide","title":"change-documentation-guide.md","content":"# Change Documentation Guide\n\nThis note explains how change documentation should be created in the homelab documentation repository.\n\nIt is the human-readable companion to:\n- `notes/ai-change-documentation-spec.md`\n\n## Goal\n\nWhenever we make a meaningful change in the homelab, we want two things to happen:\n\n1. The current-state documentation should reflect the new reality.\n2. The change itself should be recorded so we know what happened, why, and what to watch later.\n\n## What Counts As A Meaningful Change\n\nExamples:\n- hostname changes\n- DNS record changes\n- SSH access changes\n- onboarding a host\n- changing the control node\n- modifying storage layout\n- moving a service\n- changing automation or publish workflow\n\n## What Should Usually Be Created\n\nFor most significant changes, create:\n\n1. A dated change note\n2. Any current-state documentation updates\n3. Any needed policy or runbook updates\n\n## Recommended Structure\n\n### Current state\n\nUse `outputs/current/...` for documentation that describes what exists right now.\n\nExamples:\n- current host inventory\n- current DNS behavior\n- current SSH access model\n- current service mappings\n\n### Change history\n\nUse `outputs/history/...` for dated change notes.\n\nExamples:\n- `2026-03-18-hostname-standardization.md`\n- `2026-03-18-windows-ssh-dns-setup.md`\n\n### Standards and procedures\n\nUse `docs/policies/...` and `docs/runbooks/...` for repeatable guidance.\n\nExamples:\n- hostname standard\n- SSH access standard\n- how to rename a host\n- how to add DNS records\n\n## What To Record In A Change Note\n\nEach change note should answer:\n- what changed\n- why it changed\n- which systems were affected\n- what files/configuration were touched\n- how the result was validated\n- what follow-up remains\n\n## Secret Safety\n\nDo not record:\n- passwords\n- tokens\n- private keys\n- raw secret files\n\nDo record:\n- where secrets are stored\n- which systems depend on them\n- which config files or env files reference them\n\n## Current Homelab Naming And Access Assumptions\n\nAt the time this guide was written, the intended operating model is:\n\n- internal host A records live in `accursedbinkie.com`\n- short-name access depends on clients using `accursedbinkie.com` as a DNS suffix/search domain\n- `svc-admin` is the default admin SSH identity across the homelab\n- `Binkie-Desktop` uses `Jason` as the normal user SSH path\n- `Binkie-Desktop` admin access is `svc-admin`\n- Windows `svc-admin` SSH access is intentionally limited to trusted homelab systems\n\n## Intended Use With AI\n\nWhen asking an AI model to document a change, point it to:\n- `notes/ai-change-documentation-spec.md`\n\nThat file is the instruction document.\nThis file is the operator-facing summary of the same approach.\n\n\n---\n**Created:** 2026-03-18 22:08:31 UTC","summary":"# Change Documentation Guide\n\nThis note explains how change documentation should be created in the homelab documentation repository.\n\nIt is the human-readable companion to:\n- `notes/ai-change-documentation-spec.md`\n\n## Goal\n\nWhenever we make a meaningful change in the homelab, we want two things to happen:\n\n1. The current-state documentation should reflect the new reality.\n2. The change itself should be recorded so we know what happened, why, and what to watch later.\n\n## What Counts As A Meaningful Change\n\nExamples:\n- hostname changes\n- DNS record changes\n- SSH access changes\n- onboarding a host\n- changing the control node\n- modifying storage layout\n- moving a service\n- changing automation or publish workflow\n\n## What Should Usually Be Created\n\nFor most significant changes, create:\n\n1. A dated change note\n2. Any current-state documentation updates\n3. Any needed policy or runbook updates\n\n## Recommended Structure\n\n### Current state\n\nUse `outputs/current/...` for documentation that describes what exists right now.\n\nExamples:\n- current host inventory\n- current DNS behavior\n- current SSH access model\n- current service mappings\n\n### Change history\n\nUse `outputs/history/...` for dated change notes.\n\nExamples:\n- `2026-03-18-hostname-standardization.md`\n- `2026-03-18-windows-ssh-dns-setup.md`\n\n### Standards and procedures\n\nUse `docs/policies/...` and `docs/runbooks/...` for repeatable guidance.\n\nExamples:\n- hostname standard\n- SSH access standard\n- how to rename a host\n- how to add DNS records\n\n## What To Record In A Change Note\n\nEach change note should answer:\n- what changed\n- why it changed\n- which systems were affected\n- what files/configuration were touched\n- how the result was validated\n- what follow-up remains\n\n## Secret Safety\n\nDo not record:\n- passwords\n- tokens\n- private keys\n- raw secret files\n\nDo record:\n- where secrets are stored\n- which systems depend on them\n- which config files or env files reference them\n\n## Current Homelab Naming And Access Assumptions\n\nAt the time this guide was written, the intended operating model is:\n\n- internal host A records live in `accursedbinkie.com`\n- short-name access depends on clients using `accursedbinkie.com` as a DNS suffix/search domain\n- `svc-admin` is the default admin SSH identity across the homelab\n- `Binkie-Desktop` uses `Jason` as the normal user SSH path\n- `Binkie-Desktop` admin access is `svc-admin`\n- Windows `svc-admin` SSH access is intentionally limited to trusted homelab systems\n\n## Intended Use With AI\n\nWhen asking an AI model to document a change, point it to:\n- `notes/ai-change-documentation-spec.md`\n\nThat file is the instruction document.\nThis file is the operator-facing summary of the same approach.\n\n\n---\n**Created:** 2026-03-18 22:08:31 UTC","status":"active","namespace":"general","namespace_name":"general","namespace_tier":"shared","tags":[]}