matrx-seo 0.1.0__tar.gz

matrx_seo-0.1.0/.gitignore

@@ -0,0 +1,271 @@
+*.pyc
+secrets/
+ignore/
+temp/
+logs/
+# The broad `logs/` rule above is for RUNTIME log output, but it also matched
+# the dashboard's SOURCE directory and silently swallowed an entire feature's
+# files (only the pre-existing index.tsx stayed tracked), breaking the prod
+# Docker build with "Could not resolve ./structured-tab". Re-include the source.
+!apps/dashboard/src/features/logs/
+!apps/dashboard/src/features/logs/**
+todo
+text_notes/
+aidream/secrets/2.env
+automation_matrix/matrix_processing/temp/*
+cd
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+.venv/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+# The blanket lib/ rule above is from the standard Python .gitignore template
+# and was silently swallowing TS source under the SPA `src/lib/` folders.
+# Re-allow them explicitly so frontend builds don't ship without their lib layer.
+!apps/dashboard/src/lib/
+!apps/dashboard/src/lib/**
+!apps/workflow-studio/src/lib/
+!apps/workflow-studio/src/lib/**
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+ai/tests/clean_response.json
+ai/tests/cx_storage_response.json
+ai/tests/execution_test.py
+ai/tests/final_response.json
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.env_remote
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.env.armanonly
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# random armani files
+/armani_dev/secrets/
+/armani/
+/_armani/
+
+
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+.idea/
+.vscode/
+/node_modules/
+
+# Frontend pnpm workspace (apps/) — node_modules at the workspace root and any
+# member, plus Vite caches and build output. The unified lockfile (apps/pnpm-lock.yaml)
+# IS committed; everything below is regenerated.
+node_modules/
+apps/**/.vite/
+apps/**/dist/
+.vite/
+
+dump.rdb
+
+frontend/
+
+# AME Temp Files and directory structure
+# Ignore all files in the temp directory and its subdirectories
+/temp/**/*
+/tmp/**/*
+
+# Allow .gitkeep files to retain directory structure
+!/temp/**/.gitkeep
+!/tmp/**/.gitkeep
+
+# Armani
+.history*
+.history/
+local_data/
+local_reports_data/
+webscraper/quick_scrapes/temp/
+automation_matrix/ai_apis/fireworks/_dev/*
+automation_matrix/ai_apis/fireworks/_dev/fireworks_sample.py
+*.pdf
+*.flac
+*.mp3
+*.wav
+miniconda.sh
+/database/python_sql/temp_data/
+ .history*
+ .history/
+.history/
+
+_dev/
+/_dev/
+requirements_filtered.txt
+
+# matrx-dev-tools backups
+.env-backups/
+# Matrx Ship config (contains API key)
+.matrx-ship.json
+
+# Matrx config (contains API keys)
+.matrx.json
+.matrx-tools.conf
+
+# Claude Code local worktrees and per-user settings
+.claude/worktrees/
+.claude/settings.local.json
+
+# Append-only snapshots from matrx_utils.update_history (unbounded; do not commit)
+common/utils/data_in_code/data_history.json
+packages/matrx-utils/matrx_utils/data_in_code/data_history.json
+
+# Tool-dispatch debug logs — one file per server start, never committed
+.matrx-debug/
+
+# macOS Finder metadata
+.DS_Store
+**/.DS_Store
+
+# Environment files
+.env
+.env.*
+*.env
+*.env.*
+
+# Keep safe templates trackable
+!.env.example
+!.env.sample
+!.env.template

matrx_seo-0.1.0/CLAUDE.md

