hinata-z2 GitHub Repo — Specification

URL: https://github.com/mnnamah/hinata-z2
Purpose: Infrastructure-as-code for Z2 Proxmox VE deployment
Status: Clean structure, ready for population

What SHOULD be in hinata-z2

1. Commander Containers (LXC — one folder per container)

jimmy/                          # ct100 — jimmy-postgres (database, brain-ops)
├── config/
└── entrypoints/

mail-poller/                    # pending — IMAP pipeline (4 accounts)
├── config/
└── entrypoints/

heimerdinger-nlp/               # ct101 — NLP classifier (email + text)
├── config/
└── entrypoints/

itachi/                         # ct103 — Vaultwarden, credential management
├── config/
├── docker/                     # Vaultwarden Docker (inside LXC, not top-level)
│   └── docker-compose.yml
└── entrypoints/

zoro-sync/                      # pending — Bodybuilding tracker reconciliation
├── config/
├── scripts/
│   ├── reconcile_gym_data.py
│   └── update-bodybuilding.py
└── entrypoints/

Content:

Each folder maps to an LXC container named after its Hinata commander
Docker is used INSIDE containers where needed (Vaultwarden in Itachi) — NOT at orchestration level
Z2 uses Proxmox LXC, not Docker Compose, as the container runtime

2. Setup + Deployment Scripts

scripts/
├── proxmox-install.sh          # BIOS config + Proxmox VE 9.2 install
├── mount-sandpit-nfs.sh        # NFS mount Sandpit at /mnt/archive
├── sync-vault-from-icloud.sh   # Git clone hinata-v2 from GitHub
├── start-containers.sh         # Docker-compose up + health check
└── health-check.sh             # Verify poller + classifier running

Content:

Installation steps (executable, idempotent)
Environment setup (Tailscale join, static IP assignment)
Dependency checks (Git, Docker, NFS tools available)
Error handling + rollback instructions

3. Configuration Templates (Environment-Specific)

config/
├── .env.template               # Template for Z2-specific vars (IP, Tailscale name)
├── nfs-mount.template          # Template for /etc/exports entry on Mac
└── cron-schedule.template      # Pi cron template (mail-poller trigger)

Content:

Placeholders for: Z2 IP, Tailscale subnet, Sandpit IP, storage paths
Examples: SANDPIT_IP=192.168.1.100, Z2_STATIC_IP=192.168.1.50
Users copy .template → .env and fill in their values (NOT committed)

4. Documentation — NOT in Z2 repo

Documentation lives in the vault: projects/infrastructure/ for architecture docs, commander context.md files for per-agent docs. The Z2 repo contains only executable infrastructure code and config — no prose documentation.

5. Top-Level Files

.gitignore                       # STRICT: no credentials, data, logs
README.md                        # Repo overview + quick-start link
DEPLOYMENT_CHECKLIST.md          # Michael's checklist for Phase 1–3
LICENSE                          # Match hinata-v2 (if applicable)

What SHOULD NOT be in hinata-z2

❌ DO NOT include:

