docs: add comprehensive technical architecture specs for DSH, Portal, and Host Ports

docs/README.md

@@ -1,8 +1,24 @@
-# Docs
+# Family Home Lab Technical Documentation
 
-Future phase — document/library tools (e.g. paperless-ngx, BookStack, or an internal wiki).
+This directory contains architectural specifications, component manuals, integration tables, and network registries for the Family Home Lab ecosystem.
 
-- Category colour assigned: teal `#2a9d99`.
-- No service ships from this folder yet; design decisions belong in plan.md/AGENT.md
-  when a tool is chosen.
-- User permission flag (`can_docs`) already exists in the portal user model, default off.
+## Core Technical Reference Specs
+
+- **[DeepSeek Harness (DSH) Architecture](dsh-architecture.md)**:
+  Multi-instance chat engine, per-user container allocation (`sam`, `jo`, `harry`, `finn`), ports (`3081–3084`), JSON session persistence, multi-model routing table (OmniRoute, OpenRouter, Whisper, Jervis Voice Agent), CSP framing, and API endpoints.
+
+- **[Console Portal Architecture](portal-architecture.md)**:
+  FastAPI application spec, user database schema, access control entitlement flags (`can_chat`, `can_image`, `can_audio`, `can_docs`), tool catalogue structure (`tools.py`), host-side `service-controller` bridge, ON/OFF RAM management, and Garage S3 file integration.
+
+- **[Host Network & Port Registry](host-network-ports.md)**:
+  Single source of truth network topology and port allocations across hosts `.13` (containers/models), `.35` (Caddy/Gitea/Outline), `.27` (dev workstation), and `.51`.
+
+---
+
+## Component Plans & Features
+
+- **[Audio Plan](audio-plan.md)**: MIDI transcription (Basic Pitch) and sheet music generation (MuScriptor).
+- **[DSH Plugins Shortlist](dsh-plugins.md)**: Curated index of DeepSeek Harness extension plugins.
+- **[DSH Plugin Plan](dsh-plugin-plan.md)**: Roadmap for integrating summary and media plugins into DSH.
+- **[Websites & Services Inventory](websites.md)**: Catalogue of public domains and upstream destinations.
+- **[Interactive Architecture Map](family-home-lab-map.html)**: Visual HTML component map.