@@ -0,0 +1,32 @@
+# CLAUDE.md — matrx-seo
+
+`matrx-seo` is the SEO vertical: provider/client layer + canonical ORM persistence over
+the live `seo.*` schema. Read `matrx_seo/FEATURE.md` before changing this package — it
+is the durable contract (repository semantics, identity names, association-only project
+linkage, battery credentials).
+
+Hard rules:
+
+- Persistence uses canonical `web.site` / `web.page` ids and links keywords to
+  `workspace.projects` ONLY through `platform.associations`
+  (`orm_identity.link_keyword_to_project`). No table may contain `project_id`; no
+  feature-specific project membership or site/page binding table may exist.
+- All DB access goes through matrx-orm models (`db/models_seo.py`, host mirrors in
+  `db/models_host.py`) — zero raw SQL.
+- Credentials resolve through the matrx-orm secrets battery
+  (`config.battery_credential_resolver`); no environment credential fallback.
+- Never import `aidream` or a repository-root module from `matrx_seo/` source
+  (tests may; only package source is boundary-checked).
+
+The standalone service is REAL (`standalone/app.py::create_app`): matrx-connect
+`AuthMiddleware` (Supabase JWTs only), boot gates (svc_seo pool from
+`SUPABASE_MATRIX_*`, `assert_service_role()`, explicit
+`CREDENTIALS_ENCRYPTION_KEY` round-trip, JWT material from
+`SUPABASE_MATRIX_URL`/`SUPABASE_JWT_SECRET`), and thin JSON routes over ONE
+`SeoCollectionService` (`/health`, `/health/ready`, `POST/GET /collections`,
+`GET /collections/{run_id}`). Standalone provider registry =
+`ADAPTER_FACTORIES` (brave / dataforseo / serpapi — the others need host client
+factories). MCP tools were deliberately skipped (auth-stack cost — see
+FEATURE.md). `scripts/independence_gate.sh` pins the boot contract in a bare
+venv; `tests/test_standalone_boot.py` pins it in the suite. matrx-connect is a
+`[standalone]`-extra dependency, not a core one.

matrx_seo-0.1.0/DEPLOY.md

