How We Work¶

This guide explains how the ExzenTCG team works. Read this end-to-end before making any changes to infrastructure or this documentation.

Why This Exists¶

Infrastructure knowledge can't live in one person's head. If that person is unavailable, nobody knows what's running, why decisions were made, or how to fix things.

Our solution: everything is documented as it happens, in a shared vault, published to a site everyone can read.

The principle: "If it's not documented, it didn't happen."

The Workflow¶

Every change to the homelab follows this loop:

1. PLAN    → Write what you're going to do           (01_planning/)
2. DO      → Execute the plan, log every action       (02_setup_logs/)
3. RECORD  → Update runbooks, architecture, creds     (03_runbooks/, 01_planning/)
4. PUSH    → Git commit + push                        (auto-deploys to docs.exzentcg.com)
5. VERIFY  → Check the published site is current

Before touching infrastructure¶

Read the current plan, implementation guide, and known issues for the relevant phase. Don't work from memory.

While working¶

Log every command, screenshot, decision, and error into the Phase Actions log (02_setup_logs/Phase N Actions.md). Keep it raw and ugly — accuracy matters more than formatting. When the phase is done, ask Claude to format it cleanly.

Any deviations from the original implementation plan should also be updated back into the plan itself — ask Claude to do this.

After finishing¶

Claude will suggest which files need updating — credentials index, architecture diagram, runbooks, implementation guide. Review Claude's suggestions and approve the updates. Don't let docs go stale.

Always¶

Document into the vault so that the next Claude session (yours or a teammate's) has full context. Claude reads the entire vault — the more complete it is, the better Claude performs for everyone.

Using Claude¶

Every team member uses Claude Code as their primary assistant. Claude:

• Reads the full vault — CLAUDE.md, planning docs, setup logs, runbooks. The entire vault is its context, not just one file.
• Has skills for common operations: /validate-docs, /add-service, /deploy-docs, /new-phase
• Enforces safety via hooks — can't accidentally edit secrets, warns on potential leaks
• Suggests documentation updates — after implementation work, Claude prompts: "These files may need updating: [list]. Want me to draft updates for your review?"
• Proposes context updates — when Claude detects drift between docs and reality (e.g., a new port, a changed IP, a reversed decision), it proposes updates to CLAUDE.md and planning docs, but always shows the diff and asks for confirmation first

How to use Claude effectively¶

• Start each session by telling Claude what you're working on and which phase/step
• Use skills:
  • /add-service — when deploying new services (generates all boilerplate: firewall rules, NPM config, tunnel route, stub docs)
  • /validate-docs — before merging any PR (catches broken links, missing images, leaked secrets)
  • /deploy-docs — when ready to publish (build, verify, commit, push)
  • /new-phase — when starting a new phase (scaffolds directory structure and templates)
• After every session: Claude will suggest which docs need updating. Review and approve.

The critical discipline¶

Claude's context dies when the session ends. The vault is what persists. If you and Claude generated configs, made decisions, or ran commands — make sure they're in the vault before you close the session.

Setup for New Team Members¶

Prerequisites: Git installed, GitHub account, added as collaborator on the repo, email added to Cloudflare Access for docs.exzentcg.com.

Setup (~5 minutes):

1. Clone the repo:

   git clone git@github.com:ExzenTCG/ExzenTCG-Homelab.git
   

2. Open the folder in Obsidian as a vault. All settings, plugins (including Obsidian Git), and formatting sync automatically from the committed config — no manual installation needed.

3. Open Claude Code in the repo directory. Claude auto-loads context from the vault. You're ready.

Parallel Editing (Avoiding Conflicts)¶

Each person works on their own branch, never directly on main:

1. Create a branch:

   git checkout -b draft/<your-name>-<topic>
   

2. Obsidian Git auto-commits and pushes to your branch every 10 minutes.
3. When done: create a Pull Request on GitHub to merge into main.
4. The owner reviews and merges. Cloudflare Pages auto-deploys.

Two people can edit simultaneously without conflicts — each on their own branch. Conflicts only surface at PR merge time, where GitHub highlights them and they're resolved deliberately.

The one rule: Never push directly to main. Always branch, then PR, then merge.

Writing Conventions¶

Folder Structure¶

Viewing the Docs¶

The vault is published to docs.exzentcg.com, gated behind Cloudflare Access. Log in with your authorised email (Google OAuth or one-time PIN).

The site auto-deploys when changes are merged to main. You don't need to run any build commands — just merge your PR and the site updates within a minute.

For local preview before pushing: zensical serve in the repo directory opens a local preview at http://localhost:8000.