docs: document Linux VM deployment, auto-publish timer, and bug fixes

Generated with [Devin](https://cli.devin.ai/docs)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

docs/devops/GITEA_NPM_REGISTRY_MIGRATION.md

@@ -681,3 +681,92 @@ After completing the migration and audit, all Dockerfiles were tested with actua
 - **Backend tests**: 1,700+ tests passing across all 12 backend services (platform 1,483 + extraction 136 + 10 products)
 - **Web typecheck**: 9/9 web apps typecheck clean
 - **Backend typecheck**: 10/10 repos typecheck clean
+
+---
+
+## 18. Linux VM Deployment (Current — 2026-05-10)
+
+The ecosystem has been deployed to a Linux VM (Azure) as planned in §13. This section documents the current production setup.
+
+### 18.1 Architecture
+
+```text
+Azure Linux VM (srv1491630)
+├── Gitea (Docker container: gitea-npm-registry, port 3300)
+│   ├── Git hosting (13 repos under bytelyst/*)
+│   ├── npm package registry (@bytelyst/* packages)
+│   └── Gitea Actions (enabled, but see §18.4)
+├── Repos at /opt/bytelyst/
+│   ├── learning_ai_common_plat/     ← canonical package source
+│   ├── learning_ai_clock/
+│   ├── learning_ai_invt_trdg/
+│   ├── learning_ai_notes/
+│   └── bytelyst-devops-tools/
+└── Systemd auto-publish (see §18.3)
+```
+
+### 18.2 Package Registry
+
+- **Registry URL:** `http://localhost:3300/api/packages/bytelyst/npm/`
+- **Auth:** token-based, stored in `/opt/bytelyst/.gitea_token`
+- **Packages published:** 63 `@bytelyst/*` packages (up from 56 on Mac)
+- **All packages current** as of 2026-05-10
+
+Key differences from the Mac setup:
+
+- Gitea runs in Docker (not Homebrew), port mapping `3300:3000`
+- All paths use `/opt/bytelyst/` instead of `/Users/sd9235/code/mygh/`
+- `.npmrc` files use `localhost:3300` (no SSH tunnel needed — same host)
+
+### 18.3 Auto-Publish via Systemd Timer
+
+Since Gitea Actions with host runner proved unreliable on Linux (see §18.4), auto-publishing uses a systemd timer instead:
+
+```text
+systemd timer (every 5 min)
+  ↓ triggers
+bytelyst-publish.service
+  ↓ runs
+/opt/bytelyst/publish_packages.py
+  ├── git fetch gitea + reset --hard
+  ├── pnpm build
+  └── for each @bytelyst/* package:
+      ├── check if version exists on registry
+      └── npm publish if missing or outdated
+```
+
+**Files:**
+| File | Purpose |
+|---|---|
+| `/etc/systemd/system/bytelyst-publish.service` | Service unit |
+| `/etc/systemd/system/bytelyst-publish.timer` | Timer (every 5 min) |
+| `/opt/bytelyst/publish_packages.py` | Publish script |
+
+**Commands:**
+
+```bash
+systemctl status bytelyst-publish.timer    # check timer
+journalctl -u bytelyst-publish.service     # view logs
+systemctl start bytelyst-publish.service   # manual trigger
+```
+
+### 18.4 Bugs Fixed During Linux Deployment
+
+| #   | Finding                                                                 | Severity       | Fix                                                               |
+| --- | ----------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------- |
+| 1   | Registry URL used `ByteLyst` (capital B, L) instead of `bytelyst`       | **BUG**        | Fixed in `publish-outdated-packages.sh` and `release-packages.sh` |
+| 2   | CI workflow hardcoded macOS paths (`/Users/sd9235/...`)                 | **BUG**        | Updated to `/opt/bytelyst/learning_ai_common_plat`                |
+| 3   | Gitea Actions not enabled in container config                           | **GAP**        | Added `[actions] ENABLED = true` to `app.ini`                     |
+| 4   | act_runner host mode unreliable — jobs stuck, not picking up new pushes | **LIMITATION** | Replaced with systemd timer (more reliable for single-VM)         |
+
+### 18.5 Remotes
+
+All repos have both remotes:
+
+- `origin` → GitHub (canonical)
+- `gitea` → `http://localhost:3300/bytelyst/<repo>.git` (local CI + package publishing)
+
+```bash
+# Push to both
+git push origin main && git push gitea main
+```