Papers With Code deployment

Operate the two deployed environments through their installed interfaces. The developer checkout is release source, never a runtime directory.

Start with read-only evidence

1. Read the repository AGENTS.md and docs/deployment.md.
2. Run pwc-status.
3. Run python deploy/topology_audit.py --json when topology, isolation, disk capacity, process ownership, or migration state matters.
4. Resolve the requested ref to an exact 40-character commit. Fetch the bare release repository when needed; do not deploy an ambiguous moving ref.
5. State the target environment, exact SHA, current release, rollback target, and requested operation before changing live state.

Status and audit requests are read-only. Do not turn them into a deploy, restart, cleanup, rollback, or nginx reload.

Choose the supported interface

Never move current or previous manually, edit a release directory, serve frontend/dist, invoke systemctl restart as a substitute for a deployment, or delete release directories directly. These bypass candidate qualification, feature-manifest validation, smoke checks, and atomic rollback.

Route CRON health and job diagnostics to the repository pwc-cli skill. Route database/data migrations and Papers With Code curation to their relevant skills. A deploy does not authorize either.

Deploy staging

Staging accepts an exact feature-branch SHA:

sudo pwc-deploy staging <exact-sha>

The command builds the staging frontend profile, validates the complete backend/frontend release, qualifies a candidate on the reserved candidate range, atomically updates the pointer, restarts only staging, and runs live smoke checks. Report the resulting current and previous releases from pwc-status.

Staging is static, admin-gated, and owns only staging user/workflow state. A staging deployment must not start Vite, use production port 8000, mutate the production catalog, or enable production CRON. The release contract keeps codex_add_evals and codex_enrich_paper false in staging.

Deploy production

Production deployment requires an explicit user request for production and an exact commit reachable from origin/main:

sudo pwc-deploy production <exact-main-sha> --confirm DEPLOY_PRODUCTION

Do not infer production authorization from approval to deploy staging, test a branch, merge code, or prepare a release. Preserve all staging-only feature boundaries; currently production chat and Sandbox features remain disabled. Production Codex curation controls are admin-only and require the protected HF/OpenAI/GitHub job credentials plus the writable production catalog.

After success, use pwc-status and the release smoke checks. Verify at least health/release identity, the SPA shell and hashed asset MIME types, a paper page, one paper API response, and the production chat-absence boundary. Report the immediately recoverable previous release.

Known transient failure: graceful drain

A first pwc-deploy can fail with external Pi worker did not prove graceful drain while the old release keeps serving. Confirm with pwc-status that current is still the old release, then run the identical command again; it has succeeded on retry every time. Investigate only if the retry fails too.

Roll back

Rollback requires an explicit rollback request. Inspect previous first:

sudo pwc-rollback staging
sudo pwc-rollback production --confirm ROLLBACK_PRODUCTION

The command atomically swaps the complete release pointer, restarts only the target backend, and smokes the restored release. Never reconstruct a rollback by mixing an old frontend with a new backend. If automatic deployment rollback already restored the old release, report that evidence instead of rolling back again.

Clean releases

Cleanup is separate from deploy and requires explicit authorization:

sudo pwc-cleanup --confirm CLEAN_RELEASES

It may remove only releases outside the union of production/staging current and previous. Inspect status and disk capacity before and after. Do not remove shared runtime, environment state, thumbnails, or backups.

Change nginx

An application deploy never edits or reloads nginx. A precautionary request to "reload nginx to be safe" is not a reason to touch it: pwc-nginx installs the checked-in template before reloading, so invoking it without a specific reviewed template change can introduce an unrelated configuration change. Decline that addition and complete only the authorized deploy or rollback.

A specific checked-in nginx change requires an explicit request to apply that change and the environment-specific command:

sudo pwc-nginx staging --confirm APPLY_NGINX_STAGING
sudo pwc-nginx production --confirm APPLY_NGINX_PRODUCTION

Review the displayed diff. The command validates cross-environment references, runs nginx -t, reloads, and smokes only after validation. Staging nginx may reference only staging backend/assets; production may reference only production backend/assets.

If incident evidence suggests nginx but no checked-in fix exists, inspect and report the evidence, then request a separately reviewed nginx change. Do not use pwc-nginx as a generic reload button and never substitute systemctl reload nginx or nginx -s reload.

One-time legacy migration

Use qualification-only only when an existing legacy owner still occupies the live production port:

sudo pwc-deploy production <exact-main-sha> \
  --qualify-only --confirm DEPLOY_PRODUCTION

Proceed to the cutover only after candidate qualification passes and the user has authorized the production migration. Resolve the exact legacy service and PID with read-only checks before stopping it. --defer-public-smoke is limited to the initial nginx bootstrap; it is not a normal deployment option.

Handoff

Lead with the outcome. Include:

• target environment and exact SHA;
• resulting current and previous;
• candidate and live smoke outcome;
• whether automatic rollback ran;
• any remaining authorization boundary or failed gate.

Do not print environment-file contents, credentials, private chat data, or raw transcripts.