📜 The Product Requirements Document

The constitution for the Home Infrastructure Handbook. Every chapter, page, diagram, and PDF is measured against this document. Written by ChatGPT in the original conversation, captured here as the project foundation.

01 · Project Vision & Mission

Purpose. Design, build, and continuously maintain the best freely available Home Infrastructure Handbook on the Internet — a living, searchable, version-controlled knowledge base for TK's home lab that can also export beautiful PDFs for offline reading.

Audience. Primary: TK (and his family, who'll use the lab). Secondary: anyone building a home lab with TrueNAS SCALE, ZFS, or comparable self-hosted infrastructure. Tertiary: future TK, who'll re-read this when the lab has grown and the original context is gone.

Mission. Treat every recommendation as if it had to survive five years of evolution. New tech becomes a new volume, not a rewrite.

Goals.

• Searchable, continuously updated, version controlled, easy to navigate
• Contains videos, diagrams, code blocks, screenshots, downloadable PDFs, and interactive content
• Website is the canonical version; PDF is a snapshot
• Open-ended: new volumes get added as the lab grows

02 · Audience Definition

Primary: TK — a self-taught systems engineer building a real, family-grade home lab. Comfortable with computers, learning Linux and ZFS, working through a Master's in Data Science. Reads the handbook on planes (East Coast trips), then refers back to it while building.

Secondary: A reader who is similar to TK — comfortable with computers, new to TrueNAS/ZFS, family of 4, wants to understand concepts before clicking buttons. The handbook should serve this reader without modification.

Tertiary: Anyone else who finds the site and needs an honest, opinionated guide to home infrastructure.

03 · Learning Philosophy

The handbook is not a how-to. It is a mentorship in document form.

Assume the reader has little Linux experience. Explain concepts before procedures. Show the alternatives. Surface the tradeoffs. Prefer diagrams over paragraphs. Use real examples. Use the reader's actual hardware and datasets whenever possible.

Every chapter answers: Why does this exist? Why this way? What's the alternative? What could go wrong?

04 · Information Architecture

Top-level structure: Volumes → Chapters → Sections.

• Each volume covers a phase of the lab's evolution (Foundations → Family NAS → Creator Studio → Home Lab → Data Science → Operations).
• Each chapter is a self-contained learning unit — readable in one sitting, exportable as a single PDF.
• Each chapter follows the same template (see §13).

Cross-references are first-class: chapters link to prerequisites and follow-ups. No chapter is an island.

05 · Website Architecture

Static site. No build step required. Loads fast. Works without JavaScript for the core reading experience (JS enhances with search, sidebar, print). Dark mode follows the OS. Mobile-first layout.

Stack: HTML + a single shared CSS file + a small JS file. That's it.

Per chapter: A standalone HTML page. Each page is printable to PDF via the browser's native print dialog (a print stylesheet strips nav and produces a clean book layout).

Hosting: Mac Mini (home) → cloudflared tunnel → homelab.aidalee.com. Same setup as the other TK sites.

06 · Navigation & Search

Sticky left sidebar with the full handbook tree. Search box in the sidebar (page-level for v1, site-wide via JSON index in v2). Breadcrumbs on every page. "Next/Previous chapter" nav at the bottom of every chapter. Keyboard shortcuts (j/k to navigate, / to focus search) coming in v2.

07 · Content Standards

Every chapter uses the same template. See §13. Every page has a toolbar with: print-to-PDF, version badge, "skip to next" link. Every page has breadcrumbs. Every page has a meta footer with version + last-updated date.

08 · Writing Style Guide

Three rules from the original ChatGPT conversation, plus a few additions:

• Sound like an experienced systems engineer mentoring a junior engineer. Not marketing. Not a textbook. Not a forum post. A senior engineer sitting next to you explaining the why and the how.
• Write as if it were timeless. Say "Navigate to the Storage section," not "Click the blue button." UIs change; concepts don't.
• Prefer current TrueNAS SCALE terminology. Update as the platform evolves. Never invent commands or invent UI labels.
• Always compare alternatives. If you recommend ZFS snapshots, mention Synology snapshots, QNAP snapshots, Linux LVM snapshots. The handbook is a guide to thinking, not a product manual.
• Include tradeoffs explicitly. RAIDZ2 vs RAIDZ3. SMB vs NFS. Local auth vs SSO. Every recommendation has a "when to use this" and a "when not to."
• Never recommend enterprise complexity unless justified. No Ceph, no Gluster, no Kubernetes for the home. If something only makes sense at scale, say so and link out.
• Prefer diagrams. A 200-word paragraph becomes a 50-word diagram in half the time. Use ASCII art for tree-style diagrams (pool layout, dataset tree, network topology) and SVG for everything else.

09 · Illustration Standards

Three principles:

• Simple. One concept per diagram. No decorative elements.
• Professional. Monospace font for ASCII art. Clean SVG for everything else. No clip art.
• Consistent. Reuse a single visual language across all chapters. Same colors mean the same things. Same symbols mean the same things.

Standard diagram types: pool layout, dataset tree, network topology, VM architecture, Docker networking, permission flowchart, backup strategy, video production workflow, remote access.

10 · Code & Command Standards

• Use fenced code blocks with the language tag.
• Real commands, not pseudo-code. Always testable on a real TrueNAS install.
• Inline code for filenames, dataset names, and short identifiers.
• Never invent commands. When the documentation is ambiguous, link to the official source.
• Always show the output (or at least the first/last lines) when the output matters.

11 · Platform & Publishing Requirements

The site is platform-agnostic. It runs on any static-file web server. No build step. No bundler. No framework.

Publishing: edit a file → reload the page → done. The site is the live canonical version. PDFs are generated on demand from any chapter via the browser's print dialog.

The Mac Mini hosts the live site on port 8006. Cloudflared tunnels it to homelab.aidalee.com.

12 · Versioning Strategy

Semver-style for the project. v0.x during the build-out. v1.0 when Volume 1, 2, and 3 are complete. v2.0 when Volumes 4–6 are complete. v3.0 when the lab has its first AI workload running.

Each chapter has a "last reviewed" date. If a recommendation is still accurate, the date is updated. If something changed, the chapter is updated and the version is bumped.

Git for change history. The site lives in a git repo on the Mac Mini. Every commit notes which chapter was edited and why.

13 · Chapter Template

Every chapter, every volume, no exceptions:

1. Learning Objectives — what you'll be able to do after reading this.
2. Introduction — why this chapter exists in this volume at this point.
3. Concepts — the mental model before any procedures.
4. Diagrams — visual explanations of the concepts.
5. Examples — concrete worked examples using TK's actual hardware and datasets.
6. TK Tips — personal annotations specific to TK's setup, family, and workflow.
7. Engineering Notes — the deeper principles, the "things I wish someone had told me" callouts.
8. Common Mistakes — what people (including TK, on a bad day) actually get wrong.
9. Summary — the chapter in one paragraph.
10. Checklist — the things to actually do before moving on.
11. Looking Ahead — what the next chapter covers and how it builds on this one.

14 · Volume Roadmap

The original ChatGPT proposal, refined:

15 · Technical Accuracy Requirements

Every command, every UI path, every recommendation is tested against TK's actual TrueNAS install before publication. When the documentation conflicts with reality, reality wins and the docs get updated.

Source authority ranking: official TrueNAS docs > TrueNAS community forum > blog posts > Reddit > YouTube. The lowest tier is cited only for inspiration, never as a primary source.

16 · AI Agent Instructions

The agent (Aida, in this case) follows these rules when writing or updating chapters:

• Never invent commands. If unsure, link to the official source.
• Prefer current TrueNAS SCALE terminology. Update as the platform evolves.
• Explain concepts before procedures. The "why" comes before the "how."
• Always compare alternatives. Show at least one other option, even if the recommendation is clear.
• Include tradeoffs explicitly. No hand-waving.
• Never recommend enterprise complexity unless justified. This is a home lab. Keep it proportional.
• Prefer diagrams. Visual > text whenever possible.
• Assume the reader has little Linux experience. Explain the basics without condescension.
• Keep explanations technically accurate. Precision over vibes.
• Follow the chapter template. Every chapter. No exceptions.
• Preserve TK's voice. This is TK's handbook. When quoting TK or capturing his specific situation, use his words. When the agent is writing, use the engineering mentor voice defined in §08.

17 · Quality Assurance Checklist

Before any chapter is published:

• ✅ All commands tested on TK's actual install (or a matching VM)
• ✅ All UI paths match the current TrueNAS SCALE version
• ✅ Every diagram renders cleanly at default size
• ✅ Every code block has correct language tag
• ✅ Every chapter follows the §13 template
• ✅ Cross-references resolve to existing chapters
• ✅ PDF export (via browser print) is clean and book-like
• ✅ Read-through by TK — would he learn from this?
• ✅ "Engineering Note" callouts added where the wisdom is non-obvious
• ✅ "Common Mistakes" section covers at least 2 real-world failure modes

18 · Long-Term Maintenance Plan

The handbook is a living document. The lab will evolve; the handbook evolves with it.

• Quarterly review: re-read each chapter, verify commands, check for UI changes
• After every major TrueNAS release: review affected chapters, update terminology
• After every lab hardware change: update §9 (Your actual homelab) and any chapter that references the old hardware
• When a chapter is wrong: fix it. Don't add a footnote. Fix it.

Versions don't just track added content — they track lessons learned. v1.0 reflects what TK and the agent thought was right in July 2026. v2.0 reflects what they learned by living with it.

19 · Future Expansion Strategy

The original ChatGPT conversation identified these as likely future volumes:

• AI / LLM workloads — running models locally, GPU server, inference at home
• Home Assistant — smart home, automations, sensors
• Advanced networking — 10 GbE, VLANs, firewall segmentation, VPNs
• Kubernetes at home — when the lab is ready for orchestration
• GPU servers — dedicated hardware for ML training
• Cloud bridge — selectively syncing specific datasets to/from cloud storage
• Second NAS / off-site replication — DR planning, 3-2-1 backups, the offsite copy
• Rack build — when the lab outgrows the desk

None of these are planned. They're listed as triggers: when TK is ready, a new volume opens. The PRD grows with each new volume.

20 · Appendices

Living appendices, not a fixed list:

• Glossary — every technical term used in the handbook, defined once, linked from every chapter
• Reference cards — printable, formula-focused sheets (similar to datascience.aidalee.com's cheatsheets)
• Hardware log — every piece of hardware TK has ever owned, with notes on what worked and what didn't
• Dataset inventory — TK's current pool/dataset layout, snapshots, retention policies
• Service inventory — every app, VM, and container running, with version, purpose, and last-touched date
• Troubleshooting journal — every problem solved, with the root cause and the fix
• Index — full-text index across the entire handbook (coming in Phase 2)

PRD v0.1 · drafted from the original ChatGPT conversation, July 2026