08 — Records and templates

TL;DR: Have your AI operator keep configuration, equipment records, decisions, and task summaries in your private GitHub repository. Keep secrets and sensitive original exports in a protected archive, with references in the records. Use the templates when their subject comes up.

Keep records as you work#

Your AI operator should fill in details it can inspect. You decide matters such as who may use a service, which files to protect, and how much to spend. These templates help it keep a useful record; they are not homework you must complete before starting the guide.

Keep a working clone of your private GitHub repository on your admin computer. After each task, have the AI operator commit the configuration and records with a meaningful message and push them. For unfinished work, save a clearly identified checkpoint describing what was applied and what remains. Refresh an offline recovery copy as well.

Git lets you compare previous configuration and prepare a reversal or correction. Checking out an older revision does not change a running service or restore its database. The change record must explain how to apply that configuration and what to do with data written since the earlier version.

Start with the interview and equipment record#

Use the first interview to describe what you want to run, the equipment you have, and your practical limits. Your AI operator should ask about the current stage, then inspect what it can. You should not have to plan a future directory service before setting up your admin computer.

Prompt to paste:

Help me plan the next stage of this guide. Ask about the services I want,
equipment available, files that must be protected, budget, space/noise limits,
and the people who will use or maintain it. Inspect technical facts you can
check instead of asking me to supply them. Use "AI operator" consistently and
call the machine where we work together "my admin computer."

Create the relevant records from these templates as we work. Explain choices
and missing information in plain language. Do not present completed setup as
a prerequisite when this stage is supposed to teach us how to do it.

Use the equipment record for computers, drives, and network connections. Keep the model, role, useful capabilities, health, and date checked. Label physical drives and cables so you can match the record to the equipment.

If there are identifiers you do not want sent to an AI provider, use stable labels such as disk-a in the shared record and keep their mapping in the protected hardware record. Store that mapping outside the AI operator's account. Before erasing a drive, you still need to match the selected label to the physical drive; a generic label does not make that check unnecessary.

Record how to connect#

The connection and tool catalog records each computer's normal address, recovery address, account reference, permitted connections, and last test. Your AI operator should consult it before trying another computer.

Include your admin computer, each server, and PiKVM if installed. For a switched PiKVM setup, record the port associated with each computer. Include power and startup limitations, such as when you need to unlock an encrypted computer locally.

Keep passwords and private keys in their protected stores. The catalog says where to find or use a credential; it does not contain the credential itself.

Save decisions and task results#

A decision record explains what you chose and why. Record rejected options when they are likely to come up again. “One combined server because its downtime is acceptable and we have room for its drives” is more useful than a list of unexplained settings.

Use the session record to summarize what you asked for, what changed, what was tested, and what remains. Save original session exports and terminal output separately when they contain sensitive information. Put a searchable summary and reference in Git so a future session can find them.

Use the handoff record before ending a session with unfinished work. Ask a fresh session to find a previous decision and compare the recorded setup with what is currently running. Fix the record if it cannot do that.

Prompt to paste before stopping:

Save a checkpoint for this task. Separate proposed changes from changes already
applied. Record the current result, tests passed or failed, decisions, remaining
work, and recovery instructions. Include the relevant configuration revision
and references to protected logs without copying secrets into Git.
Commit and push the completed records, or a clearly marked unfinished checkpoint.
Leave the next session enough information to inspect current state and continue.

Prepare a change you can review#

Use a work order for a complete task and a change record when configuration or data will change. Your AI operator should prepare these, then show you the decisions or actions it needs from you.

You should be able to tell which computer is changing, what users will notice, which files may be affected, and how to recover. When you need to run a command, it should name the account and location and explain the expected result. A collection of unexplained commands is not a useful procedure.

For an operation that erases or reorganizes drives, use the drive-erasure authorization record. Decide for the named physical drives and current operation. A months-old equipment record saying a drive was spare is not permission to erase what is on it today.

Use the access record to track accounts and permissions. To grant or revoke access, change the actual account, key, or service permission and test it. Editing a row in Git alone does not change access.

Keep the server, storage, and application records together#

These templates belong with the chapters that create the corresponding setup:

These files use structured fields so your AI operator can check consistency. Ask it to explain a field when it affects your decision; you do not need to memorize the format.

A scheduled-job record should show the job that was actually installed, the data it covers, and where to check its last result. “Daily backup” in a plan does not show that anything ran. Have your AI operator verify a run without its session active and test restoration from that backup.

Keep recovery instructions offline#

Fill out the printable recovery card as you test each connection. It should identify the router, DNS device, admin computer, servers, recovery cable, PiKVM ports, and power connections you need to recognize.

Write the steps you actually used: which cable to connect, which address to enter, which account to use, and where its credential is stored. Test reading the card when your usual name lookup or network path is unavailable. Someone should be able to follow it without knowing what “Tier 0” means.

Keep a paper copy near the equipment and a protected copy outside the house. Credentials belong in a separately protected recovery store that you can reach without the failed homelab. Explain how to reach that store on the card without printing the secrets themselves.

Record recovery practice#

Use the recovery-test record to describe what you tested, why, what happened, and what still needs fixing. Distinguish routine checks from tests that deliberately interrupt a service.

Test destructive or disruptive scenarios using disposable data, a spare machine, or an agreed maintenance period with someone present. Decide the recovery steps beforehand. If an important check fails, give the corrective work a clear next action rather than marking the exercise complete.

Ask for an independent review when needed#

For unfamiliar storage, access, or network changes, use the review template. Give a separate review session the same facts and proposed change, with secrets removed. Keep it separate from the account applying changes.

Ask what assumptions it questions and which checks would settle them. If two reviewers disagree, investigate the disagreement. Agreement alone does not confirm a technical claim.

Use the AI operator access test when changing the tools or permissions it uses. Have it prepare a disposable test with no personal data or real credentials. Check that prohibited actions fail and that it reports those failures correctly. The AI operator chapter explains how to begin.

The read-only inspection template can help you define the targets and information it may inspect. You can authorize a useful batch of checks once; a separate decision is needed if the task reaches data or actions outside that scope.