@@ -0,0 +1,165 @@
+# Deploying matrx-seo (the SEO vertical service)
+
+STATUS 2026-07-21: **artifacts ready, NOT yet deployed.** Everything below is
+prepared; the first deploy needs three human actions (marked **[ARMAN]**) that
+an agent cannot do: an AWS SSO login, a one-time PyPI Trusted Publisher, and
+minting the `svc_seo` database password.
+
+The service runs **on the same EC2 box as matrx-files** (`i-084f757c1e47d4efb`
+/ `54.144.86.132`, Ship name `matrx-sandbox-host-dev`) — same pattern, same
+management surface, different container/port/hostname.
+
+| | matrx-files | matrx-seo |
+|---|---|---|
+| container | `matrx-files` | `matrx-seo` |
+| port (loopback only) | `127.0.0.1:8080` | `127.0.0.1:8081` |
+| env file (root 600) | `/etc/matrx-files.env` | `/etc/matrx-seo.env` |
+| build dir on box | `/opt/matrx-files` | `/opt/matrx-seo` |
+| public URL | `https://files.matrxserver.com` | `https://seo.matrxserver.com` |
+| TLS | shared Caddy container (`matrx-files-tls`, host network, :443) | **same container, new site block** |
+
+**One Caddy for the box.** Do NOT start a second TLS container — :443 is taken.
+Add a `seo.matrxserver.com` block to the existing Caddyfile and reload.
+
+---
+
+## The database contract — there is ONE database
+
+The service connects to **Matrx Main**, the same Postgres everything else uses,
+through the **same env var names** (`SUPABASE_MATRIX_*`). There is no SEO
+database and no SEO-specific connection variable.
+
+What differs on THIS deployment is only the **credentials**: `SUPABASE_MATRIX_USER`
+is `svc_seo`, a role that owns the `seo` schema and is granted exactly the
+platform surfaces in [`matrx_seo/db/grants.yaml`](matrx_seo/db/grants.yaml).
+The service asserts this at boot (`assert_service_role`) and **crashes if handed
+a broad role** — that assertion is what makes the boundary real rather than
+documentation.
+
+### `/etc/matrx-seo.env` (root 600)
+
+```ini
+# The ONE database (identical names to aidream/scraper/files).
+SUPABASE_MATRIX_HOST=<same as every other service>
+SUPABASE_MATRIX_PORT=6543
+SUPABASE_MATRIX_DATABASE_NAME=postgres
+SUPABASE_MATRIX_USER=svc_seo                 # <- the ONLY per-deployment difference
+SUPABASE_MATRIX_PASSWORD=<minted below>      # <- svc_seo's password
+
+# Supabase JWT verification (JWKS) — same value every service uses.
+SUPABASE_MATRIX_URL=<same as every other service>
+
+# The ONE platform encryption key (matrx-orm secrets battery). Same value as
+# aidream/scraper — provider API keys are read straight from users.user_secrets.
+CREDENTIALS_ENCRYPTION_KEY=<same as every other service>
+```
+
+Every one of these already exists on the other servers. **Copy the values; do
+not invent new ones.**
+
+---
+
+## First deploy — the runbook
+
+### 0. **[ARMAN]** One-time PyPI Trusted Publisher
+`https://pypi.org/manage/account/publishing/` → pending publisher:
+owner `AI-Matrix-Engine`, repo `aidream`, workflow `publish-package.yml`,
+environment blank, project `matrx-seo`. (Same one-time step every workspace
+package needed.)
+
+### 1. **[ARMAN]** Mint the `svc_seo` login
+The role exists and owns its schema, but is `NOLOGIN` with no password — it
+cannot connect until you give it one. In the Supabase SQL editor:
+
+```sql
+ALTER ROLE svc_seo LOGIN PASSWORD '<a strong password you generate>';
+```
+
+Put that same password in `/etc/matrx-seo.env` as `SUPABASE_MATRIX_PASSWORD`.
+Nobody needs to see it again — the drift guard never reads it, and the service
+only proves *which role* it connected as.
+
+> Keeping it `NOLOGIN` until deploy day is deliberate: the boundary exists in
+> the database from the moment the schema did, but no credential existed to
+> leak in the meantime.
+
+### 2. **[ARMAN]** AWS SSO (the deploy script rides SSM)
+```bash
+aws sso login --profile AdministratorAccess-872515272894
+ssh matrx-sandbox 'echo ok'   # must print ok
+```
+
+### 3. Publish the package
+```bash
+cd ~/code/aidream
+git tag matrx-seo/v0.1.0 && git push origin refs/tags/matrx-seo/v0.1.0
+# CI publishes to PyPI; confirm: https://pypi.org/project/matrx-seo/
+```
+matrx-orm must also be published at a version containing the secrets battery +
+role-aware associations (tag `matrx-orm/v<version>` the same way) — the
+Dockerfile resolves it from PyPI.
+
+### 4. Put the env file on the box
+```bash
+scp /tmp/matrx-seo.env matrx-sandbox:/tmp/matrx-seo.env
+ssh matrx-sandbox 'sudo mv /tmp/matrx-seo.env /etc/matrx-seo.env && sudo chown root:root /etc/matrx-seo.env && sudo chmod 600 /etc/matrx-seo.env'
+```
+
+### 5. Deploy
+```bash
+cd ~/code/aidream/packages/matrx-seo
+./deploy.sh 0.1.0
+```
+The script refuses to swap the live container unless the built image really
+contains that version, and after the swap it requires readiness to report
+`service_role: true` — i.e. it proves the service came up **inside its granted
+boundary**.
+
+### 6. TLS + DNS (first deploy only)
+Add the site block to the box's shared Caddyfile (`/opt/matrx-files/Caddyfile`):
+
+```
+seo.matrxserver.com {
+    tls internal
+    reverse_proxy 127.0.0.1:8081
+}
+```
+Then `ssh matrx-sandbox 'sudo docker restart matrx-files-tls'`.
+
+Cloudflare: A record `seo.matrxserver.com` → `54.144.86.132`, **proxied**,
+SSL mode Full (already set for the zone). Security group `sg-05a1b5a6163cd8ee6`
+already allows 443 from Cloudflare ranges only — **no new SG rule**, and 8081
+stays closed to the world (the app binds loopback).
+
+### 7. Register in Ship
+Already recorded in [`matrx-ship/SERVERS_AND_ROUTES.md`](/Users/armanisadeghi/code/matrx-ship/SERVERS_AND_ROUTES.md).
+Drop the service descriptor on the box so the Manager UI lists it:
+```bash
+ssh matrx-sandbox 'sudo tee /opt/matrx-seo/service.json >/dev/null <<JSON
+{"name":"matrx-seo","container":"matrx-seo","port":8081,
+ "public_url":"https://seo.matrxserver.com","health":"/health",
+ "readiness":"/health/ready","env_file":"/etc/matrx-seo.env",
+ "repo":"aidream/packages/matrx-seo"}
+JSON'
+```
+
+---
+
+## Manage
+
+`ssh matrx-sandbox`, or the Manager host-exec
+(`POST /api/hosts/matrx-sandbox-host-dev/exec` → `sudo docker …`).
+
+- App: `sudo docker {ps,logs,restart} matrx-seo`
+- TLS: `sudo docker {logs,restart} matrx-files-tls` (shared)
+- **Env changes need `docker rm` + `run`, not `restart`** — `--env-file` is read
+  only at run time. Re-running `./deploy.sh <version>` does this correctly.
+- Rollback: `./deploy.sh <previous-version>`
+
+## Health contract
+
+- `GET /health` — liveness, unauthenticated.
+- `GET /health/ready` — 503 until every boot gate passes; the body names the
+  failed component (`database` / `service_role` / `models` /
+  `credentials_encryption` / `service`).
+- Every `/collections*` route requires a Supabase JWT (401 otherwise).

