Document admin upgrade package readiness

AGENTS.md

@@ -15,3 +15,5 @@ Before any Codex agent changes code, fixes bugs, reviews behavior, or answers im
 Do not start by broad-searching the repository when the memory and index documents already identify a likely file path. Use those documents as the first routing layer, then verify against the current source before editing.
 
 Every code adjustment, configuration change, workflow change, API change, UI change, and bug fix must include a documentation check before commit. If the change affects how future agents should locate code, diagnose bugs, call APIs, understand architecture, deploy, or verify behavior, update the matching document in `docs/codex-miaojing/` and, if needed, update `CODEX_MIAOJING_MEMORY.md` in the same commit. Do not leave documentation updates for a later session.
+
+All new development must remain compatible with the production admin upgrade path. Before finishing a change, decide whether it can be delivered as a hot update package or requires a cold update package through the admin console. Changes that touch `src`, server code, API routes, `package.json`, `pnpm-lock.yaml`, database schema, environment variables, PM2/runtime configuration, build scripts, backup/restore scripts, or generated server assets must be treated as cold-update candidates unless the upgrade runner explicitly supports them as safe hot-update payloads. Static/public asset-only changes may be hot-update candidates only after package preflight passes. Never finish deploy-facing work without considering backup, rollback, package preflight, and post-upgrade health checks.

CODEX_MIAOJING_MEMORY.md

@@ -16,6 +16,7 @@ This file is the required entry point for Codex work in this repository. Its job
 4. Verify the file paths against current source with `rg` or direct file reads.
 5. Make the smallest scoped code change that fits the existing architecture.
 6. For every adjustment or modification, check whether the change affects any project knowledge document. If it changes code location, UI behavior, API behavior, data shape, schema expectation, deployment flow, verification method, or bug-diagnosis path, update the corresponding document in the same commit.
+7. Before finishing new development, classify the production delivery path: admin-console hot update package or admin-console cold update package. Record upgrade, backup, rollback, and health-check implications when the change affects deployable behavior.
 
 ## Repository Identity
 
