# nuclide.systems docs

Single source of truth for the homelab. Git-tracked since 2026-05-20.

## Read this first
- **[`/CLAUDE.md`](../CLAUDE.md)** (host root) — operator doctrine for any AI agent SSHing in. Skim before touching anything.
- **[`CHANGELOG.md`](CHANGELOG.md)** — what changed and when.
- **[`ct-inventory.md`](ct-inventory.md)** — canonical roster of LXCs / VM, IPs, role, sizing.

## Layout

```
/docs/
├── README.md                  ← you are here
├── CHANGELOG.md               ← dated bullets of every infra change
├── ct-inventory.md            ← LXC/VM roster (single source of truth)
│
├── infra/                     ← host-level + cross-cutting state
│   └── proxmox-state.md       ← the 900-line master state doc (sizing, ZFS, NFS, DNS)
│
├── services/                  ← per-service operational docs (current truth)
│   ├── homelab-architecture.md   topology + design rationale
│   ├── dev-environment.md        Coder + Gitea on CT 111
│   ├── mcp-gateway.md            MCP gateway on CT 104
│   ├── comfyui.md
│   ├── zoraxy.md                 reverse proxy
│   ├── adguard-dns.md            DNS + rewrites
│   ├── cloud-gpu.md              GPU passthrough + future external GPU
│   └── pocket-id.md              [planned] OIDC IdP + client registry
│
├── stacks/                    ← CT 104 docker stacks notes
│   ├── PORTMAP.md             canonical service → port → public hostname registry
│   ├── CLAUDE.md              agent breadcrumbs (CT 104 specific)
│   ├── storage.md             [being rewritten] storage class per service
│   ├── volumes.md             [being rewritten] volume bindings per stack
│   ├── docker-networks.md
│   └── todo.md
│
├── history/                   ← frozen / archived
│   ├── traefik-migration.md                  ABANDONED 2026-05-16 (Zoraxy chosen)
│   ├── traefik-migration-docker-labels.md    ABANDONED 2026-05-16
│   ├── mcp-gateway-requirements.md           SUPERSEDED by services/mcp-gateway.md
│   ├── scrubbing-list-2026-05-17.md          snapshot of cleanup pass
│   └── case-study.md                         narrative writeup
│
└── ideas/
    └── stack-ideas.md
```

## Operating principles
See [`/CLAUDE.md`](../CLAUDE.md) for the full doctrine. Highlights:
1. Keep services running; surface synergies and gaps.
2. Enforce consistency: Pocket-ID OIDC, Zoraxy + ACME, `<svc>.nuclide.systems`, secrets in `.env`.
3. Plan rollback at medium+ risk (ZFS snapshots, fresh experimental CTs).
4. Every service should be AI-accessible (MCP / Coder workspace CLI / documented API).
5. Test end-to-end before declaring done.
6. Generate slash commands for recurring maintenance.

## Quick links
- Pocket-ID admin: `https://id.nuclide.systems`
- Gitea: `https://git.nuclide.systems`
- Coder: `https://dev.nuclide.systems`
- Nextcloud: `https://nc.nuclide.systems`
- MCP gateway: `https://mcp.nuclide.systems`
- Zoraxy admin: CT 108 (operator-only; **always confirm before any change** — see `[[feedback_zoraxy_confirm]]`)
- Proxmox PVE: `https://192.168.1.20:8006`

## Repo + rendered site
- Source: `https://git.nuclide.systems/fkrebs/docs`
- Rendered (LAN-only, no Zoraxy route): `http://192.168.1.42:13080`
- Build: docs-server container on CT 111 polls Gitea every 5 min; rebuilds with mkdocs Material on every push.