matrx_seo-0.1.0/Dockerfile

@@ -0,0 +1,20 @@
+# Matrx SEO — standalone vertical service image.
+#
+# Installs ENTIRELY from PyPI (every matrx-* dep is published; a bare
+# `uv pip install matrx-seo[standalone]` is proven by the independence gate).
+# Build from anywhere:
+#   docker build -t matrx-seo packages/matrx-seo
+# Pin the version at build time for reproducible deploys:
+#   docker build --build-arg MATRX_SEO_VERSION==0.1.0 -t matrx-seo:0.1.0 packages/matrx-seo
+#
+# No system binaries: this service talks HTTP to SEO providers and Postgres to
+# the ONE database. Nothing to render, nothing to OCR — keep the image small.
+FROM python:3.13-slim
+
+RUN pip install --no-cache-dir uv
+
+ARG MATRX_SEO_VERSION=""
+RUN uv pip install --system "matrx-seo[standalone]${MATRX_SEO_VERSION}"
+
+EXPOSE 8081
+CMD ["uvicorn", "matrx_seo.standalone.app:create_app", "--factory", "--host", "0.0.0.0", "--port", "8081"]

matrx_seo-0.1.0/INDEPENDENCE.md

@@ -0,0 +1,6 @@
+# Package independence
+
+This package follows `/Users/armanisadeghi/code/matrx-package-template/INDEPENDENCE.md`:
+no host imports, explicit injected configuration, and package-owned contracts,
+schema manifest, models, migrations, tests, and standalone boot surface.
+

matrx_seo-0.1.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: matrx-seo
+Version: 0.1.0
+Summary: Provider-neutral SEO collection contracts and canonical persistence.
+Requires-Python: >=3.13
+Requires-Dist: httpx>=0.28
+Requires-Dist: matrx-orm>=3.1
+Requires-Dist: matrx-utils
+Requires-Dist: pydantic>=2.12
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Provides-Extra: standalone
+Requires-Dist: fastapi>=0.115; extra == 'standalone'
+Requires-Dist: matrx-connect; extra == 'standalone'
+Requires-Dist: uvicorn>=0.34; extra == 'standalone'
+Description-Content-Type: text/markdown
+
+# matrx-seo
+
+Provider-neutral SEO provider clients, collection contracts, normalization, replay
+fixtures, and canonical persistence for Matrx. Durable persistence is temporarily absent
+while it is rebuilt on `platform.associations`; persistence remains part of this package's
+required product boundary. See
+[`matrx_seo/FEATURE.md`](matrx_seo/FEATURE.md) for the current contract.

matrx_seo-0.1.0/README.md

@@ -0,0 +1,7 @@
+# matrx-seo
+
+Provider-neutral SEO provider clients, collection contracts, normalization, replay
+fixtures, and canonical persistence for Matrx. Durable persistence is temporarily absent
+while it is rebuilt on `platform.associations`; persistence remains part of this package's
+required product boundary. See
+[`matrx_seo/FEATURE.md`](matrx_seo/FEATURE.md) for the current contract.

