docs: remediate documentation gaps across quickstart, backup, config, API spec, and operations guides (#330)

- Fix Cyrillic character in quickstart image ref and correct registry to Docker Hub (saelix/sencho)
- Correct backup guide WAL references (Sencho uses SQLite default journal mode)
- Add SSL/TLS reverse proxy examples for Nginx, Traefik, and new Caddy configuration
- Add missing env vars (PORT, DATA_DIR, NODE_ENV, FRONTEND_URL, SSO_LDAP_DISPLAY_NAME) to .env.example
- Add upgrade & migration guide documenting automatic schema migrations
- Add self-hosting best practices (1:1 path rule, Docker socket security, resource recs)
- Add architecture overview (system design, request flow, database schema, multi-node model)
- Add development & contributor guide (setup, tests, code style, PR workflow)
- Update OpenAPI spec from v0.23.0 to v0.25.3 with Registries and Image Updates endpoints
- Update docs.json navigation with all new pages and API groups

docs/operations/backup.mdx

@@ -31,7 +31,7 @@ This is your actual application data. It lives entirely outside Sencho and you a
 ### Simple file copy
 
 ```bash
-# Stop Sencho to ensure the SQLite WAL is flushed (recommended but not strictly required)
+# Stop Sencho to ensure no active transactions (recommended but not strictly required)
 docker stop sencho
 
 # Copy the data directory
@@ -44,6 +44,10 @@ cp -r /opt/compose /path/to/backup/compose-$(date +%Y%m%d)
 docker start sencho
 ```
 
+<Note>
+  Sencho uses SQLite's default journal mode (not WAL), so you will not see `-wal` or `-shm` sidecar files alongside `sencho.db`. If a `-journal` file exists when you copy, it indicates an interrupted write — SQLite will automatically resolve it the next time the database is opened.
+</Note>
+
 ### SQLite online backup (without stopping)
 
 SQLite supports hot backups via its `.backup` command. This is safe to run while Sencho is running:

docs/operations/self-hosting.mdx

@@ -0,0 +1,97 @@
+---
+title: Self-Hosting Best Practices
+description: Volume mounts, Docker socket security, networking, and resource recommendations for running Sencho in production.
+---
+
+## The 1:1 path rule
+
+This is the most common setup mistake. When Sencho deploys a Docker Compose stack, Docker resolves bind-mount volume paths relative to the **host filesystem**, not the Sencho container. If your compose files reference relative paths like `./data:/app/data`, Docker looks for `./data` on the host — starting from the directory where the compose file lives on the host.
+
+This means the path to your compose directory **must be identical** inside and outside the container:
+
+```yaml
+# Correct - same path on both sides
+volumes:
+  - /opt/compose:/opt/compose
+environment:
+  - COMPOSE_DIR=/opt/compose
+
+# Wrong - different paths, relative volumes will break
+volumes:
+  - /opt/compose:/app/compose
+```
+
+See the [Configuration guide](/getting-started/configuration#compose-directory-the-11-path-rule) for a detailed explanation with examples.
+
+---
+
+## Volume mount checklist
+
+Sencho requires three volume mounts to function correctly:
+
+| Mount | Purpose | Required |
+|-------|---------|----------|
+| `/var/run/docker.sock:/var/run/docker.sock` | Docker Engine access for managing containers | Yes |
+| `./sencho-data:/app/data` | Persistent storage for SQLite database and encryption keys | Yes |
+| `/opt/compose:/opt/compose` | Your compose project files (must follow 1:1 path rule) | Yes |
+
+<Note>
+  The data directory contains `sencho.db` (all settings, nodes, alerts, metrics) and `encryption.key` (used to encrypt secrets at rest). Losing this directory means losing your Sencho configuration entirely.
+</Note>
+
+---
+
+## Docker socket security
+
+Mounting the Docker socket (`/var/run/docker.sock`) grants the container the ability to manage all containers, images, volumes, and networks on the host. This is equivalent to root access on the host machine.
+
+Sencho mitigates this with privilege dropping:
+
+1. The container starts as root to fix volume ownership and resolve Docker socket group permissions
+2. The entrypoint script (`docker-entrypoint.sh`) then drops to a non-root `sencho` user via `su-exec`
+3. All application code runs as the `sencho` user
+
+If your environment requires stricter isolation, consider:
+
+- Running Sencho on a dedicated Docker host
+- Using Docker's `--userns-remap` for user namespace isolation
+- Placing Sencho behind a reverse proxy with authentication (see [Configuration](/getting-started/configuration#reverse-proxy-setup))
+
+---
+
+## Resource recommendations
+
+| Resource | Minimum | Recommended | Notes |
+|----------|---------|-------------|-------|
+| CPU | 1 core | 1-2 cores | More cores help with concurrent stack operations |
+| RAM | 256 MB | 512 MB | Higher for multi-node setups with many stacks |
+| Disk | 100 MB | 500 MB | Database is typically < 50 MB; allocate headroom for metrics retention |
+
+Sencho itself is lightweight. The majority of resource usage on your host comes from the Docker containers it manages, not from Sencho.
+
+---
+
+## Networking
+
+- **Listen port:** 3000 by default, configurable via the `PORT` environment variable
+- **Inbound:** Only the listen port needs to be reachable (directly or through a reverse proxy)
+- **Outbound:** No outbound connections are required for local-only setups. If you use multi-node management, Sencho needs HTTP/HTTPS access to remote Sencho instances on their configured API URLs
+- **Health check:** `GET /api/health` returns `200` when the application is ready. The Docker image includes a built-in `HEALTHCHECK` that polls this endpoint every 30 seconds
+
+---
+
+## Environment variable checklist
+
+Quick reference for all environment variables. See [Configuration](/getting-started/configuration) for full details.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `JWT_SECRET` | *(required)* | Secret key for signing JWT tokens |
+| `COMPOSE_DIR` | `/app/compose` | Path to compose project files (1:1 rule applies) |
+| `PORT` | `3000` | HTTP server listen port |
+| `DATA_DIR` | `/app/data` | Database and encryption key directory |
+| `NODE_ENV` | `production` | Set automatically in Docker image |
+| `FRONTEND_URL` | *(empty)* | Frontend origin for CORS; leave empty for same-origin |
+| `API_RATE_LIMIT` | `100` | Max API requests per minute per IP |
+
+SSO variables are documented separately in the [SSO Quickstart](/getting-started/sso-quickstart).

docs/operations/upgrade.mdx

@@ -0,0 +1,82 @@
+---
+title: Upgrading Sencho
+description: How to update Sencho, what happens during upgrades, and the version policy.
+---
+
+## Upgrade steps
+
+Upgrading Sencho is a two-command process. Pull the latest image and recreate the container:
+
+```bash
+docker compose pull
+docker compose up -d
+```
+
+Or if you're running with `docker run`:
+
+```bash
+docker pull saelix/sencho:latest
+docker stop sencho && docker rm sencho
+# Re-run your original docker run command
+```
+
+Sencho will apply any necessary database migrations automatically on startup. No manual steps are required.
+
+---
+
+## Automatic migrations
+
+Sencho handles all schema changes internally. When the application starts, it runs a series of migration checks:
+
+- **Schema evolution** — New columns are added via `ALTER TABLE ADD COLUMN`. If a column already exists, the operation is silently skipped.
+- **Legacy config migration** — If upgrading from a very early version that used a `sencho.json` file, the settings are automatically imported into SQLite.
+- **Admin account migration** — Legacy admin credentials stored in `global_settings` are migrated to the `users` table.
+- **Encryption migration** — Unencrypted node API tokens are automatically encrypted at rest using AES-256-GCM.
+- **SSO columns** — SSO provider fields are added to the users table if not present.
+- **Registry tables** — Private registry storage tables are created if they don't exist.
+- **RBAC tables** — Role assignment tables are created for granular permissions.
+- **Legacy cleanup** — Obsolete columns from pre-0.7 versions (SSH/TLS fields) are dropped.
+
+You never need to run SQL commands, migration scripts, or any manual database operations.
+
+---
+
+## Backup before upgrading
+
+Always back up your data directory before upgrading. If something goes wrong, restoring from backup is the only recovery path — Sencho does not support downgrading or rolling back database migrations.
+
+```bash
+sqlite3 /path/to/sencho-data/sencho.db ".backup '/path/to/backup/sencho-pre-upgrade.db'"
+```
+
+See the [Backup & Restore guide](/operations/backup) for full backup procedures.
+
+---
+
+## Pinning a specific version
+
+If you prefer to control exactly which version you run, pin the image tag in your `docker-compose.yml`:
+
+```yaml
+image: saelix/sencho:0.25.3
+```
+
+Check [GitHub Releases](https://github.com/AnsoCode/Sencho/releases) for available versions and changelogs.
+
+---
+
+## Version policy
+
+Sencho follows [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`):
+
+| Change type | Version bump | Example |
+|-------------|-------------|---------|
+| Bug fixes, performance improvements | Patch | 0.25.0 → 0.25.1 |
+| New features | Minor | 0.25.x → 0.26.0 |
+| Breaking changes | Major | 0.x.y → 1.0.0 |
+
+<Note>
+  While the version is below 1.0, minor releases (0.x.0) may occasionally include breaking changes. These are always documented in the release notes. Once Sencho reaches 1.0, breaking changes will only occur in major releases.
+</Note>
+
+Breaking changes are marked with `BREAKING CHANGE` in the [release notes](https://github.com/AnsoCode/Sencho/releases). Subscribe to the repository's releases to be notified of new versions.