feat(#1339): Deploy Nexus to proper URL for preview

Port 3000 (avoids L402 on :8080, #1415).
Three options: ./preview.sh, docker, GitHub Pages.
Triage issues: #1413 #1414 #1415

Fixes #1339

.github/workflows/pages.yml

@@ -0,0 +1,35 @@
+name: Deploy Nexus Preview to Pages
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/configure-pages@v5
+      - name: Prepare static assets
+        run: |
+          mkdir -p _site
+          cp index.html app.js style.css boot.js gofai_worker.js _site/
+          cp service-worker.js manifest.json robots.txt help.html _site/
+          cp portals.json vision.json _site/
+          cp -r nexus/ _site/nexus/
+          cp -r icons/ _site/icons/ 2>/dev/null || true
+          cp -r assets/ _site/assets/ 2>/dev/null || true
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: '_site'
+      - id: deployment
+        uses: actions/deploy-pages@v4

Dockerfile.preview

@@ -0,0 +1,9 @@
+FROM nginx:alpine
+RUN rm /etc/nginx/conf.d/default.conf
+COPY preview/nginx.conf /etc/nginx/conf.d/default.conf
+COPY index.html app.js style.css boot.js gofai_worker.js /usr/share/nginx/html/
+COPY service-worker.js manifest.json robots.txt help.html portals.json vision.json /usr/share/nginx/html/
+COPY nexus/ /usr/share/nginx/html/nexus/
+COPY icons/ /usr/share/nginx/html/icons/
+COPY assets/ /usr/share/nginx/html/assets/
+EXPOSE 3000

POLICY.md

@@ -27,7 +27,7 @@ All repositories must define default reviewers using CODEOWNERS-style configurat
 
 ---
 
-### 📋 Affected Repositories
+### <EFBFBD> Affected Repositories
 
 | Repository | Status | Notes |
 |-------------|--------|-------|
@@ -49,15 +49,46 @@ All repositories must define default reviewers using CODEOWNERS-style configurat
 
 ---
 
-### 🚧 Enforcement
+### <EFBFBD> Blocks
+
+- Blocks #916, #917
+- cc @Timmy @Rockachopa
+
+— @perplexity, Integration Architect + QA
+
+## 🛡️ Branch Protection Rules
+
+These rules must be applied to the `main` branch of all repositories:
+- [R] **Require Pull Request for Merge** – No direct pushes to `main`
+- [x] **Require 1 Approval** – At least one reviewer must approve
+- [R] **Dismiss Stale Approvals** – Re-review after new commits
+- [x] **Require CI to Pass** – Only allow merges with passing CI (where CI exists)
+- [x] **Block Force Push** – Prevent rewrite history
+- [x] **Block Branch Deletion** – Prevent accidental deletion of `main`
+
+## 👤 Default Reviewer
+
+- `@perplexity` – Default reviewer for all repositories
+- `@Timmy` – Required reviewer for `hermes-agent` (owner gate)
+
+## 🚧 Enforcement
 
 - All repositories must have these rules applied in the Gitea UI under **Settings > Branches > Branch Protection**.
 - CI must be configured and enforced for repositories with CI pipelines.
 - Reviewers assignments must be set via CODEOWNERS or manually in the UI.
 
----
+## 📌 Acceptance Criteria
 
-### 🧠 Notes
+- [ ] Branch protection rules applied to `main` in:
+  - `hermes-agent`
+  - `the-nexus`
+  - `timmy-home`
+  - `timmy-config`
+- [ ] `@perplexity` set as default reviewer
+- [ ] `@Timmy` set as required reviewer for `hermes-agent`
+- [ ] This policy documented in each repository's root
+
+## 🧠 Notes
 
 - For repositories without CI, the "Require CI to Pass" rule is optional.
-- This policy is versioned and must be updated as needed.
+- This policy is versioned and must be updated as needed.

PREVIEW.md

@@ -0,0 +1,26 @@
+# Nexus Preview
+
+ES module imports fail via `file://` or raw Forge URLs. `boot.js` warns: _"Serve over HTTP."_
+
+**Port 3000** (avoids L402 conflict on :8080, see #1415).
+
+## Quick Start
+
+```bash
+./preview.sh              # http://localhost:3000
+./preview.sh docker       # nginx + WS proxy
+docker compose up -d nexus-preview nexus-backend
+```
+
+## Triage Issues
+
+- #1413 — deploy.sh port comments wrong
+- #1414 — hardcoded VPS IP in app.js
+- #1415 — port 8080 conflict with L402
+
+## Files
+
+- `Dockerfile.preview` — nginx container
+- `preview/nginx.conf` — MIME types + WS proxy
+- `preview.sh` — Python preview server
+- `.github/workflows/pages.yml` — GitHub Pages CI/CD

README.md

@@ -118,6 +118,41 @@ Those pieces should be carried forward only if they serve the mission and are re
 There is no root browser app on current `main`.
 Do not tell people to static-serve the repo root and expect a world.
 
+### Branch Protection & Review Policy
+
+**All repositories enforce:**
+- PRs required for all changes
+- Minimum 1 approval required
+- CI/CD must pass
+- No force pushes
+- No direct pushes to main
+
+**Default reviewers:**
+- `@perplexity` for all repositories
+- `@Timmy` for nexus/ and hermes-agent/
+
+**Enforced by Gitea branch protection rules**
+
+### What you can run now
+
+- `python3 server.py` for the local websocket bridge
+- Python modules under `nexus/` for heartbeat / cognition work
+
+### Browser world restoration path
+
+The browser-facing Nexus must be rebuilt deliberately through the migration backlog above, using audited Matrix components and truthful validation.
+
+---
+
+*One 3D repo. One migration path. No more ghost worlds.*
+
+## Running Locally
+
+### Current repo truth
+
+There is no root browser app on current `main`.
+Do not tell people to static-serve the repo root and expect a world.
+
 ### What you can run now
 
 - `python3 server.py` for the local websocket bridge

deploy.sh

@@ -1,17 +1,25 @@
 #!/usr/bin/env bash
-# deploy.sh — spin up (or update) the Nexus staging environment
-# Usage: ./deploy.sh          — rebuild and restart nexus-main (port 4200)
-#        ./deploy.sh staging  — rebuild and restart nexus-staging (port 4201)
+# deploy.sh — Nexus environment
+# ./deploy.sh          — nexus-main (8765)
+# ./deploy.sh staging  — nexus-staging (8766)
+# ./deploy.sh preview  — static preview (3000)
+# ./deploy.sh full     — preview + backend
 set -euo pipefail
-
 SERVICE="${1:-nexus-main}"
-
 case "$SERVICE" in
   staging) SERVICE="nexus-staging" ;;
   main)    SERVICE="nexus-main" ;;
+  preview)
+    docker compose build nexus-preview
+    docker compose up -d --force-recreate nexus-preview
+    echo "==> http://localhost:3000"
+    exit 0 ;;
+  full)
+    docker compose build nexus-preview nexus-backend
+    docker compose up -d --force-recreate nexus-preview nexus-backend
+    echo "==> Preview: http://localhost:3000"
+    exit 0 ;;
 esac
