docs: Update docs for the correctness (#13)

2026-04-15 00:48:06 +03:00
1 parent 8dba55272c
commit 51a783f93a
@@ -320,7 +320,7 @@ Use GitHub-flavored alerts for emphasis.
 ## 6. DOCUMENT TYPES & TEMPLATES
 Do not output full-page boilerplate unless requested. Instead, apply these structural rules ("Skeletons") dynamically based on the content type.
-This is also serves as the fixed categories which should populate every project's docs: Getting Started, Guides, Recipes, Concepts, Troubleshooting.
+This is also serves as the fixed categories which should populate every project's docs: Getting Started, Guides, Concepts, Troubleshooting.
 ### 6.1 General Skeleton (All Docs)
@@ -349,7 +349,7 @@ This is also serves as the fixed categories which should populate every project'
 3. **Procedure:** Strict numbered steps (or `{{% steps %}}`).
 4. **Result Control:** How to verify success.
-### 6.4 How-to / Recipe (Task-Oriented)
+### 6.4 How-to / Guide (Task-Oriented)
 - **Goal:** Solve a specific problem.
 - **Structure:**
@@ -7,6 +7,6 @@ title: "Ermnvldmr's Documentation"
 Welcome to the unified documentation for my own projects
 {{< cards >}}
-{{< card link="root" title="root.ermnvldmr.com" icon="server" subtitle="Documentation for root.ermnvldmr.com infrastructure" >}}
+{{< card link="root" title="ermnvldmr.com-root-commons" icon="server" subtitle="Documentation for the root deployment commons framework" >}}
 {{< card link="quetza" title="Quetza Bot" icon="terminal" subtitle="Modular Discord bot framework documentation" >}}
 {{< /cards >}}
@@ -1,6 +1,6 @@
 ---
 title: Conversational AI Integration
-weight: 2
+weight: 4
 ---
 **Goal:** Integrate Large Language Models (LLMs) while managing context and Discord's timeout constraints.
@@ -51,5 +51,6 @@ export async function execute(interaction, controller) {
 }
 ```
-> [!WARNING] > **API Costs:**
+> [!WARNING]
 > **API Costs:**
 > AI APIs are often billed by token. Implement strict user-based rate limits in your Controller to prevent abuse.
@@ -65,7 +65,8 @@ Once running, use these mechanisms to check health:
 - **`/ping` Command:** Verifies network latency and API responsiveness.
 - **`/modules` Command:** Lists all loaded modules to confirm feature availability.
-> [!WARNING] > **Scaling Constraint:**
+> [!WARNING]
 > **Scaling Constraint:**
 > Quetza follows a single-instance-per-token model. Do not run multiple instances with the same token, as this will cause WebSocket conflicts.
 ---
@@ -1,6 +1,6 @@
 ---
 title: Interactive Voice Features
-weight: 1
+weight: 3
 ---
 **Goal:** Implement sophisticated voice interactions that respect guild boundaries and manage ephemeral resources.
@@ -32,7 +32,8 @@ Audio sessions are ephemeral.
 - **Transient State:** Active audio stream (Lost on disconnect).
 - **Durable State:** Queue/Playlist (Persisted in Controller until restart).
-> [!TIP] > **Resilience:** Separate the _Queue_ logic from the _Voice Connection_ logic. This allows the bot to reconnect without losing the user's playlist.
+> [!TIP]
 > **Resilience:** Separate the _Queue_ logic from the _Voice Connection_ logic. This allows the bot to reconnect without losing the user's playlist.
 ## 4. Implementation Sketch
@@ -1,13 +0,0 @@
 ---
 title: Recipes
 weight: 3
 ---
 **Quetza** recipes are strategic architectural patterns for common functional requirements. They focus on _how_ to compose framework features to solve business problems.
 ## Recipe Categories
 {{% cards %}}
 {{< card link="voice-features" title="Interactive Voice Features" icon="users" subtitle="Managing audio players and guild-scoped state." >}}
 {{< card link="conversational-ai" title="Conversational AI" icon="chip" subtitle="Handling LLM context and long-running responses." >}}
 {{% /cards %}}
@@ -22,18 +22,15 @@ weight: 1
 **Symptom:** `/command` does not appear in Discord.
-### Global vs. Guild Registration
+### Global vs. Test Guild Registration
- **Global:** Takes up to 1 hour to propagate.
+- **Global:** Commands pushed to the application globally can take up to 1 hour to propagate and are subject to stricter rate limits.
- **Guild:** Instant update.
+- **Test Guild:** Quetza automatically pushes commands to a specific guild in development mode for instant updates.
-  - **Fix:** Set `DEV_GUILD_ID` in your `.env` for development.
+  - **Requirement:** Ensure `NODE_ENV=development` and `DEV_GUILD_ID` is correctly set in your `.env`.
-### Data Malformation
+### Rate Limits
-Discord rejects invalid command structures silently or with generic errors.
+Frequent updates to global commands may trigger Discord's rate limits. Use a test guild for iterative development.
 - **Name:** Must be lowercase, alphanumeric, `-` only.
 - **Description:** Required, max 100 chars.
 ## 3. Interaction Failures
@@ -71,5 +68,6 @@ Check your Controller.
 - **Multiple:** Events are additive. Did you register the same handler in two modules?
 - **None:** Did you export `name` and `execute` correctly?
-> [!TIP] > **Debug Mode:**
+> [!TIP]
 > **Debug Mode:**
 > Enable verbose logging to see exactly which modules and commands are loaded at startup.
@@ -1,13 +1,13 @@
 ---
-title: Root Infrastructure
+title: Documentation of ermnvldmr.com root deployment commons
-description: Documentation for the root.ermnvldmr.com infrastructure.
+description: Documentation for the ermnvldmr.com root deployment commons framework.
 weight: 1
 type: docs
 cascade:
  type: docs
 ---
-The engine powering the shared infrastructure of `root.ermnvldmr.com`. This framework provides a minimal-dependency deployment environment for independent, self-hosted projects. 
+The `ermnvldmr.com-root-commons` framework provides a minimal-dependency deployment environment for independent, self-hosted projects.
 The generic logic, scripts, and deployment patterns used across multiple unrelated self-hosted applications are stored in the [GitHub: ermnvldmr.com-root-commons](https://github.com/deytenit/ermnvldmr.com-root-commons) repository.
@@ -23,7 +23,6 @@ The generic logic, scripts, and deployment patterns used across multiple unrelat
 {{% cards %}}
 {{< card link="concepts" title="Concepts" icon="book-open" subtitle="Theoretical foundations, architecture, and security models." >}}
 {{< card link="guides" title="Guides" icon="map" subtitle="Step-by-step guides for installation and action development." >}}
 {{< card link="recipes" title="Recipes" icon="beaker" subtitle="Collection of step-by-step procedures for infrastructure maintenance and deployment." >}}
 {{< card link="reference" title="Reference" icon="code" subtitle="API and technical references for developers." >}}
 {{% /cards %}}
@@ -32,4 +31,3 @@ The generic logic, scripts, and deployment patterns used across multiple unrelat
 **See also:**
 - [GitHub: ermnvldmr.com-root-commons](https://github.com/deytenit/ermnvldmr.com-root-commons)
 - [GitHub: root.ermnvldmr.com](https://github.com/deytenit/root.ermnvldmr.com)
@@ -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." >}}
@@ -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/folder name="shared (submodule)" state="open" >}}
-      {{< filetree/file name="root (dispatcher)" >}}
+      {{< 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/folder name="local" state="open" >}}
-      {{< filetree/file name="node-specific actions" >}}
+      {{< 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 >}}
@@ -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.
+- **Internal routing**: Services communicate over a dedicated `root-proxy` bridge network, which is often configured as `internal: true`.
- **TProxy integration**: Outgoing traffic is routed through Xray for enclave-like isolation and granular routing rules.
+- **Enclave isolation**: Outgoing traffic can be routed through a dedicated egress node for granular control.
 ---
@@ -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.
+- **Contents**: Config files, small SQLite databases, SSL certificates, application cache.
- **Characteristics**: Extremely high value, low volume.
+- **Characteristics**: Extremely high value, low to medium volume, requires low latency.
- **Backup strategy**: Frequent (hourly/daily), long retention.
+- **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.
+- **Characteristics**: High value, medium to high volume, requires high reliability.
- **Backup strategy**: Daily, prioritized for integrity.
+- **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.
+- **Contents**: Logs, temporary files, bulk media (movies, music), and other non-critical large data.
- **Characteristics**: Low value, high volume.
+- **Characteristics**: Low value, very high volume.
- **Backup strategy**: Minimal or none. These directories are typically excluded from sync operations.
+- **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.
+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. **Hardware optimization**: Tier 1 and 2 can be placed on fast SSD storage, while Tier 3 can be mounted on slower, high-capacity HDDs.
+2. **Selective backup**: Separating transient logs and bulk media (Tier 3) from critical configs (Tier 1) prevents wasting expensive backup storage.
-3. **Instant understanding**: Any operator can enter a [Node](/root/glossary#node) directory and immediately know where the critical data resides.
+3. **Architectural clarity**: Any operator can inspect a [Node](/root/glossary#node) directory and immediately understand the storage requirements and priority of its contents.
 ---
@@ -4,9 +4,10 @@ description: Step-by-step guides for installation and action development.
 weight: 20
 ---
-Step-by-step guides for installing and developing within the Root infrastructure framework.
+Step-by-step guides for installing and developing within the ermnvldmr.com root deployment commons framework.
 {{% cards %}}
-{{< card link="installation" title="Installation" icon="arrow-down" subtitle="Initial setup of the Root framework on a new host." >}}
+{{< card link="first-node" title="Setting Up Your First Node" icon="map" subtitle="Practical guide to creating your own config repository." >}}
 {{< card link="installation" title="Installation" icon="arrow-down" subtitle="Initial setup of the framework on a new host." >}}
 {{< card link="action-development" title="Action development" icon="code" subtitle="Creating and managing atomic automation tasks." >}}
 {{% /cards %}}
@@ -0,0 +1,190 @@
 ---
 title: "Setting Up Your First Node"
 description: A practical guide on creating your first node and hooking up the deployment commons.
 weight: 25
 ---
 **Goal:** Create a configuration repository for your infrastructure, add the root deployment commons as a submodule, and define your first basic node.
 ## 1. Creating the Configuration Repository
 Your infrastructure should be managed from a single Git repository. This repository will hold the configuration for all your servers (nodes).
 {{% steps %}}
 ### Step 1: Initialize the repository
 Create a new directory and initialize Git.
 ```bash
 mkdir my-infrastructure
 cd my-infrastructure
 git init
 ```
 ### Step 2: Add the commons submodule
 The `ermnvldmr.com-root-commons` must be placed at `.operator/shared`.
 ```bash
 mkdir -p .operator
 git submodule add https://github.com/deytenit/ermnvldmr.com-root-commons.git .operator/shared
 ```
 ### Step 3: Create the Bootstrap Script
 Create an `init.sh` file at the root of your repository. This script links the commons framework into your local environment.
 ```bash filename="init.sh"
 #!/usr/bin/env bash
 # init.sh
 # Source common utilities from the submodule
 source "$(git -C "$(dirname "$0")" rev-parse --show-toplevel)/.operator/shared/scripts/lib/common.sh"
 SCRIPT_NAME="init"
 navigate_to_repo_root
 log_info "Setting up Git hooks..."
 git config core.hooksPath .operator/shared/githooks
 git config --global --add safe.directory "${REPO_ROOT}"
 log_info "Setting up PATH for the root dispatcher..."
 ABSOLUTE_RUN_DIR="$(realpath "${REPO_ROOT}/.operator/shared/scripts/run")"
 BASHRC_ENTRY="export PATH=\"${ABSOLUTE_RUN_DIR}:\$PATH\""
 sed -i '/\.operator\/shared\/scripts\/run/d' ~/.bashrc
 echo "$BASHRC_ENTRY" >> ~/.bashrc
 log_info "Done. Please run 'source ~/.bashrc' or re-login to your shell."
 ```
 Make it executable:
 ```bash
 chmod +x init.sh
 ```
 {{% /steps %}}
 ## 2. Defining Your First Node
 A Node is a folder at the repository root that represents one physical or virtual server.
 ### Node Structure
 Let's create a node named `daedalus`. Inside, we'll define an operator configuration (e.g., for backups) and a core service.
 ```bash
 mkdir -p daedalus/.operator/configs/{cron,crowdsec,systemd,ufw/docker,ufw/host}
 mkdir -p daedalus/root
 ```
 ### Base Configurations (Optional)
 You can place configuration files (like UFW rules or a crontab) inside the `daedalus/.operator/configs/` directory. For example, a basic crontab:
 ```bash filename="daedalus/.operator/configs/cron/crontab.template"
 # Run backups every night at 3:00 AM
 0 3 * * * root sync tiers daedalus
 ```
 ## 3. Configuring Services (Docker Compose)
 The framework relies on `docker-compose.yml` to orchestrate services.
 ### Node-Level Infrastructure (Operator)
 The `daedalus/docker-compose.yml` file runs infrastructure utilities, such as `restic` for backups or VPN agents. This compose file has direct access to the filesystem via `@tierX` mounts.
 ```yaml filename="daedalus/docker-compose.yml"
 name: 'operator'
 services:
  restic:
    image: restic/restic:0.18.1
    container_name: operator-restic
    volumes:
      # Example: mounting project data for backups (Read-Only)
      - ./@tier2/my-app/data:/data/@tier2/my-app/data:ro
      - ./@tier3/.operator/restic/cache:/var/restic-cache
    environment:
      RESTIC_REPOSITORY: "s3:example.com/my-bucket/daedalus"
      RESTIC_PASSWORD: "${RESTIC_PASSWORD?error}"
      # AWS credentials...
    network_mode: "host"
    entrypoint: [ "restic" ]
 ```
 ### The Root Project
 The `root` project typically contains your reverse proxies (Traefik) and core services that other projects will route through.
 ```yaml filename="daedalus/root/docker-compose.yml"
 name: root
 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:
    image: traefik:3.6
    container_name: root-traefik
    # UID and GID are automatically populated by the framework after running 'root tiers useradd'
    user: "${UID?error}:${GID?error}"
    group_add:
      - "${SHARED_GID?error}"
    depends_on:
      - socket-proxy
    volumes:
      - ./@tier1/shared/root/traefik/letsencrypt:/letsencrypt
      - ./@tier3/traefik/logs:/logs
      - ./@tier1/traefik/dynamic:/etc/traefik/dynamic:ro
    ports:
      - '0.0.0.0:80:80'
      - '0.0.0.0:443:443'
    networks:
      proxy: {}
      socket: {}
    command:
      - "--api.dashboard=true"
      - "--providers.docker=true"
      - "--providers.docker.network=root-proxy"
      - "--providers.docker.endpoint=tcp://root-socket-proxy:2375"
    restart: unless-stopped
 networks:
  proxy:
    name: root-proxy
    internal: true
    driver: bridge
  socket:
    name: root-socket
    internal: true
    driver: bridge
 ```
 ## 4. Deployment
 Now that your structure is ready:
 1. Commit and push this repository to your Git server (e.g., GitHub).
 2. SSH into your VPS.
 3. Follow the [Installation](/root/guides/installation) guide, using your new repository URL instead of the example ones.
 ---
 **See also:**
 - [Guide: Installation on a new host](/root/guides/installation)
 - [Concept: Infrastructure Architecture](/root/concepts/architecture)
@@ -1,60 +1,199 @@
 ---
-title: Installation
+title: Initial Host Setup
-description: Initial setup of the Root framework on a new host.
+description: Setting up a fresh Debian host from scratch.
-weight: 25
+weight: 1
 ---
-This guide covers the initial setup of the Root framework on a new host.
+Hardened setup for a fresh Debian host from zero to deployment.
-## Prerequisites {#prerequisites}
+## Setup Procedure
 - A Debian-based Linux distribution (Debian or Ubuntu).
 - Git installed.
 - Sudo privileges.
 ## Initializing the repository {#init}
 {{% steps %}}
-### Step 1: Clone the configuration repository
+### Essential Packages
-Clone the repository containing your [Node](/root/glossary#node) configurations.
+Install `sudo` and `docker-ce` first. This is necessary because the subsequent user setup relies on the `docker` group and `sudo` configuration.
 **Install Sudo**
 ```bash
-git clone <your-configs-repo-url> ~/repo
+# As root:
-cd ~/repo
+apt update && apt install sudo -y
 ```
-### Step 2: Run the initialization script
+**Install Docker**
-The `init.sh` script sets up the [Commons](/root/glossary#commons) submodule, configures Git hooks, and adds the `root` wrapper to your `PATH`.
+Follow the [Official Docker Installation Guide for Debian](https://docs.docker.com/engine/install/debian/) to install the latest Docker Engine.
 ### System User & Privileges
 The `adam` user handles all administrative tasks. SSH-key authentication and passwordless `sudo` via the `wheel` group minimize friction while maintaining security.
 **Create the Admin User**
 ```bash
-./init.sh
+# As root:
 # Create the user with a bash shell
 useradd -m -s /bin/bash adam
 # Create the wheel group (common for cross-distro consistency)
 groupadd wheel
 # Create a modular sudoers file
 # This allows members of 'wheel' to run sudo without a password
 echo "%wheel ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/99-custom-sudoers
 # Validate syntax
 visudo -c -f /etc/sudoers.d/99-custom-sudoers
 # Add adam to the necessary groups
 usermod -aG wheel,docker adam
 ```
-### Step 3: Refresh your shell
+### Swap Setup
-Source your `.bashrc` to activate the `root` command.
+Configure a swap file to ensure system stability during memory-intensive operations.
 ```bash
-source ~/.bashrc
+# As root:
 # Create a 2GB swap file (adjust size as needed)
 fallocate -l 2G /swap
 chmod 600 /swap
 mkswap /swap
 swapon /swap
 # Make it permanent
 echo '/swap none swap sw 0 0' >> /etc/fstab
 ```
 ### SSH Access & Hardening
 Passwords are disabled. Access is strictly via SSH keys.
 **Authorize Operator Key**
 Import your local public key to the `adam` user.
 ```bash
 # As root:
 # Setup directories
 mkdir -p /home/adam/.ssh
 chmod 700 /home/adam/.ssh
 # Add your public key (Replace [PASTE_PUB_KEY_HERE])
 echo "[PASTE_PUB_KEY_HERE]" > /home/adam/.ssh/authorized_keys
 chmod 600 /home/adam/.ssh/authorized_keys
 chown -R adam:adam /home/adam/.ssh
 ```
 **Operator Side Access**
 Configure your local machine for easy access to the host.
 ```bash
 # ~/.ssh/config on operator side
 Host daedalus.example.com
  Port 2222
  User adam
  IdentityFile ~/.ssh/adam_example_com_ed25519
 ```
 **Harden SSH Daemon**
 Modify the SSH configuration to change the default port and disable password entry.
 ```bash
 # As root:
 # Create a dedicated override config
 cat <<EOF > /etc/ssh/sshd_config.d/99-custom-ssh.conf
 Port 2222
 PasswordAuthentication no
 PermitEmptyPasswords no
 AllowUsers adam
 EOF
 # Validate syntax before restarting to avoid lockout
 sshd -t && systemctl restart ssh
 ```
 ### GitHub Access (Deploy Key)
 The host requires its own identity to pull updates from the GitHub repository.
 ```bash
 # As root:
 # Generate a host-specific SSH key (no passphrase for automation)
 sudo -u adam ssh-keygen -t ed25519 -f /home/adam/.ssh/github_ed25519 -N ""
 # Configure SSH to use this key for GitHub
 cat <<EOF | sudo -u adam tee /home/adam/.ssh/config
 Host github.com
  AddKeysToAgent yes
  IdentityFile ~/.ssh/github_ed25519
 EOF
 # Display the public key to be added to GitHub (Settings > Deploy Keys)
 cat /home/adam/.ssh/github_ed25519.pub
 ```
 > [!TIP]
 > Add the output above to the Deploy Keys settings of your infrastructure repository (e.g., `https://github.com/your-username/your-repo/settings/keys`) with **read access**.
 ### Repository Deployment
 Clone your infrastructure repository and initialize the node.
 ```bash
 # As root:
 # Setup the service directory
 export REPO_DIR="/srv/your-infrastructure-repo"
 mkdir -p $REPO_DIR
 chown adam:adam $REPO_DIR
 # Clone as the adam user
 sudo -u adam git clone git@github.com:your-username/your-repo.git $REPO_DIR
 # Initialize node (Set your node name, e.g., daedalus)
 export NODE="daedalus"
 cd $REPO_DIR
 sudo -u adam ./init.sh
 ```
 **Node-Specific Configuration**
 Run the staged initialization scripts using the `root` dispatcher:
 ```bash
 # Run the sequence for your specific node (as the 'adam' user)
 # Ensure you have sourced ~/.bashrc or re-logged in if 'root' is not found
 root configure base $NODE
 root configure ufw $NODE
 root configure crowdsec $NODE
 root configure cron $NODE
 ```
 ### Storage & Hardening
 Define the data tiers and secure the environment by creating non-root users for containerized services.
 ```bash
 # Create (or mount) storage directories
 sudo mkdir -p /srv/my-infrastructure-root-$NODE-{tier1,tier2,tier3}
 # Setup tiers and non-root users
 root tiers link $NODE \
  /srv/my-infrastructure-root-$NODE-tier1 \
  /srv/my-infrastructure-root-$NODE-tier2 \
  /srv/my-infrastructure-root-$NODE-tier3
 root tiers useradd $NODE
 root tiers chown $NODE
 ```
 {{% /steps %}}
 ## Provisioning a node {#provision}
 Once the framework is installed, you can provision a specific [Node](/root/glossary#node).
 ```bash
 root configure/base <node_name>
 root configure/ufw <node_name>
 ```
 ---
 **See also:**
- [Concept: Infrastructure architecture](/root/concepts/architecture)
+- [Doc: Docker - Install on Debian](https://docs.docker.com/engine/install/debian/)
 - [Reference: ROOT_ API reference](/root/reference/root-api)
@@ -1,19 +0,0 @@
 ---
 title: 'Recipes'
 description: 'Collection of step-by-step procedures for infrastructure maintenance and deployment.'
 weight: 50
 ---
 Step-by-step instructions for reproducible tasks and infrastructure maintenance.
 ## Available Recipes
 {{% cards %}}
 {{< card link="initial-setup" title="Initial Host Setup" icon="server" subtitle="Hardened setup for a fresh Debian host from zero to deployment." >}}
 {{% /cards %}}
 ---
 **See also:**
 - [GitHub: root.ermnvldmr.com](https://github.com/deytenit/root.ermnvldmr.com)
@@ -1,202 +0,0 @@
 ---
 title: 'Initial Host Setup'
 description: 'Setting up a fresh Debian host from scratch.'
 weight: 1
 ---
 Hardened setup for a fresh Debian host from zero to deployment.
 ## Setup Procedure
 {{% steps %}}
 ### Essential Packages
 Install `sudo` and `docker-ce` first. This is necessary because the subsequent user setup relies on the `docker` group and `sudo` configuration.
 **Install Sudo**
 ```bash
 # As root:
 apt update && apt install sudo -y
 ```
 **Install Docker**
 Follow the [Official Docker Installation Guide for Debian](https://docs.docker.com/engine/install/debian/) to install the latest Docker Engine.
 ### System User & Privileges
 The `adam` user handles all administrative tasks. SSH-key authentication and passwordless `sudo` via the `wheel` group minimize friction while maintaining security.
 **Create the Admin User**
 ```bash
 # As root:
 # Create the user with a bash shell
 useradd -m -s /bin/bash adam
 # Create the wheel group (common for cross-distro consistency)
 groupadd wheel
 # Create a modular sudoers file
 # This allows members of 'wheel' to run sudo without a password
 echo "%wheel ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/99-root-ermnvldmr
 # Validate syntax
 visudo -c -f /etc/sudoers.d/99-root-ermnvldmr
 # Add adam to the necessary groups
 usermod -aG wheel,docker adam
 ```
 ### Swap Setup
 Configure a swap file to ensure system stability during memory-intensive operations.
 ```bash
 # As root:
 # Create a 2GB swap file (adjust size as needed)
 fallocate -l 2G /swap
 chmod 600 /swap
 mkswap /swap
 swapon /swap
 # Make it permanent
 echo '/swap none swap sw 0 0' >> /etc/fstab
 ```
 ### SSH Access & Hardening
 Passwords are disabled. Access is strictly via SSH keys.
 **Authorize Operator Key**
 Import your local public key to the `adam` user.
 ```bash
 # As root:
 # Setup directories
 mkdir -p /home/adam/.ssh
 chmod 700 /home/adam/.ssh
 # Add your public key (Replace [PASTE_PUB_KEY_HERE])
 echo "[PASTE_PUB_KEY_HERE]" > /home/adam/.ssh/authorized_keys
 chmod 600 /home/adam/.ssh/authorized_keys
 chown -R adam:adam /home/adam/.ssh
 ```
 **Operator Side Access**
 Configure your local machine for easy access to the host.
 ```bash
 # ~/.ssh/config on operator side
 Host daedalus.root.ermnvldmr.com
  Port 2222
  User adam
  IdentityFile ~/.ssh/adam_root_ermnvldmr_com_ed25519
 ```
 **Harden SSH Daemon**
 Modify the SSH configuration to change the default port and disable password entry.
 ```bash
 # As root:
 # Create a dedicated override config
 cat <<EOF > /etc/ssh/sshd_config.d/99-root-ermnvldmr.conf
 Port 2222
 PasswordAuthentication no
 PermitEmptyPasswords no
 AllowUsers adam
 EOF
 # Validate syntax before restarting to avoid lockout
 sshd -t && systemctl restart ssh
 ```
 ### GitHub Access (Deploy Key)
 The host requires its own identity to pull updates from the GitHub repository.
 ```bash
 # As root:
 # Generate a host-specific SSH key (no passphrase for automation)
 sudo -u adam ssh-keygen -t ed25519 -f /home/adam/.ssh/github_ed25519 -N ""
 # Configure SSH to use this key for GitHub
 cat <<EOF | sudo -u adam tee /home/adam/.ssh/config
 Host github.com
  AddKeysToAgent yes
  IdentityFile ~/.ssh/github_ed25519
 EOF
 # Display the public key to be added to GitHub (Settings > Deploy Keys)
 cat /home/adam/.ssh/github_ed25519.pub
 ```
 > [!TIP]
 > Add the output above to the [GitHub: Repository Deploy Keys](https://github.com/deytenit/root.ermnvldmr.com/settings/keys) with **read access**.
 ### Repository Deployment
 Clone the infrastructure repository and initialize the node.
 ```bash
 # As root:
 # Setup the service directory
 export REPO_DIR="/srv/root.ermnvldmr.com"
 mkdir -p $REPO_DIR
 chown adam:adam $REPO_DIR
 # Clone as the adam user
 sudo -u adam git clone git@github.com:deytenit/root.ermnvldmr.com.git $REPO_DIR
 # Initialize node (Set your node name, e.g., daedalus)
 export NODE="daedalus"
 cd $REPO_DIR
 sudo -u adam ./init.sh
 ```
 **Node-Specific Configuration**
 Run the staged initialization scripts in order:
 ```bash
 # As root:
 # Run the sequence for your specific node
 cd $REPO_DIR
 ./$NODE/.host/.scripts/00-base
 ./$NODE/.host/.scripts/10-ufw
 ./$NODE/.host/.scripts/20-crowd
 ./$NODE/.host/.scripts/30-cron
 ```
 ### Storage & Hardening
 Define the data tiers and secure the environment by creating non-root users for containerized services.
 ```bash
 # As root:
 # Create (or mount) storage directories
 mkdir -p /srv/com-ermnvldmr-root-$NODE-{tier1,tier2,tier3}
 # Setup tiers and non-root users
 cd $REPO_DIR
 sudo -u adam .scripts/ops/setup-tiers $NODE \
  /srv/com-ermnvldmr-root-$NODE-tier1 \
  /srv/com-ermnvldmr-root-$NODE-tier2 \
  /srv/com-ermnvldmr-root-$NODE-tier3
 sudo -u adam .scripts/ops/setup-noroot-users $NODE
 ```
 {{% /steps %}}
 ---
 **See also:**
 - [Doc: Docker - Install on Debian](https://docs.docker.com/engine/install/debian/)
 - [GitHub: root.ermnvldmr.com](https://github.com/deytenit/root.ermnvldmr.com)
@@ -4,8 +4,15 @@ description: API and technical references for developers.
 weight: 30
 ---
-Technical reference materials and APIs for the Root framework.
+Technical reference materials and APIs for the ermnvldmr.com root deployment commons framework.
 {{% cards %}}
 {{< card link="compose" title="Compose actions reference" icon="play" subtitle="High-level entrypoint for orchestrating docker-compose." >}}
 {{< card link="configure" title="Configure actions reference" icon="arrow-down" subtitle="Host provisioning and system-level configuration." >}}
 {{< card link="initialization" title="Initialization actions reference" icon="play" subtitle="Actions for initial node setup." >}}
 {{< card link="root-api" title="ROOT_ API reference" icon="code" subtitle="Standardized environment variables and logging helpers." >}}
 {{< card link="source" title="Source services reference" icon="book-open" subtitle="Shared services built from source." >}}
 {{< card link="sync" title="Sync actions reference" icon="check" subtitle="Actions for keeping nodes up-to-date." >}}
 {{< card link="tiers" title="Tiers actions reference" icon="archive" subtitle="Storage tiers management." >}}
 {{< card link="utils" title="Utility actions reference" icon="check" subtitle="Helper scripts and utilities." >}}
 {{% /cards %}}
@@ -0,0 +1,50 @@
 ---
 title: Compose Actions
 description: Standardized high-level entrypoint for orchestrating docker-compose across a node.
 weight: 54
 ---
 The `compose` action provides a standardized, high-level entrypoint for orchestrating Docker Compose files across all projects within a specific node.
 ## Core Compose Action {#actions}
 | Action | Description |
 | :--- | :--- |
 | `compose <node> <action>` | Executes a given Docker Compose command (e.g., `up`, `down`, `restart`) across the node's infrastructure. |
 ## Orchestration Order {#order}
 To maintain correct dependencies (especially when shutting down or starting up infrastructure-level proxies and networks), the `compose` action intelligently orders the execution:
 ### Starting Up (`up`, `restart`)
 When starting or restarting services, the action follows a **Forward Order**:
 1. **Node Infrastructure**: First, it processes the node-level `docker-compose.yml` (located at the root of the node directory).
 2. **Root Infrastructure**: Next, it processes the `root/docker-compose.yml` project, if it exists (usually contains Traefik, Socket Proxy, etc.).
 3. **Projects**: Finally, it processes all other project directories in alphabetical order.
 ### Shutting Down (`down`)
 When stopping services, the action uses a **Reverse Order** to ensure projects disconnect gracefully before the network or proxy goes down:
 1. **Projects**: All standard projects are stopped in reverse alphabetical order.
 2. **Root Infrastructure**: The `root/docker-compose.yml` project is stopped.
 3. **Node Infrastructure**: Finally, the node-level `docker-compose.yml` is brought down.
 ## Options {#options}
 You can pass standard Docker Compose arguments to the end of the command.
 Additionally, the action supports a dry-run mode:
 - `--dry-run`: Prints the commands that would be executed without actually running them.
 **Example usage:**
 ```bash
 root compose daedalus up -d --remove-orphans
 root compose daedalus restart --dry-run
 root compose daedalus down
 ```
 ---
 **See also:**
 - [Concept: Infrastructure Architecture](/root/concepts/architecture)
 - [Reference: ROOT_ API Reference](/root/reference/root-api)
@@ -0,0 +1,66 @@
 ---
 title: Configuration Actions
 description: Host provisioning, template engine, and system-level configuration.
 weight: 53
 ---
 Configuration actions are used to provision the host and maintain system-level services. They rely heavily on the built-in template engine to generate declarative configuration files.
 ## The Template Engine {#template-engine}
 The Root framework uses `envsubst` (from `gettext-base`) to render templates. This allows you to use standard Bash environment variables directly within your configuration files.
 ### Template Conventions
 - **File Extension**: Templates typically use the `.template` extension (e.g., `crontab.template`).
 - **Variable Syntax**: Use `${VARIABLE_NAME}` or `$VARIABLE_NAME` to inject values.
 - **Auto-Discovery**: Many actions automatically look for templates in specific directories within the [Configs](/root/glossary#configs) repository.
 ### Rendering Helpers
 The `root_template.sh` library provides several helpers:
 - `root_template_render <input> <output>`: Renders a single file.
 - `root_template_render_directory <src> <dest>`: Recursively renders an entire directory structure.
 - `root_template_crontab <template>`: Renders and installs a crontab for the current user.
 ## Core Configuration Actions {#actions}
 | Action | Description |
 | :--- | :--- |
 | `configure/base` | Installs essential packages (`sudo`, `ufw`, `docker`) and sets up basic system users. |
 | `configure/cron` | Renders and installs node-specific crontabs. |
 | `configure/crowdsec` | Sets up the CrowdSec agent and bouncers. |
 | `configure/routing` | Configures system-level routing and bridge networks. |
 | `configure/systemd` | Installs and enables systemd service units. |
 | `configure/ufw` | Renders and applies firewall rules using UFW and `ufw-docker`. |
 ## Example: Nginx Template {#example}
 ```nginx filename="nginx.conf.template"
 # This template uses ROOT_NODE environment variable
 user  nginx;
 worker_processes  auto;
 error_log  /var/log/nginx/error.log notice;
 pid        /var/run/nginx.pid;
 events {
    worker_connections  1024;
 }
 http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    # Injected from environment
    server_name ${ROOT_NODE}.example.com;
 }
 ```
 ---
 **See also:**
 - [Concept: Infrastructure Architecture](/root/concepts/architecture)
 - [Reference: ROOT_ API Reference](/root/reference/root-api)
@@ -0,0 +1,40 @@
 ---
 title: System Initialization
 description: Repository setup, Git hooks, and PATH configuration.
 weight: 51
 ---
 The Root framework requires a one-time initialization on each host to establish path linkages and repository-level configurations.
 ## The `init.sh` Script {#init-script}
 The `init.sh` script located at the repository root is the primary bootstrap mechanism. It performs the following critical tasks:
 1. **Submodule Initialization**: Ensures the [Commons](/root/glossary#commons) repository is present and up to date.
 2. **Git Hook Configuration**: Points `core.hooksPath` to `.operator/shared/githooks` to enable standardized pre-commit checks.
 3. **Safe Directory Registration**: Adds the repository to Git's `safe.directory` list, which is required for operations performed by different users (e.g., `root`, `adam`).
 4. **Vim Configuration**: Links a standardized `.vimrc` to both the current user and the `root` user for a consistent editing experience.
 5. **PATH Persistence**: Adds the `.operator/shared/scripts/run` directory to the user's `~/.bashrc`, making the `root` command available globally.
 ## Git Hooks {#githooks}
 Root enforces standards through Git hooks stored in `.operator/shared/githooks/`.
 - **Pre-commit**: Validates that all scripts follow the namespacing and structure conventions.
 - **Commit-msg**: (Optional) Enforces conventional commit messages if configured.
 ## PATH Configuration {#path}
 The `root` command is a wrapper located in `.operator/shared/scripts/run/root`. By adding this directory to the `PATH`, the dispatcher can be invoked from any directory within the system, automatically resolving the repository root based on the current working directory or environment variables.
 ```bash
 # Example of manual PATH addition (performed automatically by init.sh)
 export PATH="$HOME/repo/.operator/shared/scripts/run:$PATH"
 ```
 ---
 **See also:**
 - [Guide: Initial Host Setup](/root/guides/installation)
 - [Reference: ROOT_ API Reference](/root/reference/root-api)
@@ -4,11 +4,19 @@ description: Standardized environment variables for path resolution and node con
 weight: 50
 ---
-Every [Action](/root/glossary#action) script executed via the `root` dispatcher has access to a standardized set of environment variables. These variables are the single source of truth for path resolution and node context.
+Every [Action](/root/glossary#action) script executed via the `root` dispatcher has access to a standardized set of environment variables and Bash libraries. This provides a consistent "API" for interacting with the infrastructure.
 ## The `root` Dispatcher {#dispatcher}
 The `root` command (located in `.operator/shared/scripts/run/root`) is the main entrypoint for all orchestration. Its primary responsibilities include:
 1. **Context Resolution**: Locating the target [Node](/root/glossary#node) and its associated storage [Tiers](/root/glossary#tier).
 2. **Library Loading**: Sourcing the core namespaced libraries (e.g., `root_core`, `root_sys`).
 3. **Action Execution**: Discovering and running the requested action, prioritizing local overrides.
 ## Path resolution variables {#paths}
-These variables define the physical location of the infrastructure components.
+These variables are established by the dispatcher and are available to all actions.
 | Variable | Description |
 | :--- | :--- |
@@ -20,40 +28,35 @@ These variables define the physical location of the infrastructure components.
 ## Node context variables {#node-context}
-When an action targets a specific [Node](/root/glossary#node), the following variables are established by the `root_require_node` helper.
+When an action targets a specific node, the following variables are established by the `root_require_node` helper.
 | Variable | Description |
 | :--- | :--- |
-| `ROOT_NODE` | The identifier of the target node (e.g., `icarus`). |
+| `ROOT_NODE` | The identifier of the target node (e.g., `daedalus`). |
 | `ROOT_NODE_DIR` | Absolute path to the node configuration directory. |
 | `ROOT_TIER1` | Absolute path to the [Tier 1](/root/glossary#tier) storage directory. |
 | `ROOT_TIER2` | Absolute path to the Tier 2 storage directory. |
 | `ROOT_TIER3` | Absolute path to the Tier 3 storage directory. |
-## Logging helpers {#logging}
+## Core Logging Helpers {#logging}
-Standardized logging uses the `[$ROOT_NODE] [$ROOT_ACTION_PATH]` prefix for consistency across the orchestration logs.
+Standardized logging ensure consistent output across all actions.
 - `root_log_info`: Standard informational output.
- `root_log_warn`: Warnings requiring attention but not stopping execution.
+- `root_log_warn`: Warnings requiring attention.
 - `root_log_error`: Critical errors sent to `stderr`.
 - `root_log_success`: Confirmation of successful task completion.
-## Help system metadata {#help}
+## The Help System {#help}
-The `root` [Dispatcher](/root/glossary#dispatcher) provides a built-in `--help` system. To keep action scripts "stupid", they do not implement their own help flags. Instead, the dispatcher parses a specific `action_metadata` block defined at the top of every action script.
+The dispatcher provides a built-in help system by parsing an `action_metadata` block at the top of each script. This allows scripts to remain "stupid" and declarative without implementing their own CLI argument parsing.
 When a user runs `root <action> --help`, the dispatcher extracts and displays this YAML-formatted block without executing the script.
 ### Example metadata
 ```bash filename="example-action-metadata"
 action_metadata() {
  cat <<EOF
-description: "Brief summary of the task."
+description: "Brief summary of the action."
 args:
-  - NODE: "The node name"
+  - NODE: "The name of the target node."
  - PARAM: "A custom parameter"
 EOF
 }
 ```
@@ -0,0 +1,42 @@
 ---
 title: The `source/` Directory
 description: Conceptual overview of the self-contained source directory structure.
 weight: 52
 ---
 The `source/` directory at the repository root contains the core components and projects that the Root framework orchestrates. It is designed for maximum isolation and self-containment.
 ## Core Philosophy {#philosophy}
 The `source/` directory is not just a place to store code; it is a collection of independent [Projects](/root/glossary#project). Each project within this directory should follow these principles:
 1. **Isolation**: Each project lives in its own subdirectory (e.g., `source/my-app/`).
 2. **Self-Documentation**: Each project directory **MUST** contain its own `README.md` file describing its purpose, dependencies, and configuration.
 3. **Internal Logic**: Projects handle their own build processes, Dockerfiles, and internal configurations. The Root framework's [Actions](/root/glossary#action) simply orchestrate these existing components.
 ## Directory Structure {#structure}
 A typical project within the `source/` directory might look like this:
 {{< filetree/container >}}
 {{< filetree/folder name="source" state="open" >}}
  {{< filetree/folder name="happ-subscription-generator" state="open" >}}
    {{< filetree/file name="Dockerfile" >}}
    {{< filetree/file name="generator.py" >}}
    {{< filetree/file name="README.md" >}}
  {{< /filetree/folder >}}
 {{< /filetree/folder >}}
 {{< /filetree/container >}}
 ## Relationship with Actions {#actions}
 Root actions (like `compose` or `sync`) interact with the `source/` directory by referencing paths within it. For example, the `compose` action might use a `docker-compose.yml` file that points to a `Dockerfile` located in `source/app/`.
 This separation of concerns ensures that the orchestration logic (Actions) remains decoupled from the implementation details (Source).
 ---
 **See also:**
 - [Concept: Infrastructure Architecture](/root/concepts/architecture)
 - [Reference: ROOT_ API Reference](/root/reference/root-api)
@@ -0,0 +1,36 @@
 ---
 title: Synchronization Actions
 description: Repository updates, package synchronization, and data backups.
 weight: 54
 ---
 Synchronization actions ensure that the host's state remains consistent with the defined configurations in the remote repositories.
 ## Core Synchronization Actions {#actions}
 | Action | Description |
 | :--- | :--- |
 | `sync/packages` | Synchronizes node packages and their configurations across the system. |
 | `sync/repository` | Updates the main configuration repository to its latest state from GitHub. |
 | `sync/tiers` | Triggers the node-specific backup strategy for the configured [Tiers](/root/glossary#tier). |
 ## Repository Synchronization (`sync/repository`) {#repository}
 The `sync/repository` action is responsible for keeping the host's configuration repository up-to-date with its remote source. It typically performs a `git pull` on the main configuration repository and may optionally trigger sub-module updates for the [Commons](/root/glossary#commons) repository.
 This ensures that any changes to the node configurations, actions, or source files are correctly pulled down to the target host.
 ## Backup Synchronization (`sync/tiers`) {#tiers}
 The `sync/tiers` action is the primary entry point for a node's backup strategy.
 - **No Default Implementation**: The framework itself does not provide a default backup mechanism, allowing operators to design a custom strategy suitable for their needs.
 - **Custom Overrides**: As a "Smart Dispatcher" action, you can define your backup logic by placing a custom script in `.operator/local/scripts/actions/sync/tiers`.
 - **Example Implementation**: A common practice is to use a tool like [Restic](https://restic.net/) within this custom script to perform off-site backups of critical data (Tiers 1 and 2) to an S3-compatible storage backend.
 ---
 **See also:**
 - [Concept: Tiered Storage Model](/root/concepts/tiered-storage)
 - [Reference: ROOT_ API Reference](/root/reference/root-api)
@@ -0,0 +1,44 @@
 ---
 title: Tier Management Actions
 description: Storage classification, symbolic linking, and privilege isolation.
 weight: 55
 ---
 Tier management actions are responsible for enforcing the framework's [Tiered Storage Model](/root/concepts/tiered-storage) and ensuring correct filesystem ownership and isolation.
 ## Core Tier Actions {#actions}
 | Action | Description |
 | :--- | :--- |
 | `tiers/chown` | Sets correct filesystem ownership for project-specific [Non-Root Users](#useradd). |
 | `tiers/link` | Manages symbolic links between the project directories and their corresponding [Tiers](/root/glossary#tier). |
 | `tiers/useradd` | Provisions a unique system user for each project to achieve [Privilege Isolation](/root/concepts/security-model). |
 ## User Management (`tiers/useradd`) {#useradd}
 The `tiers/useradd` action creates a dedicated, low-privileged system user for each project within a node. This user is then used to run the project's containers, ensuring that a compromise of one project does not grant the attacker access to the entire host.
 - **Naming Convention**: Users are typically named after the project.
 - **Group Membership**: Users can optionally be added to the `docker` group or interact with Docker via other securely configured methods, depending on the operator's preference.
 ## Storage Linking (`tiers/link`) {#link}
 The `tiers/link` action creates the symbolic link structure required for the tiered storage model. It ensures that directories like `config`, `data`, and `logs` within a project folder point to their physical locations in `@tier1`, `@tier2`, and `@tier3` respectively.
 ```bash
 # Example link structure created by tiers/link
 /srv/root/icarus/synapse/config -> /srv/storage/@tier1/synapse
 /srv/root/icarus/synapse/data   -> /srv/storage/@tier2/synapse
 /srv/root/icarus/synapse/logs   -> /srv/storage/@tier3/synapse
 ```
 ## Ownership Management (`tiers/chown`) {#chown}
 Once tiers and links are established, the `tiers/chown` action ensures that the physical directories in each tier are owned by the correct project user. This is critical for preventing permission-denied errors and ensuring that projects can only access their own data.
 ---
 **See also:**
 - [Concept: Tiered Storage Model](/root/concepts/tiered-storage)
 - [Concept: Security & Privilege Isolation](/root/concepts/security-model)
@@ -0,0 +1,37 @@
 ---
 title: Utility Actions
 description: Common helper scripts for maintenance, validation, and certificate management.
 weight: 56
 ---
 Utility actions provide common helper functions for node maintenance, validation, and project-specific tasks.
 ## Core Utility Actions {#actions}
 | Action | Description |
 | :--- | :--- |
 | `utils/extract-traefik-certs` | Extracts SSL/TLS certificates and private keys from Traefik's `acme.json` storage. |
 | `utils/generate-happ-subscriptions` | Automatically generates HApp subscription files based on current project metadata. |
 | `utils/lint-docker-compose` | Performs a static analysis of all `docker-compose.yml` files to ensure they meet the framework's standards. |
 ## Certificate Management (`utils/extract-traefik-certs`) {#certificates}
 Traefik stores its ACME-issued certificates (like those from Let's Encrypt) in a single `acme.json` file. The `utils/extract-traefik-certs` action parses this file and extracts individual `fullchain.pem` and `privkey.pem` files.
 This is particularly useful when other services (e.g., mail servers, non-Dockerized applications) require the same SSL certificates.
 ## Quality Assurance (`utils/lint-docker-compose`) {#linting}
 To maintain consistency and security, the `utils/lint-docker-compose` action validates all compose files across the infrastructure. It checks for:
 - **Naming Standards**: Ensures project names and container names follow the `{node}-{project}` convention.
 - **Security Context**: Flags containers running as `root` without a justified override.
 - **Resource Constraints**: Identifies services lacking CPU or memory limits.
 - **Label Standards**: Validates required labels for routing (e.g., [Traefik](https://traefik.io/)) and [CrowdSec](/root/concepts/security-model#crowdsec).
 ---
 **See also:**
 - [Concept: Infrastructure Principles](/root/concepts/principles)
 - [Concept: Security & Privilege Isolation](/root/concepts/security-model)
@@ -7,5 +7,6 @@ title: 'Документация ermnvldmr.com'
 Добро пожаловать в единую документацию для моих собственных проектов
 {{< cards >}}
-{{< card link="root" title="root.ermnvldmr.com" icon="server" subtitle="Документация инфраструктуры root.ermnvldmr.com" >}}
+{{< card link="root" title="ermnvldmr.com-root-commons" icon="server" subtitle="Документация общих модулей корневой инфраструктуры ermnvldmr.com" >}}
 {{< card link="quetza" title="Quetza Bot" icon="terminal" subtitle="Документация модульного фреймворка Discord-бота" >}}
 {{< /cards >}}
@@ -0,0 +1,35 @@
 ---
 title: Quetza Bot
 description: Модульный фреймворк для Discord-ботов.
 weight: 1
 type: docs
 cascade:
  type: docs
 ---
 **Quetza** — это модульный фреймворк для Discord-ботов, построенный на TypeScript, который позволяет разработчикам создавать многофункциональные приложения для Discord с помощью самодостаточных, композитных модулей.
 Фреймворк обеспечивает архитектурный фундамент, который превращает разработку функций из модификации ядра в добавление модулей.
 ## Основные возможности
 - **Обнаружение модулей на основе соглашений**: Просто создайте папку, и Quetza загрузит ее как функциональный модуль.
 - **Изоляция контроллеров**: Управляйте состоянием на уровне сервера (guild), предотвращая утечки данных между серверами.
 - **Декларативные команды**: Определяйте Slash-команды Discord с помощью простого, типизированного интерфейса.
 - **Реактивные события**: Подписывайтесь на любые события Discord.js внутри ваших модулей.
 ## Разделы
 {{% cards %}}
 {{< card link="getting-started" title="Начало работы" icon="lightning-bolt" subtitle="Поймите философию и архитектуру Quetza." >}}
 {{< card link="concepts" title="Концепции" icon="light-bulb" subtitle="Глубокое погружение в модульную систему и структуру контроллеров." >}}
 {{< card link="guides" title="Руководства" icon="book-open" subtitle="Пошаговые инструкции по разработке модулей и деплою." >}}
 {{< card link="troubleshooting" title="Устранение неполадок" icon="shield-exclamation" subtitle="Диагностика распространенных проблем в разработке модулей." >}}
 {{% /cards %}}
 ---
 **See also:**
 - [GitHub: Quetza](https://github.com/deytenit/Quetza)
 - [Discord.js Documentation](https://discord.js.org/)
@@ -0,0 +1,6 @@
 ---
 title: Концепции
 weight: 2
 ---
 В этом разделе описываются архитектурные принципы, на которых построена Quetza. Понимание этих концепций поможет вам проектировать более надежные и поддерживаемые модули.
@@ -0,0 +1,45 @@
 ---
 title: Архитектура и Философия
 weight: 1
 ---
 **Цель:** Понять основные принципы проектирования, лежащие в основе модульности Quetza.
 ## Философия проектирования
 ### Соглашение важнее конфигурации (Convention Over Configuration)
 Quetza минимизирует шаблонный код, полагаясь на строгую структуру папок.
 - **Никакого центрального реестра:** Сама файловая система _является_ реестром.
 - **Результат:** Вам не нужно обновлять файл конфигурации, чтобы добавить модуль; вы просто создаете папку.
 ### Композиция важнее наследования (Composition Over Inheritance)
 Модули состоят из возможностей (capabilities), а не наследуются от базового класса.
 - **Гибкость:** Модули могут использовать любую внутреннюю архитектуру (Функциональную, ООП), пока они экспортируют необходимые интерфейсы.
 ### Изоляция важнее интеграции (Isolation Over Integration)
 Модули не могут напрямую вызывать друг друга.
 - **Почему:** Это предотвращает сильную связность (tight coupling).
 - **Преимущество:** Вы можете удалить любой модуль, не сломав остальную часть бота.
 ## Основные сущности
 | Сущность | Роль | Жизненный цикл |
 | :--- | :--- | :--- |
 | **Client** | Локатор сервисов и оркестратор | Синглтон. Руководит всем. |
 | **Module** | Пространство имен для функций | Загружается при запуске. |
 | **Command** | Конечная точка взаимодействия с пользователем | Без состояния (Stateless). Запрос/Ответ. |
 | **Event** | Реактивный наблюдатель (Observer) | Подписывается при запуске. |
 | **Controller** | Менеджер состояния | Сохраняется между взаимодействиями. |
 ---
 **См. также:**
 - [Паттерн Service Locator](https://ru.wikipedia.org/wiki/Локатор_служб)
 - [Паттерн Observer](https://ru.wikipedia.org/wiki/Наблюдатель_(шаблон_проектирования))
@@ -0,0 +1,67 @@
 ---
 title: Модульная система
 weight: 2
 ---
 **Цель:** Определить словарь и механизмы основной абстрактной единицы Quetza.
 ## Системный словарь
 ### Объявление модуля (Module Declaration)
 Файл `module.ts` выступает в качестве манифеста. Это точка входа для обнаружения.
 ```typescript
 export const name = 'my-module'; // ID
 export const description = '...'; // Документация
 ```
 ### Регистрация команд (Command Registration)
 Происходит во время события `ready`.
 1. Quetza сканирует все папки `commands/`.
 2. Компилирует `ApplicationCommandData`.
 3. Отправляет (PUT) данные в API Discord.
 ### Внедрение контроллера (Controller Injection)
 Состояние внедряется (injected), а не импортируется.
 ```typescript
 // Фреймворк вызывает это:
 execute(client, interaction, controller);
 ```
 - **Зачем?** Позволяет фреймворку управлять жизненным циклом контроллера (синглтон на каждый модуль).
 ## Философия управления состоянием
 ### Эфемерность по умолчанию
 Quetza **не предоставляет встроенной базы данных**.
 - **Память:** Контроллеры хранят состояние в JS объектах `Map` или `Set`.
 - **Перезапуск:** Все состояние теряется при завершении процесса.
 - **Постоянство:** Должно быть реализовано вручную (например, SQLite, Redis) внутри Контроллера.
 ### Область видимости как ключ
 Состояние должно быть ключировано по его границам.
 - `Map<GuildID, ...>` - Специфично для сервера (Наиболее частое).
 - `Map<UserID, ...>` - Специфично для пользователя (Боты для личных сообщений - DM).
 ## Модель обработки ошибок
 **Быстрый и дружелюбный отказ (Fail Fast & Friendly).**
 - **Валидация:** Проверяйте права/вводы немедленно.
 - **Для пользователя:** "У вас нет прав" (а не "Ошибка: 403").
 - **Изоляция:** Сбой в `/ping` перехватывается сам по себе и не "убивает" бота.
 ---
 **См. также:**
 - [Жизненный цикл взаимодействия Discord (Interaction Lifecycle)](https://discord.com/developers/docs/interactions/receiving-and-responding)
@@ -0,0 +1,66 @@
 ---
 title: Начало работы
 weight: 1
 ---
 **Quetza** — это модульный фреймворк для Discord-ботов, построенный на TypeScript, который позволяет разработчикам создавать многофункциональные приложения для Discord с помощью самодостаточных, композитных модулей.
 ## Что такое Quetza?
 Quetza предоставляет архитектурный фундамент, который превращает разработку функций из модификации ядра в добавление модулей. Он решает проблему жесткого дизайна ботов за счет инверсии структур зависимостей: ядро ничего не знает о модулях, однако модули имеют полный доступ к возможностям через определенные контракты.
 ## Основная философия
 ### Проблема
 Традиционные монолитные боты страдают от хрупкости. Добавление функций требует изменения логики ядра, переплетения зависимостей и управления растущими базами кода, которые трудно тестировать или изменять.
 ### Решение
 Quetza рассматривает модули как плагины.
 - **Расширение без правки ядра:** Добавляйте функции, создавая папку. Модификация кода ядра не требуется.
 - **Изоляция:** Модули работают независимо.
 - **Композиция:** Включайте или выключайте функции, просто добавляя или удаляя папки модулей.
 ## Высокоуровневая архитектура
 Quetza состоит из трех основных уровней:
 1. **Базовый уровень (Foundation Layer)**: Клиент `Discord.js`, расширенный реестрами модулей (команды, события, модули). Он действует как сервис-локатор.
 2. **Модульный уровень (Module Layer)**: Самодостаточные пакеты функций. Каждый модуль предоставляет собственные команды и события через стандартизированную структуру файлов.
 3. **Сервисный уровень (Service Layer)**: Опциональные **Контроллеры**, которые управляют состоянием бизнес-логики (например, аудиоплееры, контекст разговора) на разных серверах (guilds).
 ## Ключевые концепции
 ### Ментальная модель
 Для эффективной работы с Quetza примите следующую парадигму:
 - **Модули — это плагины:** Независимые папки, обнаруживаемые во время выполнения.
 - **Команды — это конечные точки (Endpoints):** Обработчики без сохранения состояния, действующие подобно эндпоинтам REST API.
 - **События — это наблюдатели (Observers):** Реактивная логика, подписывающаяся на события жизненного цикла Discord.
 - **Контроллеры — это сервисы:** Менеджеры состояния, восполняющие пробел между командами без состояния и постоянным поведением.
 ### Границы системы
 Понимание ограничений критически важно для проектирования:
 - **Отсутствие постоянства (Persistence):** Состояние в памяти теряется при перезагрузке. Для постоянного хранения требуется внешняя база данных.
 - **Отсутствие межмодульного взаимодействия:** Модули не могут напрямую вызывать друг друга, что обеспечивает слабую связанность.
 - **Отсутствие динамической загрузки:** Модули загружаются только при запуске.
 ## Архитектурные инварианты
 Quetza жертвует гибкостью ради предсказуемости с помощью строгих соглашений:
 - **Обнаружение на основе соглашений:** Модули _обязаны_ следовать структуре директорий (`module.ts`, `commands/`, `events/`) для загрузки.
 - **Однофазная инициализация:** Вся загрузка происходит до установления соединения с Discord.
 - **Соблюдение интерфейсов:** Все команды и события должны экспортировать специфические интерфейсы для их регистрации.
 ---
 **See also:**
 - [Discord.js Documentation](https://discord.js.org/)
 - [TypeScript Documentation](https://www.typescriptlang.org/)
@@ -0,0 +1,6 @@
 ---
 title: Руководства
 weight: 3
 ---
 Пошаговые инструкции и руководства по реализации функций в Quetza.
@@ -0,0 +1,56 @@
 ---
 title: Интеграция разговорного ИИ
 weight: 4
 ---
 **Цель:** Интегрировать большие языковые модели (LLM), управляя контекстом и ограничениями тайм-аута Discord.
 ## 1. Стратегия управления контекстом
 Разговоры требуют истории, чтобы быть связными.
 - **Область видимости (Scoping):** `Map<GuildID, Map<UserID, Message[]>>`
  - **Ключ гильдии (Guild Key):** Предотвращает утечки между серверами.
  - **Ключ пользователя (User Key):** Предотвращает путаницу между пользователями в публичных каналах.
 - **Жизненный цикл:** Реализуйте "скользящее окно" (например, последние 50 сообщений) для предотвращения разрастания контекста.
 ## 2. Потоковая передача ответов
 LLM работают медленно, а Discord требует быстрых ответов (тайм-аут 3 секунды).
 {{% steps %}}
 ### Шаг 1: Отложенное взаимодействие (Defer Interaction)
 Немедленно вызовите `interaction.deferReply()`. Это даст вам 15 минут.
 ### Шаг 2: Вызов LLM
 Асинхронно вызовите ваш ИИ-сервис.
 ### Шаг 3: Редактирование ответа
 Когда данные поступят, используйте `interaction.editReply(content)`.
 {{% /steps %}}
 ## 3. Пример реализации
 ```typescript
 // commands/chat.ts
 export async function execute(interaction, controller) {
  // 1. Отложить ответ
  await interaction.deferReply();
  // 2. Обработка
  const history = controller.getHistory(interaction.guildId, interaction.user.id);
  const response = await aiService.generate(interaction.options.getString('prompt'), history);
  // 3. Ответ
  await interaction.editReply(response);
  controller.updateHistory(interaction.guildId, interaction.user.id, response);
 }
 ```
 > [!WARNING]
 > **Затраты на API:**
 > API ИИ часто тарифицируются по токенам. Внедрите строгие лимиты запросов (rate limits) для пользователей в вашем Контроллере, чтобы предотвратить злоупотребления.
@@ -0,0 +1,77 @@
 ---
 title: Развертывание и эксплуатация
 weight: 2
 ---
 **Цель:** Настроить, развернуть и мониторить экземпляр бота Quetza.
 ## 1. Подготовка окружения
 Quetza полагается на переменные окружения для конфигурации. **Никогда** не сохраняйте их в систему контроля версий.
 | Переменная | Описание | Обязательно |
 | :--- | :--- | :--- |
 | `DISCORD_TOKEN` | Токен бота из Discord Developer Portal | **Да** |
 | `CLIENT_ID` | ID приложения для регистрации slash-команд | **Да** |
 | `LLAMA_API_KEY` | Требуется при использовании модуля ИИ | Нет |
 ## 2. Стратегии развертывания
 {{< tabs >}}
 {{< tab name="Docker (Рекомендуется)" >}}
 **Docker** обеспечивает стабильное окружение выполнения.
 1.  **Сборка** образа:
    ```bash
    docker build -t quetza-bot .
    ```
 2.  **Запуск** контейнера:
    ```bash
    docker run -d \
      --env-file .env \
      --name quetza \
      quetza-bot
    ```
 {{< /tab >}}
 {{< tab name="Из исходников (Source)" >}}
 Развертывание **из исходников** полезно для разработки.
 1.  **Установка** зависимостей:
    ```bash
    pnpm install
    ```
 2.  **Сборка** проекта:
    ```bash
    pnpm build
    ```
 3.  **Запуск** бота:
    ```bash
    pnpm start
    ```
 {{< /tab >}}
 {{< /tabs >}}
 ## 3. Операционный мониторинг
 После запуска используйте следующие механизмы для проверки работоспособности:
 - **Логи:** Проверьте стандартный вывод (логи Docker) на наличие ошибок инициализации.
 - **Команда `/ping`:** Проверяет задержку сети и отзывчивость API.
 - **Команда `/modules`:** Перечисляет все загруженные модули, чтобы подтвердить доступность функций.
 > [!WARNING]
 > **Ограничение масштабирования:**
 > Quetza следует модели "один экземпляр на один токен". Не запускайте несколько экземпляров с одним и тем же токеном, так как это вызовет конфликты WebSocket.
 ---
 **См. также:**
 - [Документация Docker](https://docs.docker.com/)
 - [Discord Developer Portal](https://discord.com/developers/applications)
@@ -0,0 +1,105 @@
 ---
 title: Процесс разработки модуля
 weight: 1
 ---
 **Цель:** Создать новую функцию для бота Quetza путем реализации самодостаточного модуля.
 ## 1. Фаза концептуализации
 Перед написанием кода определите архитектуру модуля:
 - **Простая команда:** Требуется только папка `commands/` (например, служебные команды).
 - **Реактивная логика:** Нужна папка `events/` для прослушивания жизненного цикла Discord (например, приветственные сообщения).
 - **Функция с состоянием:** Требуется **Контроллер** (Controller) для управления состоянием на разных серверах (например, музыкальный плеер).
 ## 2. Создание структуры
 Создайте структуру директорий модуля. Наличие этих файлов запускает автоматическое обнаружение.
 {{< filetree/container >}}
 {{< filetree/folder name="src" state="open" >}}
 {{< filetree/folder name="modules" state="open" >}}
 {{< filetree/folder name="my-feature" state="open" >}}
 {{< filetree/file name="module.ts" >}}
 {{< filetree/folder name="commands" >}} {{< /filetree/folder >}}
 {{< filetree/folder name="events" >}} {{< /filetree/folder >}}
 {{< filetree/folder name="lib" >}} {{< /filetree/folder >}}
 {{< /filetree/folder >}}
 {{< /filetree/folder >}}
 {{< /filetree/folder >}}
 {{< /filetree/container >}}
 ## 3. Шаги реализации
 {{% steps %}}
 ### Шаг 1: Создание манифеста
 Создайте `module.ts` для объявления модуля.
 ```typescript
 // src/modules/my-feature/module.ts
 export const name = 'my-feature';
 export const description = 'Добавляет крутые возможности';
 // Опционально: export const controller = new MyFeatureController();
 ```
 ### Шаг 2: Реализация команд
 Создайте файлы команд в папке `commands/`. Каждый файл экспортирует данные и функцию-исполнитель (executor).
 ```typescript
 // src/modules/my-feature/commands/ping.ts
 import { SlashCommandBuilder } from 'discord.js';
 export const data = new SlashCommandBuilder().setName('ping').setDescription('Отвечает Pong!');
 export async function execute(interaction) {
  await interaction.reply('Pong!');
 }
 ```
 ### Шаг 3: Реализация событий (Опционально)
 Создайте обработчики событий в `events/` для отслеживания состояния Discord.
 ```typescript
 // src/modules/my-feature/events/ready.ts
 import { Events } from 'discord.js';
 export const name = Events.ClientReady;
 export const once = true;
 export function execute(client) {
  console.log(`Ready! Logged in as ${client.user.tag}`);
 }
 ```
 ### Шаг 4: Определение контроллера (Опционально)
 Для логики, требующей сохранения состояния, реализуйте контроллер в папке `lib/` и экспортируйте его в `module.ts`.
 ### Шаг 5: Валидация
 Перезапустите бота.
 1.  Проверьте логи на наличие "Loaded module: my-feature".
 2.  Убедитесь, что команда `/ping` появилась в Discord.
 {{% /steps %}}
 ## Шаблоны интеграции
 | Паттерн | Сценарий использования | Компоненты |
 | :--- | :--- | :--- |
 | **Простая команда** | Утилиты без состояния (Ping, Бросок кубиков) | Только `commands/` |
 | **Сервис с состоянием** | Музыка, RPG, Экономика | `commands/` + `lib/Controller` |
 | **Событийно-ориентированный** | Автомодерация, Логирование | Только `events/` |
 | **Гибридный** | Сложные функции (ИИ-чат) | Все компоненты |
 ---
 **См. также:**
 - [Руководство Discord.js: Slash-команды](https://discordjs.guide/creating-your-bot/slash-commands.html)
@@ -0,0 +1,63 @@
 ---
 title: Интерактивные голосовые функции
 weight: 3
 ---
 **Цель:** Реализовать сложные голосовые взаимодействия, которые учитывают границы серверов (гильдий) и управляют временными ресурсами.
 ## 1. Стратегия ограничения ресурсов
 Голосовые функции **ОБЯЗАТЕЛЬНО** должны быть ограничены рамками Гильдии (Guild).
 - **Паттерн:** Контроллер поддерживает `Map<GuildID, Player>`.
 - **Поведение:**
  - **Подключение (Join):** Создать Player для `Гильдии A`, если он еще не существует.
  - **Отключение (Leave):** Уничтожить Player и освободить соединения.
  - **Изоляция:** Команды в `Гильдии B` никогда не влияют на `Гильдию A`.
 ## 2. Оркестрация команд
 Голосовые функции требуют набора команд, координируемых через Контроллер.
 | Команда | Действие | Логика Контроллера |
 | :--- | :--- | :--- |
 | `/join` | Подключиться к каналу | `createPlayer(guildId, channelId)` |
 | `/play` | Добавить трек в очередь | `getPlayer(guildId).enqueue(track)` |
 | `/stop` | Отключиться | `destroyPlayer(guildId)` |
 ## 3. Сохранение состояния
 Аудиосессии эфемерны.
 - **Временное состояние:** Активный аудиопоток (Теряется при отключении).
 - **Постоянное состояние:** Очередь / Плейлист (Сохраняется в Контроллере до перезапуска).
 > [!TIP]
 > **Устойчивость:** Разделяйте логику _Очереди_ и логику _Голосового соединения_. Это позволяет боту переподключаться без потери плейлиста пользователя.
 ## 4. Пример реализации
 ```typescript
 // lib/MusicController.ts
 class MusicController {
  private players = new Map<string, AudioPlayer>();
  getPlayer(guildId: string): AudioPlayer {
    if (!this.players.has(guildId)) {
      this.players.set(guildId, new AudioPlayer());
    }
    return this.players.get(guildId);
  }
  destroyPlayer(guildId: string) {
    this.players.get(guildId)?.disconnect();
    this.players.delete(guildId);
  }
 }
 ```
 ---
 **См. также:**
 - [Руководство Discord.js Voice](https://discordjs.guide/voice/)
@@ -0,0 +1,12 @@
 ---
 title: Устранение неполадок
 weight: 5
 ---
 Устранение неполадок в **Quetza** фокусируется на диагностике структурных и концептуальных проблем. Из-за его природы, основанной на соглашениях (convention-based), большинство ошибок протекают бесшумно (отсутствующие файлы), а не с шумом (трассировка стека/stack traces).
 ## Основные категории проблем
 {{% cards %}}
 {{< card link="diagnostics" title="Руководство по диагностике" icon="exclamation" subtitle="Решения для обнаружения модулей, регистрации команд и утечек состояния." >}}
 {{% /cards %}}
@@ -0,0 +1,73 @@
 ---
 title: Диагностика
 weight: 1
 ---
 **Цель:** Определить и устранить распространенные ловушки при разработке Quetza.
 ## 1. Сбои при обнаружении модулей
 **Симптом:** Бот запускается, но ваш модуль игнорируется.
 **Причина:** Нарушение соглашений файловой системы.
 {{% details title="Чек-лист: Структура директорий" closed="false" %}}
 - [ ] Существует ли `src/modules/<name>/`?
 - [ ] Экспортирует ли `module.ts` переменную `name`?
 - [ ] Находятся ли команды в `commands/` (а не в `cmds/`)?
 - [ ] Запустили ли вы `pnpm build`? (Quetza запускается из `dist/`).
      {{% /details %}}
 ## 2. Проблемы с регистрацией команд
 **Симптом:** Команда `/command` не появляется в Discord.
 ### Глобальная регистрация против регистрации в тестовой гильдии (Guild)
 - **Глобальная:** Команды, отправленные в приложение глобально, могут обновляться до 1 часа и подчиняются более строгим ограничениям скорости (rate limits).
 - **Тестовая гильдия:** Quetza автоматически отправляет команды в конкретную гильдию в режиме разработки для мгновенного обновления.
  - **Требование:** Убедитесь, что `NODE_ENV=development` и `DEV_GUILD_ID` корректно установлены в вашем `.env`.
 ### Ограничения скорости (Rate Limits)
 Частые обновления глобальных команд могут вызвать ограничения скорости со стороны Discord. Используйте тестовую гильдию для итеративной разработки.
 ## 3. Ошибки взаимодействия (Interaction Failures)
 **Симптом:** «Приложение не отвечает».
 **Причина:** Выполнение команды заняло более 3 секунд без отложенного ответа (deferral).
 **Решение:**
 ```typescript
 // ПЛОХО
 await longRunningTask();
 await interaction.reply('Готово'); // Слишком поздно!
 // ХОРОШО
 await interaction.deferReply();
 await longRunningTask();
 await interaction.editReply('Готово');
 ```
 ## 4. Утечки состояния
 **Симптом:** Потребление памяти ботом растет; странности во взаимодействии между серверами.
 **Причина:** Хранение состояния глобально вместо уровня гильдии.
 **Диагностика:**
 Проверьте ваш контроллер.
 - ❌ `private player: AudioPlayer;` (Общий для всех!)
 - ✅ `private players = new Map<string, AudioPlayer>();` (Разделен по ID гильдии).
 ## 5. Обработка событий
 **Симптом:** События срабатывают несколько раз или не срабатывают вовсе.
 - **Несколько раз:** События являются аддитивными. Не зарегистрировали ли вы один и тот же обработчик в двух модулях?
 - **Ни разу:** Правильно ли вы экспортировали `name` и `execute`?
 > [!TIP]
 > **Debug Mode:**
 > Включите подробное логирование, чтобы точно увидеть, какие модули и команды загружаются при запуске.
@@ -1,12 +1,33 @@
 ---
-title: 'root.ermnvldmr.com'
+title: Documentation of ermnvldmr.com root deployment commons
-description: 'Документация к инфраструктуре root.ermnvldmr.com'
+description: Документация общих модулей корневой инфраструктуры ermnvldmr.com.
 weight: 1
 type: docs
 cascade:
  type: docs
 ---
-Различные заметки, сделанные в процессе разработки этой инфраструктуры.
+Фреймворк `ermnvldmr.com-root-commons` предоставляет среду развертывания с минимальными зависимостями для независимых self-hosted проектов.
 Общая логика, скрипты и шаблоны развертывания, используемые в различных приложениях, хранятся в репозитории [GitHub: ermnvldmr.com-root-commons](https://github.com/deytenit/ermnvldmr.com-root-commons).
 ## Основные возможности
 - **Smart Dispatcher**: Единая точка входа (`root`) для всех задач оркестрации.
 - **Tiered Storage**: Стандартизированная классификация для конфигураций, данных и логов.
 - **Privilege Isolation**: Изоляция привилегий через выделенных non-root пользователей для каждого проекта.
 - **Namespaced Libraries**: Явные модульные Bash-утилиты для обеспечения согласованной автоматизации.
 ## Разделы
- **[Рецепты](recipes/)** -- Пошаговые инструкции,
+{{% cards %}}
-  которые мне не хочется изобретать каждый раз снова.
+{{< card link="concepts" title="Концепции" icon="book-open" subtitle="Теоретические основы, архитектура и модели безопасности." >}}
 {{< card link="guides" title="Руководства" icon="map" subtitle="Пошаговые инструкции по установке и разработке Action-скриптов." >}}
 {{< card link="reference" title="Справочник" icon="code" subtitle="API и технические справочники для разработчиков." >}}
 {{% /cards %}}
 ---
 **See also:**
 - [GitHub: ermnvldmr.com-root-commons](https://github.com/deytenit/ermnvldmr.com-root-commons)
@@ -0,0 +1,14 @@
 ---
 title: Концепции
 description: Теоретические основы, архитектура и модели безопасности.
 weight: 10
 ---
 Теоретические основы, архитектура и модели безопасности общих модулей корневой инфраструктуры ermnvldmr.com.
 {{% cards %}}
 {{< card link="principles" title="Принципы инфраструктуры" icon="book-open" subtitle="Предсказуемость, минимум зависимостей и децентрализация." >}}
 {{< card link="architecture" title="Архитектура инфраструктуры" icon="share" subtitle="Децентрализованная оркестрация и модели развертывания." >}}
 {{< card link="security-model" title="Модель безопасности и изоляция" icon="shield-check" subtitle="Изоляция привилегий и защита сети." >}}
 {{< card link="tiered-storage" title="Модель многоуровневого хранения" icon="database" subtitle="Стандартизированная классификация хранения данных сервисов." >}}
 {{% /cards %}}
@@ -0,0 +1,71 @@
 ---
 title: Архитектура инфраструктуры
 description: Децентрализованная модель оркестрации и структура развертывания.
 weight: 10
 ---
 Фреймворк Root работает на децентрализованной модели оркестрации, разработанной для независимых, самодостаточных проектов. Он обеспечивает строгое разделение между оркестратором («мозгом») и задачами автоматизации («мышцами»).
 ## Основная философия {#philosophy}
 Фреймворк построен на принципе **Smart Root, Stupid Actions** («Умный Root, глупые Action-скрипты»). Такой дизайн гарантирует, что отдельные скрипты автоматизации остаются декларативными и не знают о глобальном состоянии системы, в то время как центральный диспетчер берет на себя разрешение окружения и инициализацию библиотек.
 ### Smart Root (Диспетчер)
 Точка входа `root` является единственным интерфейсом для пользователей. Она отвечает за:
 - **Разрешение окружения** &rarr; Поиск репозиториев `commons` и `configs`.
 - **Подготовка библиотек** &rarr; Разовая загрузка пространств имен (modules) библиотек.
 - **Установление контекста** &rarr; Определение целевого [Узла (Node)](/root/glossary#node) и связанных с ним путей.
 ### Stupid Actions (Задачи)
 [Action-скрипты (Actions)](/root/glossary#action) — это декларативные скрипты, расположенные в `scripts/actions/`. Они называются «глупыми», потому что:
 - Они не вычисляют пути и не ищут репозитории.
 - Они полностью зависят от переменных окружения `ROOT_`.
 - Они фокусируются исключительно на одной атомарной задаче (например, `compose`, `ufw`).
 ## Модель развертывания {#deployment}
 Они обычно развертываются как общий репозиторий [Commons](/root/glossary#commons), подключенный как Git-субмодуль внутри репозитория конфигураций. Движок, на котором построена эта общая инфраструктура, размещен по адресу [GitHub: ermnvldmr.com-root-commons](https://github.com/deytenit/ermnvldmr.com-root-commons).
 {{< filetree/container >}}
 {{< filetree/folder name="configs-repo" state="open" >}}
  {{< filetree/folder name=".operator" state="open" >}}
    {{< 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" 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="daedalus (node)" >}}
    {{< filetree/file name="docker-compose.yml" >}}
  {{< /filetree/folder >}}
  {{< filetree/file name="init.sh (bootstrap)" >}}
 {{< /filetree/folder >}}
 {{< /filetree/container >}}
 ---
 **See also:**
 - [Concept: The ROOT_ API](/root/reference/root-api)
 - [Guide: Installation](/root/guides/installation)
 - [GitHub: ermnvldmr.com-root-commons](https://github.com/deytenit/ermnvldmr.com-root-commons)
 -commons)
@@ -0,0 +1,33 @@
 ---
 title: Принципы инфраструктуры
 description: Основные принципы, обеспечивающие безопасную, предсказуемую среду с минимальными зависимостями.
 weight: 5
 ---
 Общие модули построены на ключевых принципах, предназначенных для обеспечения безопасной, предсказуемой среды с минимальными зависимостями для независимых self-hosted проектов.
 ## Предсказуемость через структуру {#predictability}
 Ручная настройка сервера подвержена «дрейфу конфигурации» (configuration drift), когда хосты, которые должны быть идентичными, со временем начинают различаться. Общие модули решают эту проблему следующим образом:
 - **Git как источник истины**: Каждая конфигурация, от правил UFW до crontab, хранится в репозитории.
 - **Идемпотентная автоматизация**: [Action-скрипты](/root/glossary#action) разработаны так, чтобы их можно было запускать многократно без побочных эффектов, гарантируя, что хост всегда соответствует заданному состоянию.
 ## Минимальное количество зависимостей {#minimalism}
 Для обеспечения долгосрочной поддерживаемости общие модули избегают сложных инструментов управления конфигурацией (таких как Ansible или Salt). Вместо этого они полагаются на:
 - **Bash**: Универсальный язык Unix-систем.
 - **Docker**: Для изоляции приложений и согласованности окружения.
 - **Стандартные инструменты Linux**: Прямое использование `systemd`, `ufw` и `cron`.
 ## Децентрализация {#decentralization}
 Каждый [Узел (Node)](/root/glossary#node) является независимым. Хотя они используют библиотеку общих модулей ([Commons](/root/glossary#commons)), они не зависят от центрального «мастер»-сервера. Такая архитектура гарантирует, что сбой на одном хосте не повлияет на несвязанные сервисы.
 ---
 **См. также:**
 - [Концепция: Модель безопасности и изоляция](/root/concepts/security-model)
 - [Концепция: Модель многоуровневого хранения](/root/concepts/tiered-storage)
@@ -0,0 +1,64 @@
 ---
 title: Безопасность и изоляция привилегий
 description: Меры безопасности, изоляция привилегий и песочница на уровне проектов.
 weight: 20
 ---
 Безопасность в Root достигается за счет строгой изоляции привилегий и создания «песочниц» на уровне проектов для минимизации последствий в случае взлома отдельных сервисов.
 ## Принцип «No-Root» {#noroot}
 Запуск приложений под пользователем `root` внутри контейнеров является значительным риском безопасности. Общие модули обеспечивают изоляцию с помощью действий `tiers/useradd` и `tiers/chown`.
 ### Пользователи для конкретных проектов
 Каждому проекту, расположенному по пути `{repository root}/{node}/{project}`, назначается выделенный системный пользователь на хосте.
 - **Изоляция**: Если контейнер будет взломан, злоумышленник получит только привилегии этого конкретного низкопривилегированного пользователя.
 - **Безопасность файловой системы**: Проекты могут читать и записывать данные только в свои собственные директории в рамках [Уровней (Tiers)](/root/glossary#tier).
 ## Защита сокета Docker {#socket-protection}
 Прямой доступ к `/var/run/docker.sock` эквивалентен правам root на хосте. В качестве лучшей практики настоятельно рекомендуется защищать сокет Docker. Один из способов достижения этого — использование **Socket Proxy** (например, на базе `tecnativa/docker-socket-proxy`) для фильтрации и ограничения доступа к Docker API.
 ```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:
      # Использовать прокси вместо локального сокета
      - "--providers.docker.endpoint=tcp://root-socket-proxy:2375"
    networks:
      socket: {}
 ```
 ## Мониторинг безопасности (CrowdSec) {#crowdsec}
 Фреймворк интегрирует **CrowdSec** для поведенческого анализа и автоматического реагирования.
 - **Обнаружение вторжений**: CrowdSec отслеживает логи [Traefik](https://traefik.io/) и SSH на предмет подозрительных паттернов (например, брутфорс-атаки, сканирование портов).
 - **Автоматическая блокировка**: При обнаружении угрозы **CrowdSec Firewall Bouncer** автоматически обновляет правила [UFW](https://help.ubuntu.com/community/UFW), блокируя вредоносный IP на уровне хоста.
 - **Обмен данными об угрозах**: CrowdSec делится анонимизированными данными об угрозах со своим сообществом, обеспечивая превентивную защиту от известных злоумышленников.
 ## Сетевое ужесточение {#networking}
 Root использует `configure/ufw` для реализации политики «Запрещено по умолчанию» (Default Deny).
 - **Внутренняя маршрутизация**: Сервисы взаимодействуют через выделенную сеть-мост `root-proxy`, которая часто настраивается как `internal: true`.
 - **Изоляция анклавов**: Исходящий трафик может быть направлен через выделенный узел выхода (egress node) для детального контроля.
@@ -0,0 +1,71 @@
 ---
 title: Модель многоуровневого хранения
 description: Стандартизированная таксономия хранения данных сервисов.
 weight: 15
 ---
 Фреймворк навязывает стандартизированную таксономию хранения. Это гарантирует, что каждый сервис имеет предсказуемое местоположение для своих данных, что упрощает стратегии резервного копирования и распределение оборудования.
 ## Таксономия хранения {#taxonomy}
 Данные разделены на три логических [Уровня (Tiers)](/root/glossary#tier) на основе их требований к производительности, жизненного цикла и важности.
 ### Уровень 1 (Tier 1): Конфигурации и Кэш
 **Путь:** `${ROOT_NODE_DIR}/@tier1`
 - **Содержимое**: Конфигурационные файлы, небольшие базы данных SQLite, SSL-сертификаты, кэш приложений.
 - **Характеристики**: Чрезвычайно высокая ценность, объем от низкого до среднего, требует минимальных задержек (latency).
 - **Оборудование**: Высокоскоростные SSD-накопители, обычно общие с операционной системой.
 ### Уровень 2 (Tier 2): Данные приложений
 **Путь:** `${ROOT_NODE_DIR}/@tier2`
 - **Содержимое**: Пользовательские загрузки, большие базы данных, постоянное состояние приложений.
 - **Характеристики**: Высокая ценность, объем от среднего до высокого, требует высокой надежности.
 - **Оборудование**: Надежные HDD-кластеры, RAID-массивы или выделенные хранилища.
 ### Уровень 3 (Tier 3): Временные файлы и объемные медиа
 **Путь:** `${ROOT_NODE_DIR}/@tier3`
 - **Содержимое**: Логи, временные файлы, объемные медиа (фильмы, музыка) и другие некритичные большие данные.
 - **Характеристики**: Низкая ценность, очень высокий объем.
 - **Оборудование**: HDD большой емкости, оптимизированные для непрерывной последовательной записи/чтения (например, WD Purple). Обратите внимание, что Tier 3 **слишком медленный для кэша**.
 ## Стратегия резервного копирования {#backup}
 Общие модули не навязывают конкретную стратегию резервного копирования и не предоставляют реализацию по умолчанию, обеспечивая полную гибкость на уровне узла. Ожидается, что операторы сами реализуют логику резервного копирования.
 ### Пример: Резервное копирование с помощью Restic
 Распространенной лучшей практикой является использование **Restic** для резервного копирования. Например, вы можете создать файл compose узла оператора для запуска 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
    network_mode: "host"
    entrypoint: [ "restic" ]
    user: "0:0"
 ```
 ### Реализация стратегии
 Операторы могут реализовать свою стратегию, определив локальный Action в `.operator/local/scripts/actions/sync/tiers`. Диспетчер `root` затем сможет выполнить этот скрипт для запуска резервного копирования, позволяя детально контролировать способ сохранения данных.
 ## Обоснование {#justification}
 1. **Оптимизация оборудования**: Сопоставляя уровни с конкретным оборудованием (SSD для Tier 1, RAID для Tier 2, Purples для Tier 3), мы оптимизируем как производительность, так и стоимость.
 2. **Выборочное резервное копирование**: Отделение временных логов и объемных медиа (Tier 3) от критических конфигураций (Tier 1) предотвращает трату дорогостоящего места в хранилище резервных копий.
 3. **Архитектурная ясность**: Любой оператор может проинспектировать директорию [Узла (Node)](/root/glossary#node) и сразу понять требования к хранению и приоритет его содержимого.
@@ -0,0 +1,41 @@
 ---
 title: Глоссарий
 description: Терминология, используемая в рамках общих модулей корневой инфраструктуры.
 weight: 100
 ---
 Терминология, используемая в рамках общих модулей корневой инфраструктуры ermnvldmr.com.
 ## Action {#action}
 **Action (Действие)** - Атомарная задача автоматизации, расположенная в `scripts/actions/`. Action-скрипты следуют философии "Stupid Action" («Глупое действие»), оставаясь декларативными и полагаясь на диспетчер `root` для настройки окружения.
 ## Commons {#commons}
 **Commons (Общие модули)** - Общий репозиторий, содержащий общую логику, модульные библиотеки и стандартизированные действия автоматизации, используемые на всех узлах. Ссылка на [GitHub: ermnvldmr.com-root-commons](https://github.com/deytenit/ermnvldmr.com-root-commons).
 ## Dispatcher {#dispatcher}
 **Dispatcher (Диспетчер)** - Скрипт `root`, который служит точкой входа. Он разрешает пути, подготавливает окружение и выполняет запрошенный [Action](/root/glossary#action).
 ## Node {#node}
 **Node (Узел)** - Физический или виртуальный хост, управляемый общими модулями. Каждый узел имеет выделенную директорию в репозитории конфигураций, содержащую его сервисы и локальные настройки.
 ## Root {#root}
 **Root** - Имя утилиты командной строки, а также сервис оркестрации верхнего уровня внутри [Узла (Node)](/root/glossary#node) (обычно обрабатывающий Traefik и AdGuard).
 ## Tier {#tier}
 **Tier (Уровень)** - Стандартизированная классификация хранения данных сервисов.
 - **Tier 1 (Уровень 1)**: Конфигурация и критическое состояние.
 - **Tier 2 (Уровень 2)**: Данные приложений и базы данных.
 - **Tier 3 (Уровень 3)**: Логи, кэши и объемные медиафайлы.
 ---
 **См. также:**
 - [Концепция: Архитектура инфраструктуры](/root/concepts/architecture)
 - [Концепция: Модель многоуровневого хранения](/root/concepts/tiered-storage)
@@ -0,0 +1,13 @@
 ---
 title: Руководства
 description: Пошаговые инструкции по установке и разработке Action-скриптов.
 weight: 20
 ---
 Пошаговые инструкции по установке и разработке в рамках общих модулей корневой инфраструктуры ermnvldmr.com.
 {{% cards %}}
 {{< card link="first-node" title="Создание вашего первого узла" icon="map" subtitle="Практическое руководство по созданию репозитория конфигураций." >}}
 {{< card link="installation" title="Установка" icon="arrow-down" subtitle="Первоначальная настройка общих модулей на новом хосте." >}}
 {{< card link="action-development" title="Разработка Action-скриптов" icon="code" subtitle="Создание и управление атомарными задачами автоматизации." >}}
 {{% /cards %}}
@@ -0,0 +1,67 @@
 ---
 title: Разработка Action-скриптов
 description: Разработка атомарных задач автоматизации в рамках общих модулей.
 weight: 30
 ---
 [Action-скрипты](/root/glossary#action) — это атомарные задачи автоматизации. Следуя философии "Stupid Action" («Глупое действие»), они должны оставаться декларативными и полагаться на библиотеку для выполнения сложных операций.
 ## Создание нового Action-скрипта {#create}
 {{% steps %}}
 ### Шаг 1: Создание файла скрипта
 Поместите ваш скрипт в `scripts/actions/{group}/{name}`. Не используйте расширения файлов.
 ### Шаг 2: Реализация метаданных
 Каждый Action-скрипт должен предоставлять описание и список аргументов для системы справки (help system).
 ```bash filename="scripts/actions/utils/my-action"
 action_metadata() {
  cat <<EOF
 description: "Краткое описание задачи."
 args:
  - NODE: "Имя узла"
  - PARAM: "Пользовательский параметр"
 EOF
 }
 ```
 ### Шаг 3: Инициализация контекста
 Используйте вспомогательную функцию `root_require_node` для настройки окружения. Это должно быть первым функциональным шагом в вашем скрипте.
 ```bash filename="scripts/actions/utils/my-action"
 root_require_node "${1:-}"
 shift
 ```
 ### Шаг 4: Использование модульных функций
 Выполняйте операции, используя библиотечные функции `root_*`. Полагайтесь на переменные окружения `ROOT_` для всех путей.
 ```bash filename="scripts/actions/utils/my-action"
 root_log_info "Обработка узла $ROOT_NODE"
 root_sys_restart_service "my-service"
 ```
 {{% /steps %}}
 ## Пространства имен библиотек {#libraries}
 Action-скрипты имеют доступ к следующим модулям:
 - `root_core_*`: Логирование и уведомления в Telegram.
 - `root_init_*`: Декларативная инициализация сервисов и управление пакетами.
 - `root_sys_*`: Управление systemd и файлами юнитов.
 - `root_template_*`: Рендеринг на основе envsubst и внедрение конфигураций.
 - `root_validate_*`: Проверка ввода, файлов и ОС.
 ---
 **См. также:**
 - [Справочник: Справочник ROOT_ API](/root/reference/root-api)
 - [Концепция: Архитектура инфраструктуры](/root/concepts/architecture)
@@ -0,0 +1,190 @@
 ---
 title: "Создание узла (First Node)"
 description: Практическое руководство по созданию вашего первого узла и подключению общих модулей.
 weight: 25
 ---
 **Цель:** Создать репозиторий конфигураций для вашей собственной инфраструктуры, подключить общие модули в качестве подмодуля (submodule) и запустить первый базовый узел.
 ## 1. Создание репозитория конфигураций
 Ваша инфраструктура должна управляться из единого Git-репозитория. Этот репозиторий будет содержать конфигурации для всех ваших серверов (узлов).
 {{% steps %}}
 ### Шаг 1: Инициализация репозитория
 Создайте новую директорию и инициализируйте Git.
 ```bash
 mkdir my-infrastructure
 cd my-infrastructure
 git init
 ```
 ### Шаг 2: Добавление общих модулей как подмодуля
 Общие модули (`ermnvldmr.com-root-commons`) должны располагаться по пути `.operator/shared`.
 ```bash
 mkdir -p .operator
 git submodule add https://github.com/deytenit/ermnvldmr.com-root-commons.git .operator/shared
 ```
 ### Шаг 3: Создание загрузочного скрипта (Bootstrap)
 Создайте файл `init.sh` в корне вашего репозитория. Этот скрипт свяжет общие модули с вашим локальным окружением.
 ```bash filename="init.sh"
 #!/usr/bin/env bash
 # init.sh
 # Загрузка общих утилит из подмодуля
 source "$(git -C "$(dirname "$0")" rev-parse --show-toplevel)/.operator/shared/scripts/lib/common.sh"
 SCRIPT_NAME="init"
 navigate_to_repo_root
 log_info "Настройка Git hooks..."
 git config core.hooksPath .operator/shared/githooks
 git config --global --add safe.directory "${REPO_ROOT}"
 log_info "Настройка PATH для диспетчера root..."
 ABSOLUTE_RUN_DIR="$(realpath "${REPO_ROOT}/.operator/shared/scripts/run")"
 BASHRC_ENTRY="export PATH=\"${ABSOLUTE_RUN_DIR}:\$PATH\""
 sed -i '/\.operator\/shared\/scripts\/run/d' ~/.bashrc
 echo "$BASHRC_ENTRY" >> ~/.bashrc
 log_info "Готово. Выполните 'source ~/.bashrc' или перезайдите в терминал."
 ```
 Сделайте его исполняемым:
 ```bash
 chmod +x init.sh
 ```
 {{% /steps %}}
 ## 2. Определение вашего первого узла
 Узел (Node) — это папка в корне репозитория, которая представляет один физический или виртуальный сервер.
 ### Структура узла
 Давайте создадим узел с именем `daedalus`. Внутри него мы определим конфигурацию оператора (например, для резервного копирования) и базовый сервис.
 ```bash
 mkdir -p daedalus/.operator/configs/{cron,crowdsec,systemd,ufw/docker,ufw/host}
 mkdir -p daedalus/root
 ```
 ### Базовые настройки (Опционально)
 Вы можете добавить файлы конфигурации (например, правила UFW или crontab) в директорию `daedalus/.operator/configs/`. Например, простой crontab:
 ```bash filename="daedalus/.operator/configs/cron/crontab.template"
 # Запуск резервного копирования каждую ночь в 3:00
 0 3 * * * root sync tiers daedalus
 ```
 ## 3. Настройка сервисов (Docker Compose)
 Фреймворк опирается на `docker-compose.yml`.
 ### Инфраструктурный уровень (Узел оператора)
 Файл `daedalus/docker-compose.yml` запускает инфраструктурные утилиты, такие как `restic` для бекапов или VPN-агенты. Этот compose-файл имеет прямой доступ к файловой системе через монтирование директорий `@tierX`.
 ```yaml filename="daedalus/docker-compose.yml"
 name: 'operator'
 services:
  restic:
    image: restic/restic:0.18.1
    container_name: operator-restic
    volumes:
      # Пример: монтирование данных для резервного копирования (Только для чтения)
      - ./@tier2/my-app/data:/data/@tier2/my-app/data:ro
      - ./@tier3/.operator/restic/cache:/var/restic-cache
    environment:
      RESTIC_REPOSITORY: "s3:example.com/my-bucket/daedalus"
      RESTIC_PASSWORD: "${RESTIC_PASSWORD?error}"
      # Данные AWS...
    network_mode: "host"
    entrypoint: [ "restic" ]
 ```
 ### Корневой уровень (Root)
 Проект `root` обычно содержит обратные прокси (Traefik) и сервисы, к которым обращаются другие проекты.
 ```yaml filename="daedalus/root/docker-compose.yml"
 name: root
 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:
    image: traefik:3.6
    container_name: root-traefik
    # UID и GID подставляются автоматически фреймворком после команды 'root tiers useradd'
    user: "${UID?error}:${GID?error}"
    group_add:
      - "${SHARED_GID?error}"
    depends_on:
      - socket-proxy
    volumes:
      - ./@tier1/shared/root/traefik/letsencrypt:/letsencrypt
      - ./@tier3/traefik/logs:/logs
      - ./@tier1/traefik/dynamic:/etc/traefik/dynamic:ro
    ports:
      - '0.0.0.0:80:80'
      - '0.0.0.0:443:443'
    networks:
      proxy: {}
      socket: {}
    command:
      - "--api.dashboard=true"
      - "--providers.docker=true"
      - "--providers.docker.network=root-proxy"
      - "--providers.docker.endpoint=tcp://root-socket-proxy:2375"
    restart: unless-stopped
 networks:
  proxy:
    name: root-proxy
    internal: true
    driver: bridge
  socket:
    name: root-socket
    internal: true
    driver: bridge
 ```
 ## 4. Развертывание
 Теперь, когда структура создана:
 1. Закоммитьте и отправьте (push) этот репозиторий на ваш Git-сервер (например, GitHub).
 2. Зайдите на ваш VPS.
 3. Следуйте руководству по [Установке (Installation)](/root/guides/installation), используя URL вашего нового репозитория.
 ---
 **См. также:**
 - [Руководство: Установка на новый хост](/root/guides/installation)
 - [Концепция: Архитектура инфраструктуры](/root/concepts/architecture)
@@ -41,10 +41,10 @@ groupadd wheel
 # Создать модульный файл sudoers
 # Это позволяет членам группы 'wheel' запускать sudo без пароля
-echo "%wheel ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/99-root-ermnvldmr
+echo "%wheel ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/99-custom-sudoers
 # Проверить синтаксис
-visudo -c -f /etc/sudoers.d/99-root-ermnvldmr
+visudo -c -f /etc/sudoers.d/99-custom-sudoers
 # Добавить adam в необходимые группы
 usermod -aG wheel,docker adam
@@ -92,10 +92,10 @@ chown -R adam:adam /home/adam/.ssh
 ```bash
 # ~/.ssh/config на стороне оператора
-Host daedalus.root.ermnvldmr.com
+Host daedalus.example.com
  Port 2222
  User adam
-  IdentityFile ~/.ssh/adam_root_ermnvldmr_com_ed25519
+  IdentityFile ~/.ssh/adam_example_com_ed25519
 ```
 **Усиление демона SSH**
@@ -105,7 +105,7 @@ Host daedalus.root.ermnvldmr.com
 ```bash
 # От имени root:
 # Создать выделенный файл конфигурации
-cat <<EOF > /etc/ssh/sshd_config.d/99-root-ermnvldmr.conf
+cat <<EOF > /etc/ssh/sshd_config.d/99-custom-ssh.conf
 Port 2222
 PasswordAuthentication no
 PermitEmptyPasswords no
@@ -137,21 +137,21 @@ cat /home/adam/.ssh/github_ed25519.pub
 ```
 > [!TIP]
-> Добавьте вывод выше в [GitHub: Repository Deploy Keys](https://github.com/deytenit/root.ermnvldmr.com/settings/keys) с правами **read access**.
+> Добавьте вывод выше в настройки Deploy Keys вашего репозитория инфраструктуры (например, `https://github.com/your-username/your-repo/settings/keys`) с правами **read access**.
 ### Развертывание репозитория
-Клонируйте инфраструктурный репозиторий и инициализируйте узел.
+Клонируйте репозиторий вашей инфраструктуры и инициализируйте узел.
 ```bash
 # От имени root:
-# Настроить директорию сервиса
+# Настройка директории сервиса
-export REPO_DIR="/srv/root.ermnvldmr.com"
+export REPO_DIR="/srv/your-infrastructure-repo"
 mkdir -p $REPO_DIR
 chown adam:adam $REPO_DIR
-# Клонировать от имени пользователя adam
+# Клонирование от имени пользователя adam
-sudo -u adam git clone git@github.com:deytenit/root.ermnvldmr.com.git $REPO_DIR
+sudo -u adam git clone git@github.com:your-username/your-repo.git $REPO_DIR
 # Инициализировать узел (Установите имя вашего узла, например, daedalus)
 export NODE="daedalus"
@@ -161,16 +161,15 @@ sudo -u adam ./init.sh
 **Специфичная для узла конфигурация**
-Запустите скрипты инициализации по порядку:
+Запустите скрипты инициализации с помощью диспетчера `root`:
 ```bash
-# От имени root:
+# Выполните последовательность для вашего конкретного узла (от имени пользователя 'adam')
-# Выполните последовательность для вашего конкретного узла
+# Убедитесь, что вы выполнили 'source ~/.bashrc' или переподключились, если команда 'root' не найдена
-cd $REPO_DIR
+root configure base $NODE
-./$NODE/.host/.scripts/00-base
+root configure ufw $NODE
-./$NODE/.host/.scripts/10-ufw
+root configure crowdsec $NODE
-./$NODE/.host/.scripts/20-crowd
+root configure cron $NODE
 ./$NODE/.host/.scripts/30-cron
 ```
 ### Хранение и усиление безопасности
@@ -178,18 +177,17 @@ cd $REPO_DIR
 Определите уровни данных (tiers) и защитите среду, создав непривилегированных пользователей для контейнеризированных сервисов.
 ```bash
 # От имени root:
 # Создать (или примонтировать) директории хранилища
-mkdir -p /srv/com-ermnvldmr-root-$NODE-{tier1,tier2,tier3}
+sudo mkdir -p /srv/my-infrastructure-root-$NODE-{tier1,tier2,tier3}
 # Настроить уровни и непривилегированных пользователей
-cd $REPO_DIR
+root tiers link $NODE \
-sudo -u adam .scripts/ops/setup-tiers $NODE
+  /srv/my-infrastructure-root-$NODE-tier1 \
-  /srv/com-ermnvldmr-root-$NODE-tier1
+  /srv/my-infrastructure-root-$NODE-tier2 \
-  /srv/com-ermnvldmr-root-$NODE-tier2
+  /srv/my-infrastructure-root-$NODE-tier3
  /srv/com-ermnvldmr-root-$NODE-tier3
-sudo -u adam .scripts/ops/setup-noroot-users $NODE
+root tiers useradd $NODE
 root tiers chown $NODE
 ```
 {{% /steps %}}
@@ -199,4 +197,3 @@ sudo -u adam .scripts/ops/setup-noroot-users $NODE
 **См. также:**
 - [Doc: Docker - Install on Debian](https://docs.docker.com/engine/install/debian/)
 - [GitHub: root.ermnvldmr.com](https://github.com/deytenit/root.ermnvldmr.com)
@@ -1,11 +0,0 @@
 ---
 title: 'Рецепты'
 description: 'Пошаговые инструкции, которые мне не хочется изобретать каждый раз снова.'
 weight: 50
 type: docs
 ---
 Пошаговые инструкции,
 которые мне не хочется изобретать каждый раз снова.
 ## Что здесь
@@ -0,0 +1,18 @@
 ---
 title: Справочник
 description: Справочные материалы и API для разработчиков.
 weight: 30
 ---
 Технические справочные материалы и API общих модулей корневой инфраструктуры ermnvldmr.com.
 {{% cards %}}
 {{< card link="compose" title="Справочник по действиям compose" icon="play" subtitle="Высокоуровневая точка входа для оркестрации docker-compose." >}}
 {{< card link="configure" title="Справочник по действиям настройки" icon="arrow-down" subtitle="Действия для настройки системного уровня." >}}
 {{< card link="initialization" title="Справочник по действиям инициализации" icon="play" subtitle="Действия для первоначальной настройки узла." >}}
 {{< card link="root-api" title="Справочник ROOT_ API" icon="code" subtitle="Стандартизированные переменные окружения и вспомогательные функции логирования." >}}
 {{< card link="source" title="Справочник по исходным сервисам" icon="book-open" subtitle="Общие сервисы, собираемые из исходного кода." >}}
 {{< card link="sync" title="Справочник по действиям синхронизации" icon="check" subtitle="Действия для поддержания узлов в актуальном состоянии." >}}
 {{< card link="tiers" title="Справочник по действиям уровней (Tiers)" icon="archive" subtitle="Управление уровнями хранения данных." >}}
 {{< card link="utils" title="Справочник по утилитам" icon="check" subtitle="Вспомогательные скрипты и утилиты." >}}
 {{% /cards %}}
@@ -0,0 +1,50 @@
 ---
 title: Операции Compose
 description: Стандартизированная точка входа для оркестрации docker-compose в масштабах узла.
 weight: 54
 ---
 Действие `compose` предоставляет стандартизированную высокоуровневую точку входа для оркестрации файлов Docker Compose для всех проектов в рамках определенного узла.
 ## Основная операция Compose {#actions}
 | Операция | Описание |
 | :--- | :--- |
 | `compose <node> <action>` | Выполняет заданную команду Docker Compose (например, `up`, `down`, `restart`) по всей инфраструктуре узла. |
 ## Порядок оркестрации {#order}
 Для поддержания правильных зависимостей (особенно при завершении работы или запуске прокси-серверов и сетей уровня инфраструктуры), действие `compose` интеллектуально упорядочивает выполнение:
 ### Запуск (`up`, `restart`)
 При запуске или перезапуске сервисов действие использует **Прямой порядок** (Forward Order):
 1. **Инфраструктура узла (Node Infra)**: Сначала обрабатывается файл `docker-compose.yml` уровня узла (находится в корне директории узла).
 2. **Корневая инфраструктура (Root Infra)**: Затем обрабатывается проект `root/docker-compose.yml`, если он существует (обычно содержит Traefik, Socket Proxy и т.д.).
 3. **Проекты**: Наконец, в алфавитном порядке обрабатываются все остальные директории проектов.
 ### Остановка (`down`)
 При остановке сервисов действие использует **Обратный порядок** (Reverse Order), чтобы проекты корректно отключились до того, как упадет сеть или прокси:
 1. **Проекты**: Все стандартные проекты останавливаются в обратном алфавитном порядке.
 2. **Корневая инфраструктура (Root Infra)**: Проект `root/docker-compose.yml` останавливается.
 3. **Инфраструктура узла (Node Infra)**: В самом конце отключается `docker-compose.yml` уровня узла.
 ## Опции {#options}
 Вы можете передавать стандартные аргументы Docker Compose в конец команды.
 Кроме того, действие поддерживает режим пробного запуска (dry-run):
 - `--dry-run`: Выводит команды, которые будут выполнены, без их фактического запуска.
 **Пример использования:**
 ```bash
 root compose daedalus up -d --remove-orphans
 root compose daedalus restart --dry-run
 root compose daedalus down
 ```
 ---
 **See also:**
 - [Концепция: Архитектура инфраструктуры](/root/concepts/architecture)
 - [Справочник: Справочник ROOT_ API Reference](/root/reference/root-api)
@@ -0,0 +1,66 @@
 ---
 title: Операции настройки (Configure)
 description: Подготовка хоста, движок шаблонов и конфигурация на уровне системы.
 weight: 53
 ---
 Операции настройки используются для подготовки хоста и обслуживания системных сервисов. Они в значительной степени полагаются на встроенный движок шаблонов для генерации декларативных конфигурационных файлов.
 ## Движок шаблонов {#template-engine}
 Общие модули используют `envsubst` (из пакета `gettext-base`) для рендеринга шаблонов. Это позволяет использовать стандартные переменные окружения Bash непосредственно в ваших конфигурационных файлах.
 ### Соглашения по шаблонам
 - **Расширение файлов**: Шаблоны обычно используют расширение `.template` (например, `crontab.template`).
 - **Синтаксис переменных**: Используйте `${VARIABLE_NAME}` или `$VARIABLE_NAME` для подстановки значений.
 - **Автоматический поиск**: Многие действия автоматически ищут шаблоны в определенных директориях внутри репозитория [Configs](/root/glossary#configs).
 ### Вспомогательные функции рендеринга
 Библиотека `root_template.sh` предоставляет несколько вспомогательных функций:
 - `root_template_render <input> <output>`: Рендерит один файл.
 - `root_template_render_directory <src> <dest>`: Рекурсивно рендерит всю структуру директории.
 - `root_template_crontab <template>`: Рендерит и устанавливает crontab для текущего пользователя.
 ## Основные операции настройки {#actions}
 | Операция | Описание |
 | :--- | :--- |
 | `configure/base` | Устанавливает основные пакеты (`sudo`, `ufw`, `docker`) и настраивает базовых системных пользователей. |
 | `configure/cron` | Рендерит и устанавливает специфичные для узла crontab-файлы. |
 | `configure/crowdsec` | Настраивает агента CrowdSec и баунсеры (bouncers). |
 | `configure/routing` | Настраивает маршрутизацию на уровне системы и сети-мосты (bridge networks). |
 | `configure/systemd` | Устанавливает и активирует юниты сервисов systemd. |
 | `configure/ufw` | Рендерит и применяет правила брандмауэра с помощью UFW и `ufw-docker`. |
 ## Пример: Шаблон Nginx {#example}
 ```nginx filename="nginx.conf.template"
 # Этот шаблон использует переменную окружения ROOT_NODE
 user  nginx;
 worker_processes  auto;
 error_log  /var/log/nginx/error.log notice;
 pid        /var/run/nginx.pid;
 events {
    worker_connections  1024;
 }
 http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    # Подставляется из окружения
    server_name ${ROOT_NODE}.example.com;
 }
 ```
 ---
 **See also:**
 - [Концепция: Архитектура инфраструктуры](/root/concepts/architecture)
 - [Справочник: Справочник ROOT_ API Reference](/root/reference/root-api)
@@ -0,0 +1,40 @@
 ---
 title: Инициализация системы
 description: Настройка репозитория, Git-хуки и конфигурация PATH.
 weight: 51
 ---
 Общие модули требуют однократной инициализации на каждом хосте для создания связей путей и конфигураций на уровне репозитория.
 ## Скрипт `init.sh` {#init-script}
 Скрипт `init.sh`, расположенный в корне репозитория, является основным механизмом начальной загрузки. Он выполняет следующие критические задачи:
 1. **Инициализация субмодулей**: Гарантирует наличие и актуальность репозитория [Commons](/root/glossary#commons).
 2. **Конфигурация Git-хуков**: Направляет `core.hooksPath` на `.operator/shared/githooks` для обеспечения стандартизированных проверок перед коммитом.
 3. **Регистрация безопасной директории (Safe Directory)**: Добавляет репозиторий в список `safe.directory` Git, что необходимо для операций, выполняемых разными пользователями (например, `root`, `adam`).
 4. **Конфигурация Vim**: Связывает стандартизированный `.vimrc` как для текущего пользователя, так и для пользователя `root` для обеспечения единообразия при редактировании.
 5. **Сохранение PATH**: Добавляет директорию `.operator/shared/scripts/run` в `~/.bashrc` пользователя, делая команду `root` доступной глобально.
 ## Git-хуки {#githooks}
 Root обеспечивает соблюдение стандартов через Git-хуки, хранящиеся в `.operator/shared/githooks/`.
 - **Pre-commit**: Проверяет, что все скрипты соответствуют соглашениям о пространствах имен и структуре.
 - **Commit-msg**: (Опционально) Обеспечивает соблюдение правил Conventional Commits, если это настроено.
 ## Конфигурация PATH {#path}
 Команда `root` — это обертка (wrapper), расположенная по адресу `.operator/shared/scripts/run/root`. Добавляя эту директорию в `PATH`, диспетчер можно вызывать из любой директории в системе; он автоматически определит корень репозитория на основе текущей рабочей директории или переменных окружения.
 ```bash
 # Пример добавления PATH вручную (выполняется автоматически скриптом init.sh)
 export PATH="$HOME/repo/.operator/shared/scripts/run:$PATH"
 ```
 ---
 **See also:**
 - [Руководство: Начальная настройка хоста](/root/guides/installation)
 - [Справочник: Справочник ROOT_ API Reference](/root/reference/root-api)
@@ -0,0 +1,62 @@
 ---
 title: Справочник ROOT_ API
 description: Стандартизированные переменные окружения и библиотеки ядра.
 weight: 50
 ---
 Каждый Action-скрипт, выполняемый через диспетчер `root`, имеет доступ к стандартизированному набору переменных окружения и Bash-библиотек. Это обеспечивает согласованный API для взаимодействия с инфраструктурой.
 ## Диспетчер `root` {#dispatcher}
 Команда `root` (находится в `.operator/shared/scripts/run/root`) является основной точкой входа для всей оркестрации. Ее основные обязанности включают:
 1. **Разрешение контекста**: Поиск целевого [Узла (Node)](/root/glossary#node) и связанных с ним [Уровней (Tiers)](/root/glossary#tier) хранилища.
 2. **Загрузка библиотек**: Подключение основных библиотек ядра (например, `root_core`, `root_sys`).
 3. **Выполнение Action-скриптов**: Поиск и запуск запрошенного действия, с приоритетом локальных переопределений.
 ## Переменные разрешения путей {#paths}
 Эти переменные устанавливаются диспетчером и доступны всем Action-скриптам.
 | Переменная | Описание |
 | :--- | :--- |
 | `ROOT_SHARED` | Абсолютный путь к репозиторию [Commons](/root/glossary#commons). |
 | `ROOT_CONFIGS` | Абсолютный путь к основному репозиторию конфигураций. |
 | `ROOT_LOCAL` | Абсолютный путь к директории локального оператора (`.operator/local`). |
 | `ROOT_ACTIONS_SHARED` | Путь к глобальным общим Action-скриптам. |
 | `ROOT_ACTIONS_LOCAL` | Путь к специфичным для узла локальным Action-скриптам. |
 ## Переменные контекста узла {#node-context}
 Когда действие нацелено на конкретный узел, следующие переменные устанавливаются вспомогательной функцией `root_require_node`.
 | Переменная | Описание |
 | :--- | :--- |
 | `ROOT_NODE` | Идентификатор целевого узла (например, `daedalus`). |
 | `ROOT_NODE_DIR` | Абсолютный путь к директории конфигурации узла. |
 | `ROOT_TIER1` | Абсолютный путь к директории [Уровня 1](/root/glossary#tier). |
 | `ROOT_TIER2` | Абсолютный путь к директории Уровня 2. |
 | `ROOT_TIER3` | Абсолютный путь к директории Уровня 3. |
 ## Основные функции логирования {#logging}
 Стандартизированное логирование обеспечивает согласованный вывод всех действий.
 - `root_log_info`: Стандартный информационный вывод.
 - `root_log_warn`: Предупреждения, требующие внимания.
 - `root_log_error`: Критические ошибки, отправляемые в `stderr`.
 - `root_log_success`: Подтверждение успешного завершения задачи.
 ## Система помощи {#help}
 Диспетчер предоставляет встроенную систему помощи, парся блок `action_metadata` в начале каждого скрипта. Это позволяет скриптам оставаться декларативными без реализации собственной обработки аргументов командной строки.
 ```bash filename="example-action-metadata"
 action_metadata() {
  cat <<EOF
 description: "Краткое описание действия."
 args:
  - NODE: "Имя целевого узла."
 EOF
 }
 ```
@@ -0,0 +1,42 @@
 ---
 title: Директория `source/`
 description: Концептуальный обзор структуры изолированной директории исходного кода.
 weight: 52
 ---
 Директория `source/` в корне репозитория содержит основные компоненты и проекты, которыми управляют общие модули. Она разработана для максимальной изоляции и самодостаточности.
 ## Основная философия {#philosophy}
 Директория `source/` — это не просто место для хранения кода; это коллекция независимых [Проектов](/root/glossary#project). Каждый проект в этой директории должен следовать следующим принципам:
 1. **Изоляция**: Каждый проект живет в своей поддиректории (например, `source/my-app/`).
 2. **Самодокументируемость**: Каждая директория проекта **ОБЯЗАНА** содержать собственный файл `README.md`, описывающий его назначение, зависимости и конфигурацию.
 3. **Внутренняя логика**: Проекты сами управляют своими процессами сборки, Docker-файлами и внутренними конфигурациями. [Action-скрипты](/root/glossary#action) фреймворка Root просто оркеструют эти существующие компоненты.
 ## Структура директории {#structure}
 Типичный проект в директории `source/` может выглядеть следующим образом:
 {{< filetree/container >}}
 {{< filetree/folder name="source" state="open" >}}
  {{< filetree/folder name="happ-subscription-generator" state="open" >}}
    {{< filetree/file name="Dockerfile" >}}
    {{< filetree/file name="generator.py" >}}
    {{< filetree/file name="README.md" >}}
  {{< /filetree/folder >}}
 {{< /filetree/folder >}}
 {{< /filetree/container >}}
 ## Связь с Action-скриптами {#actions}
 Action-скрипты (такие как `compose` или `sync`) взаимодействуют с директорией `source/`, ссылаясь на пути внутри нее. Например, действие `compose` может использовать файл `docker-compose.yml`, который указывает на `Dockerfile`, расположенный в `source/app/`.
 Такое разделение ответственности гарантирует, что логика оркестрации (Action-скрипты) остается отвязанной от деталей реализации (Source).
 ---
 **See also:**
 - [Концепция: Архитектура инфраструктуры](/root/concepts/architecture)
 - [Справочник: Справочник ROOT_ API Reference](/root/reference/root-api)
@@ -0,0 +1,36 @@
 ---
 title: Операции синхронизации (Sync)
 description: Обновление репозитория, синхронизация пакетов и резервное копирование данных.
 weight: 54
 ---
 Операции синхронизации гарантируют, что состояние хоста соответствует конфигурациям, определенным в удаленных репозиториях.
 ## Основные операции синхронизации {#actions}
 | Операция | Описание |
 | :--- | :--- |
 | `sync/packages` | Синхронизирует пакеты узлов и их конфигурации по всей системе. |
 | `sync/repository` | Обновляет основной репозиторий конфигураций до последней версии из GitHub. |
 | `sync/tiers` | Запускает стратегию резервного копирования для настроенных [Уровней (Tiers)](/root/glossary#tier). |
 ## Синхронизация репозитория (`sync/repository`) {#repository}
 Действие `sync/repository` отвечает за поддержание репозитория конфигураций хоста в актуальном состоянии. Оно обычно выполняет `git pull` в основном репозитории конфигураций и может опционально запускать обновление субмодулей для репозитория [Commons](/root/glossary#commons).
 Это гарантирует, что любые изменения в конфигурациях узлов, действиях или исходных файлах будут корректно загружены на целевой хост.
 ## Синхронизация бэкапов (`sync/tiers`) {#tiers}
 Действие `sync/tiers` является основной точкой входа для стратегии резервного копирования узла.
 - **Нет реализации по умолчанию**: Сами общие модули не предоставляют механизма резервного копирования по умолчанию, позволяя операторам разработать пользовательскую стратегию, подходящую для их нужд.
 - **Пользовательские переопределения**: Будучи действием диспетчера, его можно переопределить, поместив собственный скрипт в `.operator/local/scripts/actions/sync/tiers` для реализации специфичной для узла логики резервного копирования.
 - **Пример реализации**: Распространенной практикой является использование такого инструмента, как [Restic](https://restic.net/), в рамках этого пользовательского скрипта для выполнения удаленного резервного копирования критически важных данных (Tiers 1 и 2) в S3-совместимое хранилище.
 ---
 **See also:**
 - [Концепция: Модель многоуровневого хранения](/root/concepts/tiered-storage)
 - [Справочник: Справочник ROOT_ API Reference](/root/reference/root-api)
@@ -0,0 +1,44 @@
 ---
 title: Операции управления уровнями (Tiers)
 description: Классификация хранилища, символические ссылки и изоляция привилегий.
 weight: 55
 ---
 Операции управления уровнями отвечают за соблюдение [Модели многоуровневого хранения](/root/concepts/tiered-storage) и обеспечение корректного владения файловой системой и изоляции.
 ## Основные операции с уровнями (Tier Actions) {#actions}
 | Операция | Описание |
 | :--- | :--- |
 | `tiers/chown` | Устанавливает корректного владельца файловой системы для [Пользователей проекта](#useradd). |
 | `tiers/link` | Управляет символическими ссылками между директориями проекта и их соответствующими [Уровнями (Tiers)](/root/glossary#tier). |
 | `tiers/useradd` | Создает уникального системного пользователя для каждого проекта для обеспечения [Изоляции привилегий](/root/concepts/security-model). |
 ## Управление пользователями (`tiers/useradd`) {#useradd}
 Действие `tiers/useradd` создает выделенного низкопривилегированного системного пользователя для каждого проекта внутри узла. Этот пользователь затем используется для запуска контейнеров проекта, гарантируя, что компрометация одного проекта не даст злоумышленнику доступ ко всему хосту.
 - **Соглашение об именовании**: Пользователи обычно называются в честь проекта.
 - **Членство в группах**: Пользователи могут быть опционально добавлены в группу `docker` или взаимодействовать с Docker другими безопасно настроенными способами по выбору оператора.
 ## Привязка хранилища (`tiers/link`) {#link}
 Действие `tiers/link` создает структуру символических ссылок, необходимую для модели многоуровневого хранения. Оно гарантирует, что директории `config`, `data` и `logs` внутри папки проекта указывают на их физическое местоположение в `@tier1`, `@tier2` и `@tier3` соответственно.
 ```bash
 # Пример структуры ссылок, созданной tiers/link
 /srv/root/icarus/synapse/config -> /srv/storage/@tier1/synapse
 /srv/root/icarus/synapse/data   -> /srv/storage/@tier2/synapse
 /srv/root/icarus/synapse/logs   -> /srv/storage/@tier3/synapse
 ```
 ## Управление владельцами (`tiers/chown`) {#chown}
 После того как уровни и ссылки созданы, действие `tiers/chown` гарантирует, что физические директории на каждом уровне принадлежат правильному пользователю проекта. Это критически важно для предотвращения ошибок доступа и гарантии того, что проекты могут обращаться только к своим собственным данным.
 ---
 **See also:**
 - [Концепция: Модель многоуровневого хранения](/root/concepts/tiered-storage)
 - [Концепция: Безопасность и изоляция привилегий](/root/concepts/security-model)
@@ -0,0 +1,37 @@
 ---
 title: Вспомогательные операции (Utils)
 description: Общие вспомогательные скрипты для обслуживания, валидации и управления сертификатами.
 weight: 56
 ---
 Вспомогательные операции предоставляют общие функции для обслуживания узлов, валидации и выполнения специфических задач проектов.
 ## Основные вспомогательные операции {#actions}
 | Операция | Описание |
 | :--- | :--- |
 | `utils/extract-traefik-certs` | Извлекает сертификаты SSL/TLS и приватные ключи из хранилища Traefik `acme.json`. |
 | `utils/generate-happ-subscriptions` | Автоматически генерирует файлы подписки HApp на основе текущих метаданных проекта. |
 | `utils/lint-docker-compose` | Выполняет статический анализ всех файлов `docker-compose.yml` на соответствие стандартам общих модулей. |
 ## Управление сертификатами (`utils/extract-traefik-certs`) {#certificates}
 Traefik сохраняет свои сертификаты, выпущенные через ACME (например, от Let's Encrypt), в одном файле `acme.json`. Действие `utils/extract-traefik-certs` парсит этот файл и извлекает отдельные файлы `fullchain.pem` и `privkey.pem`.
 Это особенно полезно, когда другим сервисам (например, почтовым серверам или приложениям вне Docker) требуются те же SSL-сертификаты.
 ## Контроль качества (`utils/lint-docker-compose`) {#linting}
 Для поддержания согласованности и безопасности действие `utils/lint-docker-compose` проверяет все compose-файлы в инфраструктуре. Оно проверяет:
 - **Стандарты именования**: Гарантирует, что имена проектов и контейнеров соответствуют соглашению `{node}-{project}`.
 - **Контекст безопасности**: Отмечает контейнеры, работающие под пользователем `root` без обоснованного переопределения.
 - **Ограничения ресурсов**: Идентифицирует сервисы, у которых отсутствуют лимиты CPU или памяти.
 - **Стандарты Label**: Проверяет наличие необходимых меток (labels) для маршрутизации (например, [Traefik](https://traefik.io/)) и [CrowdSec](/root/concepts/security-model#crowdsec).
 ---
 **See also:**
 - [Концепция: Принципы инфраструктуры](/root/concepts/principles)
 - [Концепция: Безопасность и изоляция привилегий](/root/concepts/security-model)