docs: add full homelab documentation structure

README.md

@@ -1,35 +1,60 @@
 # truenas-stacks
 
-Docker Compose stacks for PlausibleDeniability (TrueNAS Scale).
+Docker Compose stacks for PlausibleDeniability (TrueNAS Scale), plus documentation for the full homelab.
 
-## Stacks
+## Servers
 
-- databases/ - shared-postgres, shared-mariadb, shared-redis - deploy FIRST
-- infrastructure/ - newt, homepage, uptime-kuma, dockhand, netdata, tailscale - deploy SECOND
-- media/ - plex, tautulli, audiobookshelf, seerr, calibre-web
-- photos/ - immich server + machine learning
-- home/ - kitchenowl, donetick, dakboard bridge, shlink, qui
-- dev/ - gitea, rackpeek
-- ai/ - ollama, openwebui, scriberr
+| Server | Role | OS | IP |
+|--------|------|----|----|
+| Serenity | NAS / Media ingestion | Unraid 7.2.4 | 10.5.1.5 |
+| PlausibleDeniability | Primary Docker host | TrueNAS Scale 25.10.2.1 | LAN DHCP |
+| N.O.M.A.D. | Offline knowledge + game servers | Ubuntu 25.10 | 10.5.1.16 |
 
-## Deployment order
+## Repo Layout
 
-1. databases
-2. infrastructure
-3. All other stacks in any order
+```
+databases/       # shared-postgres, shared-mariadb, shared-redis — deploy FIRST
+infrastructure/  # newt, homepage, uptime-kuma, dockhand, netdata, tailscale — deploy SECOND
+media/           # plex, tautulli, audiobookshelf, seerr, calibre-web-automated
+photos/          # immich server + machine learning
+home/            # kitchenowl, donetick, shlink, qui, dakboard bridges
+dev/             # gitea, rackpeek
+ai/              # ollama, openwebui
+meshtastic/      # meshmonitor, mqtt-proxy, tileserver, meshtastic-map
+automation/      # planned: gotify, n8n
+search/          # planned: qdrant
+docs/            # all homelab documentation
+```
 
-## Setup on a new machine
+## Quick Start
 
-    git clone git@github.com:Paccoco/truenas-stacks.git /mnt/docker-ssd/docker/compose
-    cp databases/.env.example databases/.env && nano databases/.env
-    # repeat for each stack, then import each truenas-app.yaml via TrueNAS Apps UI
+1. Deploy `databases/` first
+2. Deploy `infrastructure/` second (creates pangolin network via newt)
+3. Deploy remaining stacks in any order
 
-## Networks
+```bash
+cd /mnt/docker-ssd/docker/compose/<stack>
+docker compose --env-file .env config   # validate
+docker compose --env-file .env up -d    # deploy
+```
 
-- ix-databases_shared-databases: created by databases stack, used by media/photos/home/dev/ai
-- pangolin: created by newt at runtime, used by any service exposed via reverse proxy
+## Documentation
 
-## Secrets
-
-.env files are gitignored. .env.example files are committed with placeholder values.
-Real .env files live only on TrueNAS at /mnt/docker-ssd/docker/compose/<stack>/.env
+- [Architecture Overview](docs/architecture/ARCHITECTURE_OVERVIEW.md)
+- [Networking Model](docs/architecture/NETWORKING_MODEL.md)
+- [Hardware Inventory](docs/architecture/HARDWARE_INVENTORY.md)
+- [Services Directory](docs/architecture/SERVICES_DIRECTORY.md)
+- [Stack Standards](docs/operations/STACK_STANDARDS.md)
+- [Deployment Checklist](docs/operations/DEPLOYMENT_CHECKLIST.md)
+- [Storage Notes](docs/operations/DOCKERSTACK_STORAGE_NOTES.md)
+- [Backup Policy](docs/operations/BACKUP_POLICY.md)
+- [Secrets Management](docs/operations/SECRETS_MANAGEMENT.md)
+- [Troubleshooting](docs/troubleshooting/TROUBLESHOOTING.md)
+- [Known Quirks](docs/troubleshooting/KNOWN_QUIRKS.md)
+- [Expansion Plan](docs/planning/HOMELAB_EXPANSION_PLAN.md)
+- [TODO](docs/planning/TODO.md)
+- [Serenity](docs/servers/SERENITY.md)
+- [PlausibleDeniability](docs/servers/PLAUSIBLEDENABILITY.md)
+- [N.O.M.A.D.](docs/servers/NOMAD.md)
+- [Meshtastic Stack](docs/reference/MESHTASTIC.md)
+- [AI Context](docs/reference/HOMELAB_AI_CONTEXT.md)