@lamalibre/create-lamaste 4.0.0

package/vendor/docs/02-guides/first-tunnel.md

@@ -0,0 +1,230 @@
+# Creating Your First Tunnel
+
+> Expose a local web app to the internet through Lamaste in under 5 minutes.
+
+## In Plain English
+
+A tunnel connects a web app running on your local machine (behind your home router or office firewall) to a public URL on your Lamaste server. Visitors go to `app.example.com`, and Lamaste forwards the request through a secure WebSocket tunnel to your machine, which serves the response. Your app never leaves your machine — only the traffic flows through the relay.
+
+## Prerequisites
+
+- A completed [Lamaste onboarding](onboarding.md) with your domain configured
+- A **web app running locally** on your machine (macOS or Linux) on a port between 1024 and 65535
+- That machine **enrolled as an agent** — with the [Desktop App](desktop-app-setup.md) or `lamaste-agent setup` (see [Agent Setup](agent-setup.md)). Every tunnel is carried by exactly one agent, so the agent must exist before its tunnel
+
+For this guide, assume you have a web app running on `http://localhost:3000`.
+
+## Step-by-Step
+
+### 1. Open the Tunnels Page
+
+Log in to the Lamaste admin panel at `https://panel.example.com` (or `https://<ip>:9292`).
+
+Click **Tunnels** in the sidebar navigation.
+
+You see an empty state: "No tunnels configured. Create your first tunnel to get started."
+
+### 2. Click Add Tunnel
+
+Click the **Add Tunnel** button in the top right corner.
+
+A form appears with these fields:
+
+| Field                          | Description                                                        | Example               |
+| ------------------------------ | ------------------------------------------------------------------ | --------------------- |
+| **Subdomain**                  | The subdomain for your tunnel's public URL                         | `app`                 |
+| **Port**                       | The port your app listens on, on the agent                         | `3000`                |
+| **Agent**                      | The enrolled agent that carries the tunnel (required)              | `laptop`              |
+| **Largest request body (MiB)** | Biggest upload nginx accepts for this tunnel (1–10240, default 10) | `10`                  |
+| **Description**                | Optional note for your reference                                   | `My React dev server` |
+| **Access**                     | Restricted (default), All Authelia Users, or Public                | Restricted            |
+
+### 3. Fill in the Form
+
+Enter a subdomain name. This becomes the public URL: if your domain is `example.com` and you enter `app`, the tunnel URL is `app.example.com`.
+
+Subdomain rules:
+
+- Lowercase letters, numbers, and hyphens only
+- Cannot start or end with a hyphen
+- Maximum 63 characters
+- Cannot use reserved names: `panel`, `auth`, `tunnel`, `www`, `mail`, `ftp`, `api`
+- Cannot start with `agent-` (this prefix is reserved for agent panel tunnels)
+
+Enter the port number. This is the port your web app listens on, on `127.0.0.1` of the agent machine. Must be between 1024 and 65535, and unique across all tunnels (Chisel binds the same port on the server). Ports 3100, 9090, 9091, 9292 and 9294 are refused: they belong to Lamaste's own services on the server, and a tunnel on one of them would publish that service.
+
+Pick the **Agent** that runs the app. Only that agent is told about the tunnel, and only that agent's Chisel credential may open its port on the server — another agent cannot take over the hostname.
+
+Leave **Largest request body** at 10 MiB unless the app takes larger uploads; requests above the limit get HTTP 413. Optionally add a description to help you remember what this tunnel is for.
+
+### 4. Create the Tunnel
+
+Click **Add Tunnel**.
+
+The panel performs four operations in sequence:
+
+1. **Issues a TLS certificate** — Runs certbot to get a Let's Encrypt certificate for `app.example.com`. This takes a few seconds.
+2. **Writes an nginx vhost** — Creates a reverse proxy configuration that forwards `app.example.com` traffic through Gatekeeper/Authelia (unless the tunnel is public) to `127.0.0.1:3000`, with the tunnel's `client_max_body_size`.
+3. **Saves the tunnel** — Writes the tunnel record, including its `agentLabel`, to `/etc/lamalibre/lamaste/tunnels.json`.
+4. **Syncs Chisel** — Re-renders the Chisel authfile from the saved state so the carrying agent — and only that agent — may bind the port. Chisel picks up the added grant without a restart, so other tunnels are not interrupted.
+
+When all four steps succeed, the new tunnel appears in the list with its subdomain, FQDN, port, agent, access mode, and body limit.
+
+**If something goes wrong:** The panel rolls back completed steps. If nginx configuration fails, the certificate is left in place (harmless). If saving the state or the Chisel sync fails, the tunnel is removed from the state and the nginx vhost is removed. You see an error message describing what went wrong.
+
+### 5. Wait for the Agent (about 30 seconds)
+
+The server now accepts the port from the carrying agent. The agent picks the tunnel up by itself: its sync timer asks the panel for its tunnel configuration (`GET /api/tunnels/agent-config`) every 30 seconds, rewrites its Chisel service (launchd on macOS, a systemd user unit on Linux) when the set changed, and restarts it — or starts it, if this is the agent's first tunnel. To apply the change at once, run on the agent machine:
+
+```bash
+lamaste-agent update
+```
+
+The same happens for every later change — a deleted or disabled tunnel, or one moved to or from this agent. `lamaste-agent status` shows the last sync on its **Sync** line.
+
+### 6. Verify the Tunnel
+
+Once the agent has picked up the tunnel, test your tunnel:
+
+1. Make sure your local app is running on the configured port (e.g., `http://localhost:3000`).
+2. Open `https://app.example.com` in a new browser window (or incognito).
+3. Authelia redirects you to the login page at `auth.example.com`.
+4. Enter your Authelia username and password.
+5. Enter your TOTP code from your authenticator app.
+6. After authentication, you see your local app.
+
+**Expected behavior:** The first visit takes a moment because Authelia intercepts the request for authentication. After logging in, subsequent requests flow through quickly. Authelia sets a session cookie, so you do not need to re-authenticate for each page load.
+
+### 7. Share Access with Users
+
+By default a tunnel is **Restricted**: a visitor needs an Authelia account and a grant for this tunnel. To let someone else access the tunnel:
+
+1. Go to the **Users** page in the panel.
+2. Create a new user with a username, display name, email, and password.
+3. Grant the user (or a group they belong to) access to the tunnel — see [Authorization](../01-concepts/authorization.md). Tunnels set to **All Authelia Users** skip this step.
+4. Share the credentials and the tunnel URL with the person.
+5. On their first login, they set up TOTP with their own authenticator app.
+
+See [Managing Users](managing-users.md) for the full guide.
+
+## For Developers
+
+### Tunnel Data Model
+
+Each tunnel is stored as a JSON object in `/etc/lamalibre/lamaste/tunnels.json`:
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "subdomain": "app",
+  "fqdn": "app.example.com",
+  "port": 3000,
+  "description": "My React dev server",
+  "type": "app",
+  "accessMode": "restricted",
+  "agentLabel": "laptop",
+  "maxBodySizeMb": 10,
+  "enabled": true,
+  "createdAt": "2024-01-15T10:30:00.000Z"
+}
+```
+
+`agentLabel` is the carrying agent. `maxBodySizeMb` becomes the vhost's `client_max_body_size`; tunnels created before the setting existed have no value and keep nginx's built-in 1 MiB until a body limit is set on them.
+
+### API Endpoints
+
+| Method   | Path                        | Purpose                                                                |
+| -------- | --------------------------- | ---------------------------------------------------------------------- |
+| `GET`    | `/api/tunnels`              | List tunnels, newest first (an agent sees only its own)                |
+| `POST`   | `/api/tunnels`              | Create a tunnel (certbot + nginx + state + chisel)                     |
+| `PATCH`  | `/api/tunnels/:id`          | Enable/disable, move to another agent, change access mode or body size |
+| `DELETE` | `/api/tunnels/:id`          | Remove a tunnel (nginx + state + chisel)                               |
+| `GET`    | `/api/tunnels/agent-config` | One agent's Chisel client configuration (used by `lamaste-agent`)      |
+
+See the [Tunnels API](../04-api-reference/tunnels.md) for the full reference.
+
+### Create Tunnel Request
+
+```json
+POST /api/tunnels
+{
+  "subdomain": "app",
+  "port": 3000,
+  "agentLabel": "laptop",
+  "description": "My React dev server"
+}
+```
+
+Validation rules (Zod schema):
+
+- `subdomain`: lowercase alphanumeric with hyphens, max 63 chars, not reserved, not already served by a static site or site alias
+- `port`: integer between 1024 and 65535, unique across tunnels
+- `agentLabel`: an enrolled, non-revoked agent — required for admin certificates; an agent certificate defaults to itself and may not name another agent
+- `accessMode`: `restricted` (default), `authenticated`, or `public` — the last two admin-only
+- `maxBodySizeMb`: optional integer 1–10240, default 10
+- `description`: optional, max 200 characters
+
+### nginx Vhost Structure
+
+Each tunnel gets a vhost that:
+
+1. Terminates TLS with a Let's Encrypt certificate
+2. Sends an auth subrequest to Authelia (`auth_request /authelia`)
+3. Proxies authenticated traffic to `127.0.0.1:<tunnel-port>`
+
+The Chisel server on the VPS accepts a reverse tunnel for the port only from the carrying agent — its authfile grants each `agent-<label>` user exactly `^R:127\.0\.0\.1:<port>$` for the enabled tunnels it owns — and forwards traffic to that agent.
+
+### Traffic Flow
+
+```
+Browser → app.example.com:443
+  → nginx (TLS termination)
+    → Authelia auth_request (checks session cookie / prompts login)
+    → proxy_pass 127.0.0.1:3000
+      → Chisel server (reverse tunnel)
+        → Chisel client (on your machine)
+          → localhost:3000 (your app)
+```
+
+### Agent Service
+
+`lamaste-agent setup`, `update` and the 30-second sync timer render the Chisel client service from the `chiselArgs` returned by `GET /api/tunnels/agent-config` (implementation: `packages/core/lib/src/agent/converge.ts` and `chisel-service.ts`, shared by the CLI and `lamaste-agentd`). The service:
+
+- Runs `chisel client --max-retry-interval 30s https://tunnel.example.com:443` and verifies the server's Let's Encrypt certificate — no `--tls-skip-verify`. The server URL must be `tunnel.<the domain the agent enrolled with>`
+- Is stopped while the agent carries no tunnels (Chisel cannot run without a remote), and while the operator has stopped it
+- Adds a `R:127.0.0.1:<port>:127.0.0.1:<port>` argument for each tunnel the agent carries
+- Reads its credential from the environment (`AUTH=`), never from argv: the 0600 `chisel.env` on Linux, the 0600 plist's `EnvironmentVariables` on macOS
+- Restarts automatically (`KeepAlive` on macOS, `Restart=always` on Linux)
+
+### Deletion Rollback
+
+When deleting a tunnel, the panel removes components in order:
+
+1. Remove the nginx vhost and reload
+2. Remove the tunnel from `tunnels.json`
+3. Sync Chisel — the authfile is re-rendered without the owner's grant for the port, and Chisel restarts so live sessions drop it. The owner's sync timer stops asking for the port within about 30 seconds (until then Chisel refuses the owner's session, so its other tunnels are briefly down too)
+
+The TLS certificate is left in place (certbot manages its lifecycle).
+
+## Quick Reference
+
+| Action                 | How                                                         |
+| ---------------------- | ----------------------------------------------------------- |
+| **Create tunnel**      | Tunnels page, "Add Tunnel" button                           |
+| **Delete tunnel**      | Click delete icon on the tunnel row                         |
+| **Move / reconfigure** | "Edit" on the tunnel row (agent, access mode, body limit)   |
+| **Enable / disable**   | Toggle on the tunnel row                                    |
+| **View tunnel URL**    | Click the domain link on the tunnel row                     |
+| **Update client**      | Automatic within ~30 s; `lamaste-agent update` to apply now |
+
+| Constraint           | Value                                           |
+| -------------------- | ----------------------------------------------- |
+| Subdomain format     | `^[a-z0-9]([a-z0-9-]*[a-z0-9])?$`               |
+| Port range           | 1024-65535, except 3100, 9090, 9091, 9292, 9294 |
+| Max subdomain length | 63 characters                                   |
+| Reserved subdomains  | panel, auth, tunnel, www, mail, ftp, api        |
+| Reserved prefix      | `agent-` (used by agent panel tunnels)          |
+| Unique port          | Yes (one tunnel per port)                       |
+| Unique subdomain     | Yes (one tunnel per subdomain)                  |
+| Carrying agent       | Exactly one (`agentLabel`)                      |
+| Request body limit   | 1-10240 MiB (agents: up to 100), default 10     |

package/vendor/docs/02-guides/installation.md

@@ -0,0 +1,393 @@
+# Installation
+
+> Complete guide to provisioning a Lamaste server from a fresh DigitalOcean droplet in under 10 minutes.
+
+## In Plain English
+
+This guide walks you through creating a cheap cloud server and running a single command that turns it into a secure relay for your local web apps. By the end, you have a browser-accessible admin panel protected by a client certificate — no SSH required after setup.
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+- A **DigitalOcean account** (or any VPS provider offering Ubuntu 24.04)
+- A **local terminal** with SSH and SCP available (macOS Terminal, Linux shell, or Windows PowerShell)
+- A **modern browser** (Chrome, Firefox, Safari, or Edge) for importing the client certificate
+- Approximately **10 minutes** of uninterrupted time
+
+## Step-by-Step
+
+### 1. Create a DigitalOcean Droplet
+
+1. Log in to [DigitalOcean](https://cloud.digitalocean.com/).
+2. Click **Create** and select **Droplets**.
+3. Choose these settings:
+
+| Setting            | Value                                                 |
+| ------------------ | ----------------------------------------------------- |
+| **Region**         | Choose the closest to your users                      |
+| **Image**          | Ubuntu 24.04 (LTS) x64                                |
+| **Size**           | Basic, Regular, $4/mo (512 MB RAM, 1 vCPU, 10 GB SSD) |
+| **Authentication** | SSH keys (recommended) or password                    |
+| **Hostname**       | Something memorable, e.g. `lamaste-relay`             |
+
+4. Click **Create Droplet**.
+5. Wait for the droplet to boot. Copy its **public IP address** from the dashboard.
+
+The $4/month droplet is sufficient. Lamaste is designed for a 512 MB RAM budget — all services together use approximately 245 MB, with a 1 GB swap file as a safety net.
+
+### 2. SSH into the Droplet
+
+Open your terminal and connect:
+
+```bash
+ssh root@203.0.113.42
+```
+
+Replace `203.0.113.42` with your droplet's actual IP address.
+
+If you used an SSH key during droplet creation, you connect immediately. If you chose a password, enter it when prompted.
+
+**Expected output:**
+
+```
+Welcome to Ubuntu 24.04 LTS (GNU/Linux 6.x.x-xxx-generic x86_64)
+...
+root@lamaste-relay:~#
+```
+
+### 3. Run the Installer
+
+Execute the Lamaste installer:
+
+```bash
+apt install -y npm
+npx @lamalibre/create-lamaste@4.0.0
+```
+
+The installer displays a confirmation banner before making any changes:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Lamaste Installer                                          │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  This will install Lamaste on this machine.                │
+│                                                             │
+│  The following changes will be made:                         │
+│                                                             │
+│    * Reset UFW firewall (allow ports 22, 80, 443, 9292)     │
+│    * Harden SSH (disable password authentication)           │
+│    * Install fail2ban, Node.js 20, nginx, certbot           │
+│    * Generate mTLS certificates for browser access          │
+│    * Create lamaste user and systemd service               │
+│    * Deploy panel to /opt/lamalibre/lamaste/                         │
+│                                                             │
+│  Designed for a fresh Ubuntu 24.04 droplet.                  │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+
+  Press Enter to continue or Ctrl+C to abort...
+```
+
+Press **Enter** to proceed. To skip the confirmation prompt, use `npx @lamalibre/create-lamaste@4.0.0 --yes`.
+
+### 4. What the Installer Does
+
+The installer runs seven sequential phases. Each phase displays real-time progress:
+
+**Phase 1 — Environment checks**
+
+```
+✔ Checking environment
+  ✔ Verifying root access
+  ✔ Detecting operating system → Ubuntu 24.04 LTS
+  ✔ Detecting IP address → 203.0.113.42
+```
+
+The installer verifies you are running as root on Ubuntu 24.04 and detects the droplet's public IP address.
+
+**Phase 2 — OS hardening**
+
+```
+✔ Hardening operating system
+  ✔ Creating swap file → Swap file created and activated
+  ✔ Configuring UFW firewall → UFW enabled with ports 22, 80, 443, 9292 allowed
+  ✔ Installing and configuring fail2ban → fail2ban status: active
+  ✔ Hardening SSH configuration → SSH hardened: key-auth only, root with keys only
+  ✔ Installing system dependencies → System dependencies installed, nginx stopped
+```
+
+This phase creates a 1 GB swap file, configures the UFW firewall to allow only ports 22 (SSH), 80 (HTTP for Let's Encrypt), 443 (HTTPS), and 9292 (panel), installs fail2ban with SSH and nginx jails, hardens SSH to disable password authentication, and installs nginx, certbot, curl, and openssl.
+
+**Phase 3 — Node.js**
+
+```
+✔ Installing Node.js 20
+  ✔ Checking existing Node.js installation → Node.js not found, installing v20 LTS
+  ✔ Installing NodeSource repository → NodeSource repository added
+  ✔ Installing Node.js 20 LTS → Node.js installed
+  ✔ Verifying Node.js installation → Node.js v20.x.x, npm 10.x.x
+```
+
+If Node.js 20 or later is already installed, this phase is skipped.
+
+**Phase 4 — mTLS certificates**
+
+```
+✔ Generating mTLS certificates
+  ✔ Creating PKI directory → PKI directory: /etc/lamalibre/lamaste/pki
+  ✔ Generating CA private key and certificate → CA key and certificate generated
+  ✔ Generating client key and CSR → Client key and CSR generated
+  ✔ Signing client certificate with CA → Client certificate signed and CSR removed
+  ✔ Creating PKCS12 bundle → PKCS12 bundle created
+```
+
+This phase creates a private certificate authority (CA), signs a client certificate, and bundles it into a `.p12` file for browser import. The CA certificate has a 10-year validity; the client certificate has a 2-year validity.
+
+**Phase 5 — nginx**
+
+```
+✔ Configuring nginx
+  ✔ Generating self-signed TLS certificate for IP access → Self-signed TLS certificate generated
+  ✔ Writing mTLS snippet → mTLS snippet written
+  ✔ Writing IP-based panel vhost → Vhost written
+  ✔ Deploying certificate help page → Certificate help page deployed
+  ✔ Enabling site and cleaning up defaults → Site enabled, default removed
+  ✔ Redirecting plain HTTP to HTTPS → Port 80 answers every host with a redirect to https://
+  ✔ Validating and starting nginx → nginx is running and listening on port 9292
+```
+
+nginx is configured to listen on port 9292 with TLS and mTLS client certificate verification. A self-signed certificate is used for the IP-based connection (a proper Let's Encrypt certificate is issued later during onboarding when you configure a domain).
+
+Port 80 gets a catch-all site, `lamalibre-lamaste-http-redirect` (`listen 80 default_server`), that answers every plain-HTTP request with a `301` to `https://$host$request_uri`. It does not get in the way of Let's Encrypt: during an HTTP-01 challenge certbot's nginx plugin clones this default server for the name being validated, answers the challenge, and restores the file afterwards — for new certificates and renewals alike. If another site on the machine already owns port 80's default server, the step is skipped and the relay works without the redirect.
+
+**Phase 6 — Panel deployment**
+
+```
+✔ Deploying Lamaste panel
+  ✔ Creating system user → Created system user: lamaste
+  ✔ Creating directory structure → Directories created: /opt/lamalibre/lamaste, /etc/lamalibre/lamaste
+  ✔ Installing chisel and Authelia → chisel and Authelia installed (started during onboarding)
+  ✔ Deploying serverd → Panel server deployed
+  ✔ Deploying lamaste-server CLI → lamaste-server CLI deployed; lamaste-reset-admin shim installed
+  ✔ Deploying server-ui → Panel client deployed from pre-built dist
+  ✔ Deploying documentation → Documentation deployed
+  ✔ Writing panel configuration → Configuration written to /etc/lamalibre/lamaste/panel.json
+  ✔ Writing systemd service unit → Systemd service unit written
+  ✔ Installing sudoers wrapper scripts → Sudoers wrappers installed
+  ✔ Writing sudoers rules → Sudoers rules written and validated
+  ✔ Starting panel service → Panel service running. Health: {"status":"ok"}
+```
+
+The panel server runs as the unprivileged `lamaste` system user. Its code in `/opt/lamalibre/lamaste/` is root-owned and read-only for it. The installer — not onboarding — installs the pinned Chisel (1.12.0) and Authelia (4.39.28) releases, verified against pinned SHA-256 digests, with their systemd units; it creates the `lamaste-chisel` group (Chisel runs as it; the panel is a member so it can hand Chisel its authfile without sudo) and the `lamaste-authelia` account Authelia runs as. `/etc/sudoers.d/lamaste` has no wildcards: fixed `systemctl` command lines, `nginx -t`, and three root-owned programs in `/usr/local/sbin/` that validate every argument — `lamaste-priv` (the panel's nginx vhosts, checked against a directive allow-list; Authelia TOTP secrets; self-update), `lamaste-certbot` and `lamaste-cert-info`. The sudoers file is checked with `visudo -c` before it replaces the old one. See [Security Model](../01-concepts/security-model.md#privilege-boundary). Configuration lives in `/etc/lamalibre/lamaste/panel.json`.
+
+**Phase 7 — Gatekeeper deployment** deploys the tunnel authorization service into `/opt/lamalibre/lamaste/gatekeeper` and starts it.
+
+### 5. Read the Summary
+
+After all phases complete, the installer prints a summary box:
+
+```
+╔════════════════════════════════════════════════════════════════╗
+║                                                                ║
+║   Lamaste installed successfully!                             ║
+║                                                                ║
+╠════════════════════════════════════════════════════════════════╣
+║                                                                ║
+║   1. Download your client certificate:                         ║
+║                                                                ║
+║      scp root@203.0.113.42:/etc/lamalibre/lamaste/pki/client.p12 .     ║
+║                                                                ║
+║   2. Import client.p12 into your browser:                      ║
+║                                                                ║
+║      macOS:  Double-click the file → Keychain Access           ║
+║              → select "System" keychain (not "login")          ║
+║              → enter the password below when prompted          ║
+║              → find cert in System keychain → double-click     ║
+║              → Trust → Always Trust                            ║
+║                                                                ║
+║      Linux:  Chrome → Settings → Privacy & Security            ║
+║              → Security → Manage certificates → Import         ║
+║                                                                ║
+║      Windows: Double-click the file → Certificate Import       ║
+║               Wizard → enter the password below                ║
+║                                                                ║
+║   3. Certificate password:                                     ║
+║                                                                ║
+║      <random-password-here>                                    ║
+║                                                                ║
+║   4. Open the Lamaste panel:                                  ║
+║                                                                ║
+║      https://203.0.113.42:9292                                 ║
+║                                                                ║
+║      (Your browser will warn about the self-signed cert.       ║
+║       This is expected — click "Advanced" → "Proceed")         ║
+║                                                                ║
+║   You can now disconnect from SSH.                             ║
+║   The panel is running and accessible from your browser.       ║
+║                                                                ║
+╚════════════════════════════════════════════════════════════════╝
+```
+
+**Save the certificate password.** You need it to import the `.p12` file into your browser.
+
+### 6. Download the Client Certificate
+
+Open a **new terminal window** on your local machine (not the SSH session) and run:
+
+```bash
+scp root@203.0.113.42:/etc/lamalibre/lamaste/pki/client.p12 .
+```
+
+This copies the certificate bundle to your current directory.
+
+### 7. Import the Certificate into Your Browser
+
+The `.p12` file contains both your client certificate and private key, protected by the password shown in the summary.
+
+**macOS (Chrome, Safari, Firefox):**
+
+1. Double-click `client.p12`.
+2. Keychain Access opens. Select the **System** keychain (not "login").
+3. Enter the certificate password when prompted.
+4. Find the imported certificate in the System keychain (look for "admin" under "My Certificates").
+5. Double-click the certificate, expand **Trust**, and set "When using this certificate" to **Always Trust**.
+6. Close the dialog and enter your macOS password to confirm.
+
+If you see an error about "Local Items" — ignore it. The System keychain import is what matters.
+
+**Linux (Chrome):**
+
+1. Open Chrome and navigate to `chrome://settings/certificates`.
+2. Click **Import** under "Your Certificates".
+3. Select `client.p12` and enter the password.
+
+**Windows (Chrome, Edge):**
+
+1. Double-click `client.p12`.
+2. The Certificate Import Wizard opens.
+3. Choose "Current User" and click Next.
+4. Enter the certificate password and click Next.
+5. Let Windows automatically select the certificate store.
+6. Click Finish.
+
+### 8. Access the Panel
+
+Open your browser and navigate to:
+
+```
+https://203.0.113.42:9292
+```
+
+Your browser warns about the self-signed TLS certificate. This is expected — the IP-based connection uses a self-signed cert because Let's Encrypt cannot issue certificates for IP addresses.
+
+- **Chrome:** Click "Advanced", then "Proceed to 203.0.113.42 (unsafe)".
+- **Firefox:** Click "Advanced", then "Accept the Risk and Continue".
+- **Safari:** Click "Show Details", then "visit this website".
+
+Your browser then presents the client certificate. Select the "admin" certificate and click OK.
+
+You see the Lamaste onboarding wizard. Proceed to the [Onboarding Guide](onboarding.md) for the next steps.
+
+### 9. Disconnect SSH
+
+You can now close your SSH session:
+
+```bash
+exit
+```
+
+Everything from this point forward happens through the browser-based admin panel. SSH is never needed again for normal operation.
+
+## For Developers
+
+### Installer Internals
+
+The installer (`packages/create-lamaste`) is built with Listr2 for progress display and execa for shell commands. It runs as a single orchestrated pipeline:
+
+```
+main() → envTasks → confirmInstallation() → installTasks → printSummary()
+```
+
+Each task module exports a function that returns a Listr2 subtask list:
+
+| Module        | File                  | Purpose                                                                                                          |
+| ------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `hardenTasks` | `src/tasks/harden.js` | Swap, UFW, fail2ban, SSH, apt packages                                                                           |
+| `nodeTasks`   | `src/tasks/node.js`   | Node.js 20 LTS via NodeSource                                                                                    |
+| `mtlsTasks`   | `src/tasks/mtls.js`   | CA, client cert, PKCS12 bundle                                                                                   |
+| `nginxTasks`  | `src/tasks/nginx.js`  | Self-signed TLS, mTLS snippet, vhost                                                                             |
+| `panelTasks`  | `src/tasks/panel.js`  | System user, root-owned install dir, pinned chisel + Authelia, deploy, config, systemd, sudoers programs + rules |
+
+### Idempotency
+
+Every task includes skip guards. Running the installer a second time detects existing state and skips completed steps:
+
+- Swap already active: skips creation
+- Node.js 20+ installed: skips NodeSource setup
+- mTLS CA and client.p12 exist: skips all certificate generation
+- UFW active with correct rules: skips firewall configuration
+- SSH already hardened: skips SSH changes
+- Existing `panel.json`: merges rather than overwrites
+
+### Directory Structure on the Server
+
+After installation, the server has these Lamaste directories:
+
+| Path                                | Owner                             | Purpose                                         |
+| ----------------------------------- | --------------------------------- | ----------------------------------------------- |
+| `/etc/lamalibre/lamaste/`           | `lamaste:lamaste`                 | Configuration and state files                   |
+| `/etc/lamalibre/lamaste/pki/`       | `lamaste:lamaste` (700)           | CA, client cert, server cert, .p12              |
+| `/etc/lamalibre/lamaste/panel.json` | `lamaste:lamaste`                 | Panel configuration                             |
+| `/opt/lamalibre/lamaste/`           | `root:root`                       | Panel server, CLI, UI, docs, gatekeeper (code)  |
+| `/var/www/lamaste/`                 | `lamaste:www-data` (2750, setgid) | Static site files (0640; nginx reads via group) |
+| `/etc/authelia/`                    | `lamaste:lamaste-authelia` (2770) | Authelia configuration and database             |
+| `/var/log/authelia/`                | `lamaste-authelia` (750)          | Authelia log                                    |
+| `/usr/local/bin/chisel`, `authelia` | `root:root`                       | Pinned releases                                 |
+
+### CLI Flags
+
+| Flag            | Effect                                      |
+| --------------- | ------------------------------------------- |
+| `--help`, `-h`  | Print help and exit                         |
+| `--yes`, `-y`   | Skip confirmation prompt                    |
+| `--skip-harden` | Skip swap, UFW, fail2ban, and SSH hardening |
+| `--dev`         | Allow private/non-routable IP addresses     |
+| `--uninstall`   | Print manual removal guide and exit         |
+
+### Systemd Service
+
+The panel runs as `lamalibre-lamaste-serverd.service`:
+
+```ini
+[Service]
+User=lamaste
+Group=lamaste
+# Lets the panel hand the chisel authfile to the group chisel runs as.
+SupplementaryGroups=lamaste-chisel
+WorkingDirectory=/opt/lamalibre/lamaste/serverd
+ExecStart=/usr/bin/node src/index.js
+Environment=NODE_ENV=production
+Environment=CONFIG_FILE=/etc/lamalibre/lamaste/panel.json
+Restart=always
+RestartSec=5
+```
+
+The service includes security hardening: `ProtectHome=true`, `PrivateTmp=true`, and `ReadWritePaths` for the config and static site directories. `NoNewPrivileges` is intentionally omitted because the panel runs the fixed `sudo` commands in `/etc/sudoers.d/lamaste` (service control, `nginx -t`, `lamaste-priv`, `lamaste-certbot`, `lamaste-cert-info`) — nothing else.
+
+## Quick Reference
+
+| Item                     | Value                                                        |
+| ------------------------ | ------------------------------------------------------------ |
+| **Install command**      | `npx @lamalibre/create-lamaste@4.0.0`                              |
+| **Minimum VPS**          | Ubuntu 24.04, 512 MB RAM                                     |
+| **Required ports**       | 22 (SSH), 80 (HTTP/Let's Encrypt), 443 (HTTPS), 9292 (panel) |
+| **Certificate location** | `/etc/lamalibre/lamaste/pki/client.p12`                      |
+| **Download command**     | `scp root@<ip>:/etc/lamalibre/lamaste/pki/client.p12 .`      |
+| **Panel URL**            | `https://<ip>:9292`                                          |
+| **Config file**          | `/etc/lamalibre/lamaste/panel.json`                          |
+| **Service name**         | `lamalibre-lamaste-serverd`                                  |
+| **Service logs**         | `journalctl -u lamalibre-lamaste-serverd -f`                 |
+| **Re-run safe**          | Yes (idempotent)                                             |
+| **Total install time**   | ~5-10 minutes                                                |