@@ -84,6 +85,7 @@ Before treating `ag-psd` or `@xyflow/react` as source bugs, run `corepack pnpm i
 - Do not change admin upgrade behavior without checking both `src/app/api/admin/upgrade/route.ts`, `scripts/admin-upgrade-runner.mjs`, `scripts/backup-create.sh`, and `scripts/backup-restore.sh`.
 - Do not change backup/import/restore behavior without preserving transaction boundaries, media restore behavior, dedupe rules, and pre-restore safety backups.
 - Do not change public content rendering without checking both backend persistence (`site-config`, `announcements`) and frontend consumers (`site-config-sync`, policy pages, footer, popup).
+- Do not treat a feature as complete until its production update-package path is clear. Hot-update candidates should be limited to payloads the upgrade runner accepts without restart, usually static/public assets. Changes to source code, API routes, server code, dependencies, DB schema or compatibility migrations, environment variables, PM2/runtime config, build scripts, backup/restore scripts, or deployment scripts are cold-update candidates and must preserve package preflight, backup, rollback, rebuild, restart, and `/api/health` verification.
 
 ## Documentation Maintenance Rule
 

docs/codex-miaojing/api-reference.md

@@ -131,7 +131,7 @@ All routes in this section require admin unless noted.
 | GET/PUT/POST | `/api/admin/email-settings` | `src/app/api/admin/email-settings/route.ts` | Read/update/test email settings. |
 | GET | `/api/admin/email-recipients` | `src/app/api/admin/email-recipients/route.ts` | Email recipient list. |
 | POST | `/api/admin/send-email` | `src/app/api/admin/send-email/route.ts` | Send admin email. |
-| GET/POST | `/api/admin/upgrade` | `src/app/api/admin/upgrade/route.ts` | Read upgrade runtime/status/history; upload/start dry run or upgrade package. |
+| GET/POST | `/api/admin/upgrade` | `src/app/api/admin/upgrade/route.ts` | Read upgrade runtime/status/history; upload/start dry run or upgrade package. New deployable work should be classified against this path: static/public asset-only payloads may be hot-update candidates after preflight, while source/API/server/dependency/schema/env/runtime/script changes are cold-update candidates. |
 
 ## Persistence Tables Mentioned By APIs
 

docs/codex-miaojing/architecture.md

@@ -221,6 +221,13 @@ Runtime:
 
 When changing deploy/upgrade behavior, validate package limits, disk checks, backup creation, rollback paths, restore safety backups, PM2 restart command, and health checks.
 
+All new development must be designed so the production server can be updated later through the admin console upgrade package flow. Classify every deployable change before handoff:
+
+- Hot update candidate: static/public asset-only payloads that the upgrade runner accepts without restart. Preflight must reject source, dependency, script, lockfile, secret, backup, storage, and runtime paths.
+- Cold update candidate: any change involving `src`, API routes, server code, dependencies, `package.json`, `pnpm-lock.yaml`, DB schema or compatibility migration behavior, environment variables, PM2/runtime config, build scripts, backup/restore scripts, deployment scripts, or generated server assets.
+
+Cold updates must preserve this safety chain: package preflight, disk checks, data backup, source snapshot, build/type verification, PM2 reload/restart, `/api/health`, and rollback through source restore plus backup restore when needed. When a feature introduces new persistent data, schema expectations, file-storage paths, background jobs, or environment variables, update the upgrade/package notes in this architecture document so future production packages can be prepared safely.
+
 ## Data Portability
 
 Admin data export/import is a portability layer, separate from the full tar backup scripts:
@@ -250,7 +257,9 @@ Use the narrowest useful check, then broaden as needed.
 | API route | `pnpm run ts-check`, route smoke with `curl` where runtime exists. |
 | UI workflow | `pnpm run ts-check`, `pnpm run build`, browser/manual or Playwright check if visual. |
 | Generation path | `pnpm run ts-check`, `pnpm run build`, job create/poll route check, storage result check. |
-| Deployment/upgrade | `pnpm run ts-check`, `pnpm run build`, package/upgrade dry run, PM2 reload, health checks. |
+| Static hot-update candidate | Admin upgrade dry run/preflight, verify runner accepts the payload without restart, then route/static asset smoke check. |
+| Cold-update candidate | `pnpm run ts-check`, `pnpm run build`, admin upgrade dry run/preflight, backup/rollback readiness, PM2 reload/restart, health checks. |
+| Deployment/upgrade tooling | `pnpm run ts-check`, `pnpm run build`, package/upgrade dry run, PM2 reload, health checks. |
 
 ## Known Risk Points
 

docs/codex-miaojing/bug-location-guide.md

@@ -112,6 +112,7 @@ Use this guide when the user reports behavior. Start from the symptom row, inspe
 | PM2 app not updated | `ecosystem.config.cjs`, `scripts/start.sh`, `scripts/deploy-or-upgrade.sh` | Process cwd, role ports, environment variables, `pm2 startOrReload ecosystem.config.cjs --update-env`. |
 | Production uses different checkout | `ecosystem.config.cjs`, PM2 process env/cwd | Always verify PM2 cwd before editing production. |
 | Upgrade package cleanup failed | `scripts/deploy-or-upgrade.sh`, `scripts/admin-upgrade-runner.mjs`, `src/app/api/admin/upgrade/route.ts` | Cleanup trap, backup paths, state dir, disk space guards. |
+| Unsure whether a change is safe for hot update or needs cold update | `scripts/admin-upgrade-runner.mjs`, `src/app/api/admin/upgrade/route.ts`, `src/components/admin/system-upgrade-tab.tsx`, `docs/codex-miaojing/architecture.md` | Treat source/API/server/dependency/schema/env/runtime/script changes as cold-update candidates. Hot updates should be static/public asset-only and must pass runner preflight without restart. Verify backup, rollback, package limits, disk checks, PM2 restart expectations, and `/api/health` before marking deploy-facing work complete. |
 
 ## Useful Search Patterns
 

docs/codex-miaojing/feature-code-index.md

@@ -166,5 +166,6 @@ Use this document to jump directly to code before broad searching.
 | Dev | `scripts/dev.sh` |
 | Deploy/upgrade | `scripts/deploy-or-upgrade.sh` |
 | Backup | `scripts/backup-create.sh`, `scripts/backup-list.sh`, `scripts/backup-restore.sh`. Restore uses `pg_restore --single-transaction`, validates archive/dump contents, atomically swaps local storage, and keeps a pre-restore safety backup. |
-| Admin upgrade runner | `scripts/admin-upgrade-runner.mjs` |
+| Admin upgrade API/UI | `src/app/api/admin/upgrade/route.ts`, `src/components/admin/system-upgrade-tab.tsx` |
+| Admin upgrade runner | `scripts/admin-upgrade-runner.mjs`. Use this when deciding whether a change can be packaged as a hot update or must be a cold update. Source/API/server/dependency/schema/env/runtime/script changes should be treated as cold-update candidates; static/public asset-only packages are hot-update candidates only if runner preflight accepts them without restart. |
 | Boundary checks | `scripts/check-boundaries.sh` |