feat(ci): add deploy-backend workflow + Phase 2C runbook + Live Demo README section

.github/workflows/deploy-backend.yml

@@ -0,0 +1,49 @@
+name: Deploy backend to HuggingFace Space
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: deploy-backend
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  push-to-space:
+    name: Push main to HF Space
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      (github.event.workflow_run.conclusion == 'success' &&
+       github.event.workflow_run.head_branch == 'main')
+    env:
+      HF_USERNAME: apoorvrajdev
+      HF_SPACE: image-captioning-api
+    steps:
+      - name: Checkout full history
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Configure git identity
+        run: |
+          git config user.name "apoorvrajdev"
+          git config user.email "apoorvrajmgr@gmail.com"
+
+      - name: Push to HuggingFace Space
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          if [ -z "${HF_TOKEN}" ]; then
+            echo "::error::HF_TOKEN secret is not set. Add it under repo Settings → Secrets and variables → Actions."
+            exit 1
+          fi
+          git remote add space "https://${HF_USERNAME}:${HF_TOKEN}@huggingface.co/spaces/${HF_USERNAME}/${HF_SPACE}"
+          git push space HEAD:main

README.md

@@ -28,7 +28,7 @@ short_description: InceptionV3 + Transformer image captioning inference API
 <p align="center">
   <img alt="Ruff"             src="https://img.shields.io/badge/lint-ruff-261230?style=flat-square&logo=ruff&logoColor=white">
   <img alt="mypy strict"      src="https://img.shields.io/badge/typed-mypy%20strict-1F5082?style=flat-square">
-  <img alt="Tests"            src="https://img.shields.io/badge/tests-90%20passing-brightgreen?style=flat-square">
+  <img alt="Tests"            src="https://img.shields.io/badge/tests-94%20passing-brightgreen?style=flat-square">
   <img alt="Pre-commit"       src="https://img.shields.io/badge/pre--commit-enabled-FAB040?style=flat-square&logo=pre-commit&logoColor=white">
   <img alt="IEEE Published"   src="https://img.shields.io/badge/IEEE-published-00629B?style=flat-square&logo=ieee&logoColor=white">
   <img alt="License: MIT"     src="https://img.shields.io/badge/license-MIT-blue?style=flat-square">
@@ -48,6 +48,20 @@ short_description: InceptionV3 + Transformer image captioning inference API
 
 ---
 
+## 🌐 Live Demo
+
+| Component | URL | What you can do |
+|---|---|---|
+| **Frontend SPA** | https://image-captioning-system.vercel.app | Drag-and-drop an image, hit **Generate caption**, see the typed `CaptionResponse` rendered with model version, decode strategy, and latency |
+| **Backend API** | https://apoorvrajdev-image-captioning-api.hf.space | Interactive Swagger at [`/docs`](https://apoorvrajdev-image-captioning-api.hf.space/docs); liveness + readiness at [`/healthz`](https://apoorvrajdev-image-captioning-api.hf.space/healthz); inference at `POST /v1/captions` |
+| **Weights (HF Hub)** | https://huggingface.co/apoorvrajdev/captioning-inceptionv3-transformer | Pinned to tag `v1.0.0`; the backend pulls these at lifespan startup via `snapshot_download` so the Space's git tree never contains the `.h5` |
+
+Deployment topology: GitHub `main` → CI on every push → on green, `deploy-backend.yml` pushes to a HuggingFace Space (Docker SDK, cpu-basic, port 7860, single uvicorn worker); Vercel's Git integration builds and promotes the SPA in parallel. Production CORS is wired through the Space's `CAPTIONING__SERVE__CORS_ALLOWED_ORIGINS` variable, not a hardcoded config. Full topology + rollback procedure: [`docs/PHASE_2C_DEPLOYMENT_RUNBOOK.md`](docs/PHASE_2C_DEPLOYMENT_RUNBOOK.md). CI/CD workflows: [`docs/CI.md`](docs/CI.md).
+
+> ⚠️ The live caption you get will look like noise (e.g. `"plate city mountain [UNK]"`). That is the dev-scaffold weight story above — the infrastructure is what's being demonstrated end-to-end; the trained checkpoint is a future `v2.0.0` swap with **zero code changes** (just a Space variable bump from `v1.0.0` → `v2.0.0`).
+
+---
+
 ## 📌 What Is This Project?
 
 Image Captioning System is a research-to-production conversion of the IEEE paper *"AI Narratives: Bridging Visual Content and Linguistic Expression"*. The original work — a Kaggle notebook training an InceptionV3-encoder + multi-head Transformer-decoder on MS COCO — is preserved verbatim as the canonical research artefact. Around it sits a typed Python package, a FastAPI inference service, and a React SPA that together turn the published model into something a serving team could actually run, version, and reason about.