matrx_seo-0.1.0/deploy.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# Deploy matrx-seo to the live EC2 box behind https://seo.matrxserver.com
+#
+#   ./deploy.sh 0.1.0        # deploy a version (must already be on PyPI)
+#   ./deploy.sh 0.0.9        # rolling back is the same command
+#
+# Mirrors packages/matrx-files/deploy.sh (same box, same pattern) and REFUSES
+# to touch the live container until the new image is proven:
+#   1. checks PyPI actually has the version (tag push publishes it)
+#   2. syncs THIS directory's canonical Dockerfile to the box (kills drift)
+#   3. builds matrx-seo:<version> on the box
+#   4. asserts the built image really contains <version> (aborts otherwise)
+#   5. swaps the container (rm + run — NEVER docker restart: --env-file is
+#      read only at run time)
+#   6. health-checks locally and through Cloudflare, and proves the service
+#      is inside its granted DB boundary (readiness reports service_role)
+#
+# Requires: `ssh matrx-sandbox` working (SSM per ~/.ssh/config; run
+# `aws sso login --profile AdministratorAccess-872515272894` first if stale).
+#
+# The box needs /etc/matrx-seo.env (root 600) BEFORE the first deploy — see
+# DEPLOY.md. It carries the ONE database's standard SUPABASE_MATRIX_* vars
+# with USER/PASSWORD set to the svc_seo role, plus CREDENTIALS_ENCRYPTION_KEY.
+set -euo pipefail
+
+VERSION="${1:?usage: deploy.sh <version, e.g. 0.1.0>}"
+HOST="${MATRX_SEO_HOST:-matrx-sandbox}"
+PUBLIC_BASE="https://seo.matrxserver.com"
+PORT=8081
+DIR="$(cd "$(dirname "$0")" && pwd)"
+
+echo "==> [1/6] checking PyPI has matrx-seo==${VERSION}"
+if ! curl -sf -m 15 "https://pypi.org/pypi/matrx-seo/${VERSION}/json" >/dev/null; then
+  echo "ERROR: matrx-seo==${VERSION} is not on PyPI."
+  echo "       Publish first: cd aidream && git tag matrx-seo/v${VERSION} && git push origin refs/tags/matrx-seo/v${VERSION}"
+  exit 1
+fi
+
+echo "==> [2/6] syncing canonical Dockerfile to ${HOST}:/opt/matrx-seo/"
+ssh "${HOST}" 'sudo mkdir -p /opt/matrx-seo'
+scp -q "${DIR}/Dockerfile" "${HOST}:/tmp/matrx-seo.Dockerfile"
+ssh "${HOST}" 'sudo mv /tmp/matrx-seo.Dockerfile /opt/matrx-seo/Dockerfile'
+
+echo "==> [3/6] building matrx-seo:${VERSION} on ${HOST}"
+ssh "${HOST}" "sudo docker build --build-arg MATRX_SEO_VERSION='==${VERSION}' -t 'matrx-seo:${VERSION}' /opt/matrx-seo"
+
+echo "==> [4/6] verifying the image really contains ${VERSION}"
+GOT="$(ssh "${HOST}" "sudo docker run --rm --entrypoint python 'matrx-seo:${VERSION}' -c 'import importlib.metadata as m; print(m.version(\"matrx-seo\"))'" | tr -d '[:space:]')"
+if [ "${GOT}" != "${VERSION}" ]; then
+  echo "ERROR: built image contains matrx-seo ${GOT}, expected ${VERSION} — ABORTING; live container untouched."
+  exit 1
+fi
+echo "    image verified: ${GOT}"
+
+echo "==> [5/6] swapping the live container (rm + run)"
+ssh "${HOST}" "sudo docker rm -f matrx-seo >/dev/null 2>&1 || true; sudo docker run -d --name matrx-seo --restart unless-stopped --env-file /etc/matrx-seo.env -p 127.0.0.1:${PORT}:${PORT} 'matrx-seo:${VERSION}'"
+
+echo "==> [6/6] health checks"
+HEALTH=""
+for _ in $(seq 1 20); do
+  HEALTH="$(ssh "${HOST}" "curl -sf -m 5 http://127.0.0.1:${PORT}/health" 2>/dev/null || true)"
+  [ -n "${HEALTH}" ] && break
+  sleep 2
+done
+if [ -z "${HEALTH}" ]; then
+  echo "ERROR: health never came up on the box. Logs: ssh ${HOST} 'sudo docker logs --tail 50 matrx-seo'"
+  echo "       Roll back: ./deploy.sh <previous-version>"
+  exit 1
+fi
+echo "    box health: ${HEALTH}"
+
+# Readiness proves the BOUNDARY: the service booted only because it connected
+# as svc_seo and the encryption key round-tripped. A 503 here means a boot gate
+# refused — read the body, it names the failed component.
+READY="$(ssh "${HOST}" "curl -s -m 10 http://127.0.0.1:${PORT}/health/ready" 2>/dev/null || true)"
+echo "    box readiness: ${READY}"
+case "${READY}" in
+  *'"service_role": true'*|*'"service_role":true'*) echo "    boundary OK: connected as svc_seo" ;;
+  *) echo "ERROR: readiness does not confirm the svc_seo boundary — ABORTING the rollout check."
+     echo "       Logs: ssh ${HOST} 'sudo docker logs --tail 50 matrx-seo'"
+     exit 1 ;;
+esac
+
+echo "    public health: $(curl -sf -m 10 "${PUBLIC_BASE}/health" || echo 'UNREACHABLE (DNS/Caddy not wired yet?)')"
+ANON="$(curl -s -m 10 -o /dev/null -w '%{http_code}' "${PUBLIC_BASE}/collections?organization_id=00000000-0000-0000-0000-000000000000")"
+echo "    anon /collections -> HTTP ${ANON} (expect 401)"
+
+echo "DONE: matrx-seo ${VERSION} is live at ${PUBLIC_BASE}. Rollback = ./deploy.sh <previous-version>"