diff --git a/k8s.md b/k8s.md
new file mode 100644
index 0000000..6440868
--- /dev/null
+++ b/k8s.md
@@ -0,0 +1,72 @@
+# Updating `.env` in Kubernetes
+
+Buzz Sheet uses the `buzz-sheet-env` Secret in the `buzz-sheet` namespace. The
+local `.env` file is ignored by Git and must never be committed.
+
+This repository uses hand-authored Kustomize manifests rather than a
+Kuber-managed Compose file, so synchronize `.env` with `kubectl`.
+
+## Push an updated `.env`
+
+From the repository root, confirm that `kubectl` is connected to the intended
+cluster:
+
+```bash
+cd /home/gunshiz/buzz-sheet
+kubectl config current-context
+kubectl get namespace buzz-sheet
+```
+
+Create or update the Secret without printing its values:
+
+```bash
+kubectl create secret generic buzz-sheet-env \
+  --namespace buzz-sheet \
+  --from-env-file=.env \
+  --dry-run=client \
+  --output=yaml | kubectl apply --filename=-
+```
+
+Running pods do not reload Secret values automatically. Restart both the web
+application and the outbox worker, then wait for each rollout:
+
+```bash
+kubectl rollout restart deployment/buzz-sheet \
+  --namespace buzz-sheet
+
+kubectl rollout restart deployment/buzz-sheet-worker \
+  --namespace buzz-sheet
+
+kubectl rollout status deployment/buzz-sheet \
+  --namespace buzz-sheet \
+  --timeout=10m
+
+kubectl rollout status deployment/buzz-sheet-worker \
+  --namespace buzz-sheet \
+  --timeout=10m
+```
+
+Verify PostgreSQL and Redis readiness, then inspect the application logs:
+
+```bash
+curl -fsS 'https://sheet.sudloh.com/api/health?ready=1'
+bun logs
+```
+
+The health response should report `"status":"ready"`, with both `database`
+and `redis` set to `"ok"`.
+
+## Important exceptions
+
+- Updating the Secret does not apply database migrations or seed data. If
+  `DATABASE_URL` now points to a new database, migrate and seed that database
+  before restarting the application.
+- Better Auth errors about missing database fields require a schema migration.
+  Pushing `.env` again will not fix them.
+- `NEXT_DEPLOYMENT_ID` is controlled by `buzz-sheet-config` and the immutable
+  image revision. Do not change it for an environment-only update.
+- `NEXT_SERVER_ACTIONS_ENCRYPTION_KEY` is embedded during `next build`. Rotating
+  it requires building and deploying a new image; restarting the existing image
+  is not sufficient.
+- If `BETTER_AUTH_URL` or the public hostname changes, update the Kubernetes
+  ingress, Cloudflare/DNS, and the Google OAuth callback URL as well.
diff --git a/package.json b/package.json
index 4ebc2a1..f3afdbc 100644
--- a/package.json
+++ b/package.json
@@ -11,6 +11,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
+    "logs": "kubectl logs --namespace buzz-sheet --selector 'app.kubernetes.io/name=buzz-sheet,app.kubernetes.io/component in (web,worker)' --all-containers=true --prefix=true --tail=100 --follow --max-log-requests=10",
     "db:generate": "drizzle-kit generate",
     "db:migrate": "bun scripts/migrate.ts",
     "db:studio": "drizzle-kit studio",