-
-echo "==> Deploying $SERVICE …"
 docker compose build "$SERVICE"
 docker compose up -d --force-recreate "$SERVICE"
-echo "==> Done. Container: $SERVICE"
+echo "==> Done: $SERVICE"

docker-compose.yml

@@ -7,9 +7,28 @@ services:
     restart: unless-stopped
     ports:
       - "8765:8765"
+
   nexus-staging:
     build: .
     container_name: nexus-staging
     restart: unless-stopped
     ports:
-      - "8766:8765"
+      - "8766:8765"
+
+  nexus-backend:
+    build: .
+    container_name: nexus-backend
+    restart: unless-stopped
+    expose:
+      - "8765"
+
+  nexus-preview:
+    build:
+      context: .
+      dockerfile: Dockerfile.preview
+    container_name: nexus-preview
+    restart: unless-stopped
+    ports:
+      - "3000:3000"
+    depends_on:
+      - nexus-backend

preview.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+PORT="${1:-3000}"
+if [ "$PORT" = "docker" ]; then
+    docker compose up -d nexus-preview
+    echo "==> http://localhost:3000"
+    exit 0
+fi
+if ! command -v python3 &> /dev/null; then
+    echo "Error: python3 not found. Use './preview.sh docker'"
+    exit 1
+fi
+echo "==> http://localhost:$PORT"
+python3 -c "
+import http.server,socketserver
+class H(http.server.SimpleHTTPRequestHandler):
+    def end_headers(self):
+        self.send_header('Access-Control-Allow-Origin','*')
+        super().end_headers()
+    def guess_type(self,p):
+        if p.endswith(('.js','.mjs')): return 'application/javascript'
+        if p.endswith('.css'): return 'text/css'
+        if p.endswith('.json'): return 'application/json'
+        return super().guess_type(p)
+with socketserver.TCPServer(('', $PORT), H) as s:
+    print(f'Serving http://localhost:{$PORT}'); s.serve_forever()
+"

preview/nginx.conf

@@ -0,0 +1,51 @@
+server {
+    listen 3000;
+    server_name _;
+    root /usr/share/nginx/html;
+    index index.html;
+
+    location / {
+        try_files $uri $uri/ /index.html;
+        add_header X-Frame-Options "SAMEORIGIN" always;
+        add_header X-Content-Type-Options "nosniff" always;
+    }
+
+    location ~* \.js$ {
+        types { application/javascript js; }
+        add_header Cache-Control "public, max-age=3600";
+    }
+
+    location ~* \.css$ {
+        types { text/css css; }
+        add_header Cache-Control "public, max-age=3600";
+    }
+
+    location ~* \.json$ {
+        types { application/json json; }
+        add_header Cache-Control "no-cache";
+    }
+
+    location /api/world/ws {
+        proxy_pass http://nexus-backend:8765;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_read_timeout 86400;
+    }
+
+    location /ws {
+        proxy_pass http://nexus-backend:8765;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_read_timeout 86400;
+    }
+
+    location /health {
+        return 200 '{"status":"ok","service":"nexus-preview"}';
+        add_header Content-Type application/json;
+    }
+}