docs: document the issue-to-deploy pipeline, staging, and test DB

- App/README.md: add FORGEJO_*/NEXT_PUBLIC_ENV_LABEL env vars and an
  'Operations & Automation' section pointing to automation/README.md.
- App/CLAUDE.md: complete the env var list (AZURE_AD_*, FORGEJO_*, GST_SERVICE_URL,
  NEXT_PUBLIC_ENV_LABEL) and note the prod-mirror test DB used by autofix/staging.
- .env.example: document NEXT_PUBLIC_ENV_LABEL.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

App/.env.example

@@ -54,3 +54,8 @@ GST_SERVICE_URL=http://localhost:3003
 FORGEJO_URL=https://git.pelagiamarine.com
 FORGEJO_REPO=shad0w/pelagia-portal
 FORGEJO_TOKEN=
+
+# ── Non-production banner ─────────────────────────────────────
+# When set, a fixed "internal dev / staging" banner is shown (EnvBanner).
+# Leave UNSET in production. Staging sets this automatically.
+# NEXT_PUBLIC_ENV_LABEL="INTERNAL DEV / STAGING - NOT PRODUCTION"

App/CLAUDE.md

@@ -95,7 +95,31 @@ NEXTAUTH_SECRET         # Required always
 NEXTAUTH_URL            # Required always (e.g., http://localhost:3000)
 DATABASE_URL            # PostgreSQL connection string
 
+AZURE_AD_CLIENT_ID, AZURE_AD_CLIENT_SECRET, AZURE_AD_TENANT_ID
+                        # Microsoft Entra SSO (prod). auth.ts reads them at module
+                        # load — set placeholders in non-SSO/dev envs so it boots.
+
 # Optional in dev (defaults to local storage + console email):
 R2_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, R2_BUCKET_NAME, R2_PUBLIC_URL
 RESEND_API_KEY, EMAIL_FROM, EMAIL_FROM_NAME
+
+# Report Issue button (lib/forgejo.ts); token needs write:issue:
+FORGEJO_URL, FORGEJO_REPO, FORGEJO_TOKEN
+
+GST_SERVICE_URL         # GstService microservice (defaults to localhost:3003)
+NEXT_PUBLIC_INVENTORY_ENABLED   # Inventory feature flag
+NEXT_PUBLIC_ENV_LABEL   # When set, shows a non-prod banner (EnvBanner). Leave unset in prod.
 ```
+
+### Operations & automation
+
+This repo runs a self-hosted issue-to-deploy pipeline on the `pms1` server (Forgejo +
+headless Claude Code). See [`../automation/README.md`](../automation/README.md). Relevant
+when working in this codebase:
+
+- The **Report Issue** button (portal header) files a Forgejo issue; a watcher triages it
+  and, for auto-fixable ones, implements a fix and opens a PR. Deploys are gated on a
+  human merging the PR and pushing a `vX.Y.Z` tag.
+- Automated fixes and the **staging** instance run against `pelagia_test`, a **daily mirror
+  of the production database**, in dev mode (console email, local storage). Migrations are
+  applied to it, so its schema tracks `master`. Never assume an empty DB — it holds prod-like data.

App/README.md

@@ -116,6 +116,15 @@ R2_PUBLIC_URL=https://<bucket>.<account>.r2.cloudflarestorage.com
 RESEND_API_KEY=re_<your key>
 EMAIL_FROM=noreply@yourdomain.com
 EMAIL_FROM_NAME="Pelagia Portal"
+
+# Report Issue button -> files a Forgejo issue (optional; token needs write:issue)
+FORGEJO_URL=https://git.example.com
+FORGEJO_REPO=owner/repo
+FORGEJO_TOKEN=<forgejo access token>
+
+# Non-prod banner (leave UNSET in production). When set, a fixed
+# "INTERNAL DEV / STAGING - NOT PRODUCTION" banner is shown.
+# NEXT_PUBLIC_ENV_LABEL="INTERNAL DEV / STAGING - NOT PRODUCTION"
 ```
 
 ### 2. Run database migrations
@@ -135,6 +144,27 @@ The app listens on port 3000 by default. Point your reverse proxy (nginx, Caddy,
 
 ---
 
+## Operations & Automation
+
+This repo carries its own self-hosted **issue-to-deploy pipeline** (Forgejo + Claude Code
+on the `pms1` server). The full design and runbook live in
+**[`../automation/README.md`](../automation/README.md)**. In short:
+
+- **Report Issue button** (portal header) files a Forgejo issue tagged `portal`.
+- A **watcher** triages each issue (Claude posts a requirements breakdown and routes it
+  to `claude-queue` or `interactive`), then for queued issues implements a fix and opens a PR.
+- Merging a PR and pushing a **release tag (`vX.Y.Z`)** triggers a Forgejo Actions runner
+  that deploys to production.
+- A **staging instance** (`automation/staging-up.sh`, pm2 `ppms-staging` on port 3200,
+  SSH-tunnel only) runs the latest `master` against a daily **prod-mirror test DB**
+  (`pelagia_test`) for smoke testing before tagging a release.
+
+Operational scripts live under [`../automation/`](../automation/): `claude-issue-watcher.sh`
+(watcher), `refresh-test-db.sh` (nightly test-DB refresh), `staging-up.sh` (staging),
+and `staging-tunnel.cmd` (Windows tunnel launcher).
+
+---
+
 ## Database Management
 
 | Command | Purpose |