Item	Why	Alternative
Vault files (federation/, supreme-court/, the-government/, memory/)	Vault lives on iCloud; Z2 clones it via `git clone hinata-v2`	Z2 runs: `git clone https://github.com/mnnamah/hinata-v2.git`
Email archives (email-poller/*.json)	Data lives on Sandpit (4.2GB+); too large for git	Z2 NFS-mounts `/mnt/archive` to Sandpit
ML models (FAISS index, BERTopic pickle, embeddings)	Generated on Z2, stored on Z2 `/data/ml/`; not committed	Build models via `docker-compose up heim` (runs classifier)
Credentials (.json, .token, *.key)	NEVER commit secrets	Store in Z2 container `/etc/hinata/` with 0600 perms; manage via Itachi/Vaultwarden (CT103)
State cursors (imap-state-*.json)	Mutable; changes daily as poller fetches	Z2 poller writes to `/mnt/archive/data/mail/` (Sandpit NFS)
Logs (*.log, docker logs)	Runtime artifacts; not version-controlled	Container logs: `docker logs hinata-poller` (ephemeral)
IDE files (.vscode/, .idea/, *.swp)	Personal editor config	Already in .gitignore
iCloud sync config	Z2 is not the vault owner; vault syncs to iCloud	Vault managed on Mac via Obsidian; Z2 pulls read-only
Backups (vault snapshots, tar archives)	Bloats repo; use git history for vault, iCloud for vault backups	Sandpit → iCloud (automatic); vault → GitHub (automatic)

Repository Structure (Final — Commander Model)

hinata-z2/
├── jimmy/                      # ct100 — jimmy-postgres
│   ├── config/
│   └── entrypoints/
├── mail-poller/                # pending — IMAP pipeline
│   ├── config/
│   └── entrypoints/
├── heimerdinger-nlp/           # ct101 — NLP classifier
│   ├── config/
│   └── entrypoints/
├── itachi/                     # ct103 — Vaultwarden + credentials
│   ├── config/
│   ├── docker/                 # Vaultwarden Docker inside LXC
│   └── entrypoints/
├── scripts/                    # Z2 host-level scripts
├── config/                     # Host-level config templates
├── shared/                     # Cross-container utilities
├── .gitignore (STRICT)
└── README.md

NEVER:
  - federation/, supreme-court/, the-government/ (vault structure)
  - resources/, data/ (Sandpit data)
  - docs/ (documentation lives in vault)
  - *.log, .env (runtime artifacts)
  - credentials, tokens, keys

Sync Flow (How Z2 Uses These Repos)

Step 1 — Clone vault (one-time):
  $ git clone https://github.com/mnnamah/hinata-v2.git /home/hinata/vault

Step 2 — Clone infrastructure code (one-time):
  $ git clone https://github.com/mnnamah/hinata-z2.git /home/hinata/z2-infra

Step 3 — Configure environment:
  $ cp /home/hinata/z2-infra/config/.env.template /home/hinata/z2-infra/.env
  $ # Edit .env: fill in IP addresses, Tailscale name, Sandpit path

Step 4 — Mount Sandpit NFS (one-time):
  $ sudo /home/hinata/z2-infra/scripts/mount-sandpit-nfs.sh

Step 5 — Containers managed via Proxmox LXC (not Docker Compose):
  $ # LXC containers already running: pct list
  $ # Vaultwarden (inside ct103): docker compose -f /opt/hinata-z2/itachi/docker/docker-compose.yml up -d

Step 6 — Keep vault synced (daily cron):
  $ cd /home/hinata/vault && git pull origin main

Step 7 — Poller + Heim read from:
  - Vault: /home/hinata/vault (read-only configs, laws, context)
  - Sandpit: /mnt/archive (read-write email data, state cursors)

What's in hinata-v2 (for reference)

hinata-v2 (vault — local git repo, pushed to GitHub):

hinata-v2/
├── federation/           # Agent context + agent definitions (flat, 129 files)
├── supreme-court/        # Strategy, laws, governance, preferences
├── the-government/       # Diataxis-classified outputs (reference, how-to, tutorial, explanation)
├── inbox/                # Handover files, ingested content, pending classification
├── .claude/              # Settings, skills, hooks, commands
└── CLAUDE.md             # Root entry point — the global config

hinata-v2 lives locally on Mac; Z2 pulls from GitHub (mnnamah/hinata-v2).
hinata-v2 is NOT replicated in hinata-z2 repo — Z2 clones it read-only for config/law access.

Decommissioning: mnnamah/hinata-brain

The legacy repo https://github.com/mnnamah/hinata-brain is superseded by mnnamah/hinata-v2. Steps:

Verify no Z2 crons/scripts still reference hinata-brain.git
Update any Z2 clone paths: /home/hinata/vault should pull from hinata-v2
Archive the repo on GitHub (Settings → Archive)
After 30 days with no issues: delete

Connecting hinata-sandpit via project instances

mnnamah/hinata-sandpit connects to Z2 via Claude Code project instances (not as a vault clone):

Z2 containers that need Sandpit access mount it via NFS (/mnt/archive)
Cloud sessions that need Sandpit clone it into ~/Sandpit/hinata (hard-coded path)
Local sessions access it directly at /Users/nnamdi/Sandpit/hinata-sandpit/

The hinata-sandpit repo is the operational scripts layer — it does NOT duplicate vault content.

Security + Maturity Levels

Phase 1 (Prepare): .gitignore hardening

[ ] Credentials fully blocked (app-passwords, tokens, OAuth files)
[ ] Data paths blocked (resources/, data/, email-poller/)
[ ] Logs + runtime artifacts blocked
[ ] Test: git status shows no credentials, no data

Phase 2 (Install): Repo live + documented

[ ] All scripts executable, idempotent
[ ] All templates filled in with examples
[ ] docs/ complete + validated
[ ] First deployment checklist passed

Phase 3 (Migrate): Production-ready

[ ] 30-day stability run (containers running, vault synced, data consistent)
[ ] Credentials rotated (Outlook app-passwords + Graph OAuth tokens)
[ ] Monitoring + alerting live (health-check.sh in cron)
[ ] Ready for "migration maturity" (Z2 autonomous, Mac poller decommissioned)

Decision Gate: When to Delete hinata-v2 Clone from Z2

Phase 3 (HDD Installation) — DELETE VAULT CLONE:

[ ] Z2 HDD installed + populated with data from Sandpit
[ ] Containers switched to read from Z2 HDD (not NFS)
[ ] 7-day stability test on Z2 HDD passed
Action: rm -rf /home/hinata/vault
- Vault lives on iCloud/GitHub; Z2 no longer needs local copy
- Z2 becomes data node only (no vault, no cron git-pull)
- hinata-z2 repo is the ONLY Z2-specific code source

Phase 4 (Heim Classifier) — SANDPIT DEMOTION:

[ ] Heim classifier running stably on Z2 (Layers 1–4)
[ ] All 47K emails backfilled + classified
[ ] Z2 HDD proven reliable (no errors, no corruption)
Action: Sandpit → backup-only
- Weekly rsync pull from Z2 HDD: rsync -av /mnt/data/ ~/Sandpit/hinata/resources/
- Sandpit no longer mounted on Z2 (NFS unmount)
- Mac still has iCloud sync (vault backup), but Sandpit is secondary

Architecture progression:

Phase	Vault	Data	Purpose
1–2	Z2 clone (git pull)	Sandpit NFS	Operational; Z2 synced with iCloud
3	DELETED	Z2 HDD (primary)	Data node live; vault unneeded
4+	iCloud/GitHub only	Z2 HDD + Sandpit backup	Z2 autonomous; Sandpit is backup-only

hinata-z2 GitHub Repo — Specification ​

What SHOULD be in hinata-z2 ​

1. Commander Containers (LXC — one folder per container) ​

2. Setup + Deployment Scripts ​

3. Configuration Templates (Environment-Specific) ​

4. Documentation — NOT in Z2 repo ​

5. Top-Level Files ​

What SHOULD NOT be in hinata-z2 ​

❌ DO NOT include: ​

Repository Structure (Final — Commander Model) ​

Sync Flow (How Z2 Uses These Repos) ​

What's in hinata-v2 (for reference) ​

Decommissioning: mnnamah/hinata-brain ​

Connecting hinata-sandpit via project instances ​

Security + Maturity Levels ​

Phase 1 (Prepare): .gitignore hardening ​

Phase 2 (Install): Repo live + documented ​

Phase 3 (Migrate): Production-ready ​

Decision Gate: When to Delete hinata-v2 Clone from Z2 ​

hinata-z2 GitHub Repo — Specification

What SHOULD be in hinata-z2

1. Commander Containers (LXC — one folder per container)

2. Setup + Deployment Scripts

3. Configuration Templates (Environment-Specific)

4. Documentation — NOT in Z2 repo

5. Top-Level Files

What SHOULD NOT be in hinata-z2

❌ DO NOT include:

Repository Structure (Final — Commander Model)

Sync Flow (How Z2 Uses These Repos)

What's in hinata-v2 (for reference)

Decommissioning: mnnamah/hinata-brain

Connecting hinata-sandpit via project instances

Security + Maturity Levels

Phase 1 (Prepare): .gitignore hardening

Phase 2 (Install): Repo live + documented

Phase 3 (Migrate): Production-ready

Decision Gate: When to Delete hinata-v2 Clone from Z2