@@ -552,20 +566,20 @@ The backend test suite ([`backend/app/tests/`](backend/app/tests/)) introduced i
 - [x] **2B-6** — Single `ErrorBanner` surface mapping every `ApiError.kind` to actionable copy
 - [x] **2B-7** — CORS allow-list wired through backend YAML (`serve.cors_allowed_origins`), dev origins pre-allowed
 
-### Phase 2C — Public deployment 🚧 (in progress)
+### Phase 2C — Public deployment ✅ (complete)
 
 - [x] **WS-A** — Backend containerisation: `Dockerfile` (python:3.11-slim, non-root UID 1000, EXPOSE 7860, HEALTHCHECK on `/healthz`) + `.dockerignore` + corrected `.env.example` schema
 - [x] **WS-A4** — Lifespan integration with HuggingFace Hub: extended `BackendSettings` with `weights_hub_repo` / `weights_hub_revision` / `weights_hub_filename` / `weights_cache_dir`; new `app.services.weights_loader.resolve_weights` calls `huggingface_hub.snapshot_download` when configured, falls back to local paths otherwise (4 new unit tests, downloader injected for offline testing)
 - [x] **WS-B** — Uploaded dev-scaffold weights + tokenizer to [`apoorvrajdev/captioning-inceptionv3-transformer`](https://huggingface.co/apoorvrajdev/captioning-inceptionv3-transformer) on HuggingFace Hub, tagged `v1.0.0`, verified via `snapshot_download` (SHA-256 hashes match local artefacts byte-for-byte)
 - [x] **WS-C** — First manual deploy to [`apoorvrajdev/image-captioning-api`](https://huggingface.co/spaces/apoorvrajdev/image-captioning-api) on HuggingFace Spaces (Docker SDK, cpu-basic, port 7860, single worker) — Space variables wire `BACKEND_WEIGHTS_HUB_REPO` / `_REVISION` / `_FILENAME` + `BACKEND_WARMUP=true`; lifespan pulls weights from the Hub on cold start; `/healthz` returns `model_loaded: true` and `/v1/captions` verified end-to-end via Swagger UI
 - [x] **WS-D** — **Backend test suite** ([`backend/app/tests/`](backend/app/tests/)): 12 route tests covering the full `/healthz` + `/v1/captions` contract (200 / 400 / 413 / 415 / 422 / 503) with a duck-typed `FakePredictorService` — no TF loaded, full slice runs in 0.3 s
-- [ ] **WS-E** — Frontend deploy to Vercel (static SPA, `VITE_API_BASE` baked at build time, SPA rewrites)
-- [ ] **WS-F** — Production CORS: add the deployed Vercel origin to `serve.cors_allowed_origins`
-- [ ] **WS-G** — GitHub Actions CI/CD:
+- [x] **WS-E** — Frontend deploy to Vercel: `frontend/` imported as a Vite project, `VITE_API_BASE` env var baked at build time, production alias [`image-captioning-system.vercel.app`](https://image-captioning-system.vercel.app) auto-redeployed on every push to `main` via Vercel's GitHub integration
+- [x] **WS-F** — Production CORS: deployed Vercel origin added to `serve.cors_allowed_origins` via the Space's `CAPTIONING__SERVE__CORS_ALLOWED_ORIGINS` variable (JSON array, pydantic-settings parsed), so the policy is explicit in app config rather than relying on the HF reverse-proxy default
+- [x] **WS-G** — GitHub Actions CI/CD:
   - [x] `ci.yml` — Python quality (ruff lint + format check, mypy), pytest matrix on 3.10/3.11/3.12, notebook SHA-256 freeze check, frontend lint + build, concurrency cancel-in-progress, pip + npm caching
-  - [ ] `deploy-backend.yml` — gated on `needs: ci`, pushes to the HF Space
-  - [ ] `deploy-frontend.yml` *(optional)* — Vercel-native GitHub integration is the recommended path
-- [ ] **WS-H** — README "Live Demo" section (badges swapped to live HF Space + Vercel URLs) + `docs/PHASE_2C_DEPLOYMENT_RUNBOOK.md` + `docs/CI.md`
+  - [x] [`deploy-backend.yml`](.github/workflows/deploy-backend.yml) — chained via `workflow_run` after CI, pushes `HEAD:main` to the HF Space remote using the `HF_TOKEN` repo secret; also supports `workflow_dispatch` for manual redeploys
+  - [x] `deploy-frontend.yml` *(skipped — Vercel-native GitHub integration deploys on every push, no separate workflow needed)*
+- [x] **WS-H** — "[Live Demo](#-live-demo)" section above + [`docs/PHASE_2C_DEPLOYMENT_RUNBOOK.md`](docs/PHASE_2C_DEPLOYMENT_RUNBOOK.md) (full topology, prerequisites, weights upload, Space setup, Vercel setup, CORS, CI/CD, smoke tests, known quirks, rollback) + [`docs/CI.md`](docs/CI.md) (workflow reference)
 
 ### Phase 3 — Multimodal baselines ⏳ (planned)
 

docs/CI.md

@@ -0,0 +1,61 @@
+# CI / CD
+
+GitHub Actions runs two workflows out of [`.github/workflows/`](../.github/workflows/).
+
+## `ci.yml` — quality + tests
+
+Triggered on every push and pull request to `main`. Four parallel jobs:
+
+| Job | What it runs | Why |
+|---|---|---|
+| `python-quality` | `ruff check`, `ruff format --check`, `mypy --strict` on `src/` and `backend/` | Catch style + typing regressions before they land |
+| `python-tests` | `pytest` matrix on Python **3.10 / 3.11 / 3.12** | Confirm the package keeps working on every supported interpreter |
+| `notebook-freeze` | `make freeze-paper-notebook` (SHA-256 check) | Fail if the IEEE notebook is mutated — it is the canonical research artefact |
+| `frontend` | `npm ci`, `npm run lint`, `npm run build` on Node 20 | Catch ESLint + Vite build regressions in the SPA |
+
+Caching:
+- pip via `actions/setup-python` (key derived from `requirements*.txt` + `pyproject.toml`)
+- npm via `actions/setup-node` (key derived from `frontend/package-lock.json`)
+
+Concurrency: stacked runs on the same ref cancel each other so only the
+newest commit's CI completes.
+
+## `deploy-backend.yml` — push main to the HF Space
+
+Triggered by:
+- `workflow_run` on `CI` completion, only when conclusion is `success` and
+  branch is `main` (so a failing CI never deploys)
+- `workflow_dispatch` for manual redeploys from the Actions tab
+
+The job:
+1. Checks out the full git history (HF Space remote needs the parent
+   commits to fast-forward)
+2. Sets a fixed git identity (`apoorvrajdev <apoorvrajmgr@gmail.com>`)
+3. Adds a `space` remote authenticated with the `HF_TOKEN` repository secret
+4. Pushes `HEAD:main` to the Space
+
+The Space then rebuilds its Docker image. See
+[`PHASE_2C_DEPLOYMENT_RUNBOOK.md`](PHASE_2C_DEPLOYMENT_RUNBOOK.md) for the
+end-to-end deployment topology and smoke tests.
+
+## Required secrets
+
+- `HF_TOKEN` — HuggingFace personal access token, **Write** scope. Used only
+  by `deploy-backend.yml` to push to the Space remote.
+
+Set under repo Settings → Secrets and variables → Actions → New repository
+secret.
+
+## Local equivalents
+
+Everything CI does is reproducible locally:
+
+```bash
+make lint            # ruff check + format --check
+make typecheck       # mypy strict
+make test            # pytest (single Python version)
+make freeze-paper-notebook   # SHA-256 freeze check
+
+cd frontend
+npm ci && npm run lint && npm run build
+```

docs/PHASE_2C_DEPLOYMENT_RUNBOOK.md

@@ -0,0 +1,233 @@
+# Phase 2C — Public Deployment Runbook
+
+This runbook captures every step needed to (re)deploy the Image Captioning System
+to its public hosts: weights to the HuggingFace Hub, backend to a HuggingFace
+Space, frontend to Vercel, and the CI/CD chain wiring it all together. It is
+written so a future maintainer (or the author six months from now) can rebuild
+the public deployment from a cold start without reading commit history.
+
+## 0. Topology
+
+```
+GitHub (apoorvrajdev/image-captioning-system, main)
+  ├── Actions: CI → Deploy backend to HuggingFace Space (workflow_run chained)
+  └── Vercel Git Integration → image-captioning-system.vercel.app
+
+HuggingFace Hub
+  ├── Model repo: apoorvrajdev/captioning-inceptionv3-transformer  (weights + vocab, tag v1.0.0)
+  └── Space:     apoorvrajdev/image-captioning-api                  (Docker SDK, cpu-basic, port 7860)
+```
+
+The Space pulls weights from the model repo at lifespan startup via
+`huggingface_hub.snapshot_download`, so the Space's git tree never contains
+`model.h5` — only the code that knows how to fetch it.
+
+---
+
+## 1. Live URLs
+
+| Component | URL |
+|---|---|
+| Frontend SPA | `https://image-captioning-system.vercel.app` |
+| Backend API | `https://apoorvrajdev-image-captioning-api.hf.space` |
+| Backend health | `https://apoorvrajdev-image-captioning-api.hf.space/healthz` |
+| Backend docs (Swagger) | `https://apoorvrajdev-image-captioning-api.hf.space/docs` |
+| Weights repo | `https://huggingface.co/apoorvrajdev/captioning-inceptionv3-transformer` |
+| Space console | `https://huggingface.co/spaces/apoorvrajdev/image-captioning-api` |
+
+---
+
+## 2. Prerequisites
+
+- Local git working tree on `main`, clean
+- Python 3.11 venv with `requirements.txt` + `requirements-dev.txt` installed
+- A HuggingFace account and a personal access token with **Write** scope
+  (Settings → Access Tokens). Used both in the local shell (`huggingface-cli login`)
+  and as a GitHub Actions secret named `HF_TOKEN`
+- A Vercel account connected to the GitHub repo
+
+---
+
+## 3. Weights upload (WS-B) — only when shipping a new checkpoint
+
+The Space's `BACKEND_WEIGHTS_HUB_REVISION` variable pins which Hub revision
+the backend pulls at startup, so weights and code can be versioned
+independently.
+
+```bash
+# 1. Login (token cached at ~/.cache/huggingface/token)
+huggingface-cli login
+
+# 2. Upload the contents of models/vX.Y.Z/ to the Hub repo
+python - <<'PY'
+from huggingface_hub import HfApi
+api = HfApi()
+api.upload_folder(
+    repo_id="apoorvrajdev/captioning-inceptionv3-transformer",
+    folder_path="models/v1.0.0",
+    path_in_repo=".",
+    commit_message="upload v1.0.0 weights + vocab",
+)
+api.create_tag(
+    repo_id="apoorvrajdev/captioning-inceptionv3-transformer",
+    tag="v1.0.0",
+    tag_message="v1.0.0 dev-scaffold weights",
+)
+PY
+
+# 3. Verify the snapshot round-trips byte-for-byte
+HF_HUB_DISABLE_SYMLINKS=1 python - <<'PY'
+import hashlib, pathlib
+from huggingface_hub import snapshot_download
+local = snapshot_download(
+    repo_id="apoorvrajdev/captioning-inceptionv3-transformer",
+    revision="v1.0.0",
+)
+for f in ("model.h5", "vocab.json"):
+    src = hashlib.sha256(pathlib.Path("models/v1.0.0", f).read_bytes()).hexdigest()
+    dst = hashlib.sha256(pathlib.Path(local, f).read_bytes()).hexdigest()
+    assert src == dst, f
+    print(f, "OK", src)
+PY
+```
+
+To promote a new checkpoint after this: bump the Space variable
+`BACKEND_WEIGHTS_HUB_REVISION` from `v1.0.0` to the new tag (e.g. `v2.0.0`)
+and the Space restarts with the new weights. No code change required.
+
+---
+
+## 4. Backend Space (WS-C) — one-time setup
+
+1. Create the Space at https://huggingface.co/new-space
+   - Owner: `apoorvrajdev` · Name: `image-captioning-api`
+   - SDK: **Docker** (blank template) · Hardware: **cpu-basic (free)** · Public
+2. In the Space's **Settings → Variables and secrets**, add **Variables**
+   (not secrets — these are non-sensitive):
+
+   | Name | Value |
+   |---|---|
+   | `BACKEND_WEIGHTS_HUB_REPO` | `apoorvrajdev/captioning-inceptionv3-transformer` |
+   | `BACKEND_WEIGHTS_HUB_REVISION` | `v1.0.0` |
+   | `BACKEND_WEIGHTS_HUB_FILENAME` | `model.h5` |
+   | `BACKEND_WARMUP` | `true` |
+   | `CAPTIONING__SERVE__CORS_ALLOWED_ORIGINS` | `["https://image-captioning-system.vercel.app","http://localhost:5173","http://localhost:5174","http://127.0.0.1:5173","http://127.0.0.1:5174"]` |
+
+3. Add a `space` git remote and push `main`:
+   ```bash
+   git remote add space https://huggingface.co/spaces/apoorvrajdev/image-captioning-api
+   git push space main
+   ```
+4. Watch the Space's **Logs** tab. First build takes ~8–12 min (Docker base
+   pull, `apt-get`, `pip install -r requirements.txt` with TensorFlow,
+   weight download via `snapshot_download`, predictor warmup).
+5. When the badge in the Space header turns **Running**, verify:
+   ```bash
+   curl https://apoorvrajdev-image-captioning-api.hf.space/healthz
+   # {"status":"ok","model_loaded":true,"model_version":"v1.0.0",...}
+   ```
+
+The README YAML frontmatter (`title`, `emoji`, `sdk: docker`, `app_port: 7860`,
+etc.) is what tells the Space how to build. It must remain at the literal top
+of `README.md`. GitHub auto-hides the frontmatter when rendering the README, so
+the same file serves both audiences.
+
+---
+
+## 5. Frontend (WS-E) — Vercel one-time setup
+
+1. https://vercel.com/new → import `apoorvrajdev/image-captioning-system`
+2. Configure:
+   - Framework Preset: **Vite** (auto-detected from `frontend/package.json`)
+   - Root Directory: `frontend`
+   - Build / Output / Install commands: leave on defaults
+3. Environment variable (Production + Preview):
+   - `VITE_API_BASE` = `https://apoorvrajdev-image-captioning-api.hf.space`
+4. Deploy. First build is ~90 sec. Production alias becomes
+   `https://image-captioning-system.vercel.app`.
+
+After the initial import every push to `main` triggers an automatic Vercel
+build via the GitHub integration — no separate GitHub Action required.
+
+---
+
+## 6. CORS (WS-F)
+
+`backend/app/main.py` registers `CORSMiddleware` with
+`config.serve.cors_allowed_origins`. The defaults in
+[`configs/base.yaml`](../configs/base.yaml) cover localhost dev. Production
+origins are added via the Space's `CAPTIONING__SERVE__CORS_ALLOWED_ORIGINS`
+variable (JSON array, see §4). To add a new origin (e.g. a custom domain):
+edit that variable, save, and the Space restarts (~30 sec, no rebuild).
+
+---
+
+## 7. CI/CD (WS-G)
+
+Two workflows under [`.github/workflows/`](../.github/workflows/):
+
+- **`ci.yml`** — runs on every push and PR to `main`:
+  - `python-quality`: ruff lint + format, mypy strict
+  - `python-tests`: pytest matrix on 3.10 / 3.11 / 3.12
+  - `notebook-freeze`: SHA-256 freeze check on the IEEE notebook
+  - `frontend`: `npm ci && npm run lint && npm run build`
+- **`deploy-backend.yml`** — chained via `workflow_run`, runs only after a
+  successful `CI` run on `main`. Pushes `HEAD:main` to the Space remote using
+  the `HF_TOKEN` repository secret. Also supports `workflow_dispatch` for
+  manual redeploys.
+
+### Required GitHub secret
+
+`HF_TOKEN` (repo Settings → Secrets and variables → Actions → New repository
+secret). Scope: **Write**. Used only for `git push` to the Space remote.
+
+---
+
+## 8. End-to-end smoke test
+
+After any redeploy, verify in this order:
+
+```bash
+# 1. Backend liveness + readiness
+curl https://apoorvrajdev-image-captioning-api.hf.space/healthz
+
+# 2. Backend caption round-trip (replace path with any local JPG/PNG)
+curl -X POST https://apoorvrajdev-image-captioning-api.hf.space/v1/captions \
+  -F "image=@assets/sample.jpg"
+
+# 3. Frontend loads + status badge flips to green
+open https://image-captioning-system.vercel.app  # macOS
+# start https://image-captioning-system.vercel.app  # Windows
+
+# 4. Frontend ↔ backend integration (in the browser)
+#    Upload an image → expect a 200 caption response from /v1/captions
+#    DevTools → Network → check no CORS errors
+```
+
+---
+
+## 9. Known operational quirks
+
+- **Status badge briefly flips to "offline"** while a `/v1/captions` request is
+  in flight on the single uvicorn worker. The `/healthz` poll queues behind
+  inference and the frontend's 3 s timeout expires. The next 10 s poll
+  recovers. Cosmetic only — backend never actually goes down.
+- **First request after Space idle is slow** (~5–10 s extra). HF Spaces
+  sleep idle containers; the next call wakes the container, which then runs
+  the lifespan startup (snapshot_download cache hit + predictor rewarmup).
+- **Caption quality is gibberish** by design at `v1.0.0`. The shipped weights
+  are dev scaffolds from `scripts/bootstrap_dev_artifacts.py`. A real trained
+  checkpoint will be uploaded as `v2.0.0` and promoted via the Space variable
+  bump described in §3.
+
+---
+
+## 10. Rollback
+
+- **Bad code on the Space**: `git push space <known-good-sha>:main --force`
+  (from a local checkout). Space rebuilds from that SHA.
+- **Bad weights on the Hub**: bump the Space's
+  `BACKEND_WEIGHTS_HUB_REVISION` back to the previous tag (e.g. `v1.0.0`)
+  and save. Space restarts in ~30 s with the previous weights.
+- **Bad frontend on Vercel**: dashboard → Deployments → previous green
+  deployment → "Promote to Production" (one click, no rebuild).