docs: Update docs for the correctness (#13)

services/docs/content/en/root/concepts/_index.md

@@ -4,7 +4,7 @@ description: Theoretical foundations, architecture, and security models.
 weight: 10
 ---
 
-Theoretical foundations, architecture, and security models for the Root infrastructure framework.
+Theoretical foundations, architecture, and security models for the ermnvldmr.com root deployment commons framework.
 
 {{% cards %}}
 {{< card link="principles" title="Infrastructure principles" icon="book-open" subtitle="Predictability, minimal dependencies, and decentralization." >}}

services/docs/content/en/root/concepts/architecture.md

@@ -33,16 +33,31 @@ The framework is typically deployed as a shared [Commons](/root/glossary#commons
 {{< filetree/container >}}
 {{< filetree/folder name="configs-repo" state="open" >}}
   {{< filetree/folder name=".operator" state="open" >}}
-    {{< filetree/folder name="shared" >}}
-      {{< filetree/file name="root (dispatcher)" >}}
+    {{< filetree/folder name="shared (submodule)" state="open" >}}
+      {{< filetree/folder name="scripts" >}}
+        {{< filetree/folder name="run" >}}
+          {{< filetree/file name="root (dispatcher)" >}}
+        {{< /filetree/folder >}}
+        {{< filetree/folder name="lib" >}}
+          {{< filetree/file name="shared libraries" >}}
+        {{< /filetree/folder >}}
+        {{< filetree/folder name="actions" >}}
+          {{< filetree/file name="shared actions" >}}
+        {{< /filetree/folder >}}
+      {{< /filetree/folder >}}
     {{< /filetree/folder >}}
-    {{< filetree/folder name="local" >}}
-      {{< filetree/file name="node-specific actions" >}}
+    {{< filetree/folder name="local" state="open" >}}
+      {{< filetree/folder name="scripts" >}}
+        {{< filetree/folder name="actions" >}}
+          {{< filetree/file name="node-specific overrides" >}}
+        {{< /filetree/folder >}}
+      {{< /filetree/folder >}}
     {{< /filetree/folder >}}
   {{< /filetree/folder >}}
-  {{< filetree/folder name="node-1" >}}
+  {{< filetree/folder name="daedalus (node)" >}}
     {{< filetree/file name="docker-compose.yml" >}}
   {{< /filetree/folder >}}
+  {{< filetree/file name="init.sh (bootstrap)" >}}
 {{< /filetree/folder >}}
 {{< /filetree/container >}}
 

services/docs/content/en/root/concepts/security-model.md

@@ -6,29 +6,62 @@ weight: 20
 
 Security in Root is achieved through strict privilege isolation and project-level "sandboxing" to mitigate the impact of service compromises.
 
-## The "No-Root" principle {#noroot}
+## The "No-Root" Principle {#noroot}
 
 Running applications as `root` inside containers is a significant security risk. The framework enforces isolation via the `tiers/useradd` and `tiers/chown` actions.
 
 ### Project-specific users
 
-Every project (e.g., `traefik`, `synapse`) is assigned a dedicated system user on the host. 
+Every project located at `{repository root}/{node}/{project}` is assigned a dedicated system user on the host. 
 
 - **Isolation**: If a container is compromised, the attacker only gains the privileges of that specific low-privileged user.
 - **Filesystem safety**: Projects can only read/write to their own directories within the [Tiers](/root/glossary#tier).
 
 ## Docker socket protection {#socket-protection}
 
-Direct access to `/var/run/docker.sock` is equivalent to root access on the host. To prevent services from abusing this access, the framework utilizes a **Socket Proxy**.
+Direct access to `/var/run/docker.sock` is equivalent to root access on the host. As a best practice, it is highly recommended to protect the Docker socket. One way to achieve this is by utilizing a **Socket Proxy** (e.g., based on `tecnativa/docker-socket-proxy`) to filter and restrict access to the Docker API.
 
-- **Restricted API**: The proxy filters Docker API calls, allowing only necessary operations (e.g., `GET containers`) and blocking dangerous ones (e.g., `POST containers/create`).
+```yaml filename="docker-socket-proxy-example.yml"
+services:
+  socket-proxy:
+    image: tecnativa/docker-socket-proxy:0
+    container_name: root-socket-proxy
+    user: "0:0"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    environment:
+      CONTAINERS: 1
+      SERVICES: 1
+      TASKS: 1
+    networks:
+      socket: {}
+    restart: unless-stopped
+
+  traefik:
+    # ...
+    depends_on:
+      - socket-proxy
+    command:
+      # Use the proxy instead of the local socket
+      - "--providers.docker.endpoint=tcp://root-socket-proxy:2375"
+    networks:
+      socket: {}
+```
+
+## Security Monitoring (CrowdSec) {#crowdsec}
+
+The framework integrates **CrowdSec** for behavioral detection and automated response.
+
+- **Intrusion detection**: CrowdSec monitors logs from [Traefik](https://traefik.io/) and SSH for suspicious patterns (e.g., brute-force attacks, port scanning).
+- **Automated blocking**: When a threat is detected, the **CrowdSec Firewall Bouncer** automatically updates [UFW](https://help.ubuntu.com/community/UFW) rules to block the malicious IP at the host level.
+- **Shared threat intelligence**: CrowdSec shares anonymized threat data with its community, providing preemptive protection against known bad actors.
 
 ## Network hardening {#networking}
 
 Root uses `configure/ufw` to implement a "Default Deny" policy.
 
-- **Internal routing**: Services communicate over a dedicated `root-direct` bridge network.
-- **TProxy integration**: Outgoing traffic is routed through Xray for enclave-like isolation and granular routing rules.
+- **Internal routing**: Services communicate over a dedicated `root-proxy` bridge network, which is often configured as `internal: true`.
+- **Enclave isolation**: Outgoing traffic can be routed through a dedicated egress node for granular control.
 
 ---
 

services/docs/content/en/root/concepts/tiered-storage.md

@@ -8,37 +8,67 @@ The framework enforces a standardized storage taxonomy. This ensures that every
 
 ## The storage taxonomy {#taxonomy}
 
-Data is divided into three logical [Tiers](/root/glossary#tier) based on its lifecycle, volume, and importance.
+Data is divided into three logical [Tiers](/root/glossary#tier) based on its performance requirements, lifecycle, and importance.
 
-### Tier 1: Configuration & critical state
+### Tier 1: Configuration & Cache
 
 **Path:** `${ROOT_NODE_DIR}/@tier1`
 
-- **Contents**: Config files, small SQLite databases, SSL certificates.
-- **Characteristics**: Extremely high value, low volume.
-- **Backup strategy**: Frequent (hourly/daily), long retention.
+- **Contents**: Config files, small SQLite databases, SSL certificates, application cache.
+- **Characteristics**: Extremely high value, low to medium volume, requires low latency.
+- **Hardware**: High-speed SSD storage, typically shared with the Operating System.
 
-### Tier 2: Application data
+### Tier 2: Application Data
 
 **Path:** `${ROOT_NODE_DIR}/@tier2`
 
 - **Contents**: User uploads, large databases, persistent application state.
-- **Characteristics**: High value, medium to high volume.
-- **Backup strategy**: Daily, prioritized for integrity.
+- **Characteristics**: High value, medium to high volume, requires high reliability.
+- **Hardware**: Reliable HDD clusters, RAID arrays, or dedicated storage compute.
 
-### Tier 3: Transients & bulk media
+### Tier 3: Transients & Bulk Media
 
 **Path:** `${ROOT_NODE_DIR}/@tier3`
 
-- **Contents**: Logs, caches, temporary files, bulk media downloads.
-- **Characteristics**: Low value, high volume.
-- **Backup strategy**: Minimal or none. These directories are typically excluded from sync operations.
+- **Contents**: Logs, temporary files, bulk media (movies, music), and other non-critical large data.
+- **Characteristics**: Low value, very high volume.
+- **Hardware**: High-capacity HDDs optimized for continuous sequential write/read (e.g., WD Purple). Note that Tier 3 is **too slow for cache**.
+
+## Backup strategy {#backup}
+
+The framework does not enforce a specific backup strategy or provide a default implementation, allowing for complete node-specific flexibility. Operators are expected to implement their own backup logic.
+
+### Example: Restic backup
+
+A common best practice is to use **Restic** for backups. For example, you might create an operator compose file to run Restic:
+
+```yaml filename="operator-compose.yml"
+services:
+  restic:
+    image: restic/restic:0.18.1
+    container_name: operator-restic
+    volumes:
+      - ./@tier2/{project}/{service}/{data}:/data/@tier2/{project}/{service}/{data}:ro
+      - ./@tier1/{project}/{service}/{data}:/data/@tier1/{project}/{service}/{data}:ro
+      - ./@tier1/.operator/restic/cache:/var/restic-cache
+    environment:
+      RESTIC_REPOSITORY: "s3:example.com/bucket"
+      RESTIC_PASSWORD: ${RESTIC_PASSWORD}
+      # ... AWS/S3 credentials
+    network_mode: "host"
+    entrypoint: [ "restic" ]
+    user: "0:0"
+```
+
+### Implementing the strategy
+
+Operators can implement this strategy by defining a local action in `.operator/local/scripts/actions/sync/tiers`. The `root` dispatcher can then execute this script to trigger the backup, allowing for granular control over how data is persisted.
 
 ## Justification {#justification}
 
-1. **Backup efficiency**: By separating logs (Tier 3) from configs (Tier 1), we avoid wasting storage space on redundant backups of transient data.
-2. **Hardware optimization**: Tier 1 and 2 can be placed on fast SSD storage, while Tier 3 can be mounted on slower, high-capacity HDDs.
-3. **Instant understanding**: Any operator can enter a [Node](/root/glossary#node) directory and immediately know where the critical data resides.
+1. **Hardware optimization**: By mapping tiers to specific hardware (SSDs for Tier 1, RAID for Tier 2, Purples for Tier 3), we optimize for both performance and cost.
+2. **Selective backup**: Separating transient logs and bulk media (Tier 3) from critical configs (Tier 1) prevents wasting expensive backup storage.
+3. **Architectural clarity**: Any operator can inspect a [Node](/root/glossary#node) directory and immediately understand the storage requirements and priority of its contents.
 
 ---