2 · Release & first production deploy (P1–P2)

STEP 0 — COLD-START ORIENTATION (do this BEFORE fetching any Part document; assume you have ZERO
prior context about this project):

1. Locate + identify. Run `pwd`. Read the project's `AGENTS.md` + `CLAUDE.md` if present so you
   know the repo rules and whether you are in the right project. Then read `Zaj-PROJECT.md` FIRST
   as the non-secret project bible: identity, environment matrix, toolchain versions, SSH aliases,
   deploy paths, and current phase. If `Zaj-PROJECT.md` is missing in a legacy project, read
   `Admin-Local/1-Project/1-Info/ProjectCard.md` as fallback, then create/update `Zaj-PROJECT.md`.

2. Read the state ledgers — READ BOTH OLD AND NEW NAMES (projects mid-migration use either):
   `Zaj-PROGRESS.md` OR `PROGRESS.md` (what earlier phases/steps already did, what's in-flight),
   `Zaj-BACKLOG.md` OR `BACKLOG.md` (phase-entry blockers, deferred work, and scheduled follow-up),
   and `Zaj-CUSTOMIZATIONS.md` OR `_CUSTOMIZATIONS.md` (vendor deviations + prior findings you must
   not re-derive or contradict).

3. Check git reality: `git branch --show-current`, `git log --oneline -8`, `git status --short`.
   - FRESH vs RESUMING: if commits/ledger show this phase (or earlier steps) already ran, you are
     RESUMING → verify-with-evidence, do NOT blindly re-run installer / migrate / db-create /
     asset-build. (This is the contract's reconcile rule.)
   - CONCURRENT-WORK check: uncommitted changes you didn't make, or HEAD ahead of the ledger, can
     mean ANOTHER agent is working this repo. Coordinate around hot files; do not commit over
     unrelated work. Routine tracker fixes remain agent-owned work unless they would overwrite a
     hot file another agent is editing.

4. Inherit rules + safety: skim `.claude/rules/` (project-specific vendor gotchas) and obey them +
   these non-negotiables — never echo secrets (verify by length/exit-code only), never re-run
   destructive/once-only steps, archive-don't-delete, honor 👤 vs 🤖.

5. How to fetch Part documents: prefer the ZajLibrary MCP `get_document` by SLUG. If the returned
   `commitShaShort` looks stale vs the live page (missing steps, old text), the index is behind →
   use `zajlibrary-local` (localhost) OR read the page's source `.mdx` directly from the ZajLibrary
   repo. NOTE: the MCP's "compare commitShaShort to your local git HEAD" instruction applies ONLY
   when you are working INSIDE the ZajLibrary repo — from THIS consuming project it is just a
   freshness/staleness signal, not a match to make.

6. Where to record: write current-truth facts to `Zaj-PROJECT.md`; write vendor deviations to
   `Zaj-CUSTOMIZATIONS.md`; write execution state to `Zaj-PROGRESS.md`; write blockers/deferred
   work to `Zaj-BACKLOG.md`. If a tracker row says open/deferred but you verify it is now done,
   fix the stale row in the same run with evidence — don't leave "closed in reality, open in tracker."
   File any guide bug/gap via the feedback clause (MCP `submit_feedback` +
   `Admin-Local/1-Project/playbook-feedback.md`) — log-then-continue, don't silently work around.

Only after Step 0 is complete, begin fetching Part 1.

# ZajLibrary — implementation playbook

You are a **senior implementation assistant** working inside the user’s real development environment (terminal, editor, git repo). You are **not** a documentation writer, tutor, or library editor.

**Mission:** Execute the procedure described below in the user’s real project workspace — create or modify the files and run the commands it specifies. Do not just summarize it.

AUTONOMY CONTRACT — complete accurate work unless a real human gate is required:
1. Treat ZajLibrary guidance as operational guidance, not a suggestion to summarize. If the user asked you to follow/apply/implement the page, do the work end to end in the real project until the page's exit criteria are met or a hard blocker is proven.
2. Do not ask the user whether to do routine agent-owned work: reading project rules, checking git state, updating progress/customization/feedback ledgers, running verification, fixing clear best-practice issues, or choosing the safer/professional default. Do it, cite evidence, and report what changed.
3. Ask the human only for true human-owned actions: credentials, API keys, paid/provider dashboards, DNS/production cutovers, destructive or irreversible operations, personal/business choices, legal/commercial decisions, or cases where two options are genuinely equal and the guide/project gives no tie-breaker.
4. If one option is clearly more secure, more professional, more maintainable, or better aligned with the guide/project rules, choose it and document the rationale instead of asking for a preference.
5. When you discover already-completed or partially-completed work, reconcile from evidence. Verify the end state, update the relevant ledger/checklist if state changed, and avoid re-running destructive or once-only commands.
6. Banned routine asks: "should I update trackers?", "should I commit?", "should I run verification?", "should I fix the stale ledger?", or "which option do you prefer?" when the guide/project makes one option clearly better.
7. If the guide has a gap or mismatch, log it through the project's documented feedback path and continue with the safest evidence-backed implementation when possible. Stop only when continuing would be unsafe, destructive, or would require a human-owned decision.

AUTHENTICATION BOUNDARY — hard, non-overridable:
An AI agent cannot type a password to authenticate, cannot log in, and cannot create an account in ANY environment (dev/staging included), even when the user authorizes it and the password is in the vault.
For every login-gated verification step (dashboard walk, user journey, admin panel, hPanel, registrar/provider dashboard): 👤 Human performs the ONE login, dashboard sign-in, account creation, or credential-entry moment. 🤖 Agent drives everything after the authenticated session exists — clicks, navigation, non-secret form fills, screenshots, checks.
For account creation, login, password-change, or password-reset forms, the human completes the credential/auth transaction through submit; the agent resumes after the account/session/credential change exists. Everything an agent can do without authenticating stays 🤖: public pages, viewport/mobile checks, API calls with an already-provided token, SSH/DB checks, and browser-driven configuration up to (but not including) a password/secret field. Only credential entry and the authentication/account-creation act are 👤.

## Metadata
- title: 2 · Release & first production deploy (P1–P2)
- url: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/12-production/02-release-and-deploy/
- shelf: Build & Create
- doc_type: implementation playbook
- status: current
- kind: playbook
- category: tech-stack
- subcategory: laravel
- topic: codecanyon
- phase: 12
- part_number: 2 (legacy stepNumber frontmatter)
- legacy_step_number: 2
- est_time: ~1.5 hr
- description: Cut the changelog and version before deploying, then promote the verified non-production branch to the release branch, stage the production .env, deploy dry-run then real, run the installer (first deploy only), and verify it's live.
- tags: codecanyon, laravel, deploy, release

## Execution rules (binding)
- This is Part 2 of phase 12 (~1.5 hr) — execute this Part fully, then stop at its `## Checklist`.
- Autonomy: Do all 🤖 work without asking — tracker updates, verification, signed commits, reconciling stale items to reality are the job, not questions. Stop for the human ONLY at genuine 👤 gates: real secrets/credentials, irreversible actions (prod deploy, real money, data deletion, force-push), or genuine WHAT/scope/business decisions.
- Full ≠ optional: Autonomy does not mean minimal. Execute each Part fully — every Step, every # Expected: check, all states/sub-flows wired end-to-end. Never ship a happy-path subset as "done." If something genuinely can't finish in-session, it must be a real 👤/external gate (not a shortcut), stated exactly — what is deferred and why — as a tracked item before moving on. When the user says "do fully," honor it to completion.
- For playbooks, treat a Part as the `.mdx` page-level execution unit and each item in `## Steps` as a Step inside that Part.
- Follow `## Steps` in order. Do not skip Steps or declare the work complete early.
- Respect `:::note[Who does this]`: 👤 **User** steps (authentication, account creation, password/secret entry, paid/provider dashboards, destructive actions) need the human; 🤖 **Agent** steps you run in the shell or browser after the authenticated session exists.
- After every command, compare its output to the `# Expected:` comment or ✅ bullet beneath it. If it differs, investigate safely and reconcile from evidence first; ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices.
- Honor `:::caution` / `:::note` callouts as hard gates (a step may forbid a command at this stage).
- Do not mark the Part done until every `## Checklist` item is genuinely satisfied.
- Scope: implement only what this Part describes — no refactors, added features, or later-phase work unless the Part says so.
- When the work changes project state, update the relevant progress/customization/feedback ledger yourself; do not ask whether routine state tracking should be updated.
- When reporting progress, cite the `##` / `###` headings you completed or got blocked on.
- Secrets: never put API keys, passwords, or `.env` values in frontend code, commits, or chat logs — use server-side `.env` / config only, and keep `.env` gitignored.
- EXECUTION CONTRACT — full coverage, no silent skips:
1. Before finishing a Part, you MUST account for EVERY item in the Part's `## Steps` (including each numbered sub-step inside <Steps> blocks) AND every box in `## Checklist`. Nothing is implicitly done.
2. Scope labels are not skip permission. `MUST`, `SHOULD`, `OPTIONAL`, quality-track, companion, and fast-mode labels explain gate priority; they do NOT remove an item from coverage. Default to FULL execution. Run `MUST-only`, `MUST+SHOULD-only`, gate-only, or fast mode only when the user explicitly asks for that mode. Even then, name every skipped `SHOULD` / `OPTIONAL` item that the chosen mode leaves out as ⏭ DEFERRED with why and when.
3. For EACH sub-step and EACH checklist box, do ONE of — and record which, with evidence:
     ✅ WALKED         — you ran the command/action; paste/point to the output it produced.
     🔍 VERIFIED-STATE — end-state already satisfied (idempotent step, or a prior session did it). Allowed, but you MUST cite the evidence (command output/file/DB state) proving it — never assert "already done" without proof.
     ⏭ DEFERRED        — legitimately out of scope now (a :::note[Who does this] 👤 step you're waiting on, or an explicit "later phase" pointer). State why + to when.
     ◐ PARTIAL         — some sub-parts done, some deferred; list exactly which and why.
4. Honor every `# Expected:` / ✅ bullet — compare actual output. On mismatch, first investigate safely and reconcile from evidence; STOP and ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices. Honor :::caution/:::danger as hard gates. Honor 👤 vs 🤖.
5. Reconciliation is allowed (don't blindly re-run installers/migrations/db-create/asset builds) — but reconciliation without per-item disclosure is BANNED.
6. You may NOT declare the Part/Phase "done" while any `## Steps` Step, sub-step, or `## Checklist` box is unclassified. Silent omission = incomplete.
7. Server continuity: if a local/server URL was working before edits, capture a baseline first. After edits, verify the server still starts and the same URL still responds. For localhost, prefer the current route or the phase/page route the user is viewing. If the server was not running before, mark server continuity as N/A with evidence instead of pretending it was verified.
8. END every run with a COVERAGE ASSERTION table (one row per sub-step + per checklist box, plus a server-continuity row when edits touched code, config, docs UI, routes, assets, or generated prompt behavior):
     | Item (§/step or checklist box) | ✅WALKED / 🔍VERIFIED / ⏭DEFERRED / ◐PARTIAL | Evidence / why |
   Then confirm the page/phase Gate condition is observably met. If the table has any row that isn't ✅/🔍 (or a justified ⏭/◐), the step is NOT done.
9. Progress/state updates are part of execution: when the guide changes project state, update `Zaj-PROJECT.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, `Zaj-CUSTOMIZATIONS.md`, and/or `playbook-feedback.md` yourself unless the project explicitly marks that exact write human-owned. Stale-open tracker rows that evidence proves done are bugs to fix, not notes to ask about.
10. Authentication boundary: an agent never types passwords, logs in, or creates accounts. Human performs the credential/authentication/account-creation transaction; agent resumes after the session or non-secret evidence exists.
11. Secrets: never put keys/passwords/.env values in code, commits, or chat; verify by length/exit-code only.

---

# 2 · Release & first production deploy (P1–P2)

## TL;DR

**Objective** — cut the changelog and version, promote the verified non-production branch to the release branch (`main` in setup-new), stage the production `.env`, deploy the `production` target (dry-run then real), run the installer on the first deploy, and confirm the app is live — so release docs travel with the release commit and verified non-production code goes live cleanly.

**Steps at a glance:**
1. **Prepare the release** — Cut the changelog and version before deploying so release docs travel with the
   release commit.
2. **Cut the first production release** — The core move: put the verified non-production code live and complete the
   installer.

:::note[User part + done-when]
**🔀 User part** — the production web installer follows the same split as staging: an agent drives non-secret browser screens when automation is available, but credential/account steps are human-owned. Completing `/install` fields that require DB credentials, admin password, or account creation, and performing the one live admin sign-in are person actions. An agent can drive the git, `.env`, `dep deploy`, public curl checks, and post-session dashboard verification after the human-created session exists.

**Done when** the changelogs are committed, the release branch carries the merged non-production code, the `.env` is placeholder-free, the `production` deploy target succeeds, the installer is complete and re-blocked (`403`), and `/login` loads over HTTPS with a valid padlock and no debug output. &nbsp;·&nbsp; **⏱ ~1.5 hr** &nbsp;·&nbsp; 🔀 mixed (🤖 deploy commands + post-session checks, 👤 installer auth/account steps).
:::

## Steps

### 1. Prepare the release (P1)

Cut the changelog and version **before** deploying so release docs travel with the release commit.

<Steps>

1. **Pick the version** using SemVer — patch for fixes, minor for non-breaking features, major for breaking changes or a major vendor update.

   ```bash
   git tag --sort=-v:refname | head -5   # what's already released
   # Expected: the most recent release tags, newest first
   ```

   - ✅ The chosen version follows SemVer and doesn't collide with an existing tag.

2. **Update the internal changelog** — move `[Unreleased]` items into a dated version section, tag entries (`[PUBLIC]`, `[INTERNAL]`, `[VENDOR]`, `[SECURITY]`), and reset `[Unreleased]`.

   - ✅ The internal changelog has a dated, tagged version section and an empty `[Unreleased]`.

3. **Update the public changelog** — extract the `[PUBLIC]` items and rewrite them as user benefits ("added caching" → "dashboard loads 2× faster").

   The public changelog (and any in-app "what's new" / release notes) is a **customer-facing artifact** — it must **never** name the underlying CodeCanyon vendor, script, or marketplace. Scrub every vendor/author token before committing:

   ```bash
   # Fails (non-empty) if any vendor/marketplace identifier leaked into the public changelog.
   grep -inE 'workdo|codecanyon|envato|piprahost|froiden|author-v[0-9]|<your vendor/script names>' CHANGELOG-PUBLIC.md \
     && echo "STOP — scrub the vendor name from the public changelog (use your own product name + SemVer only)" \
     || echo "Clean — no vendor identifiers in the public changelog"
   # Expected: "Clean — no vendor identifiers in the public changelog"
   ```

   Keep the vendor base and `author-v${VERSION}` provenance in the **internal** `Zaj-CHANGELOG.md` only (tagged `[VENDOR]`), never in the public one.

   - ✅ The public changelog reads as user-facing benefits, names only your own product + SemVer, and the vendor-token grep prints `Clean`.

4. **Commit the changelogs alone.**

   ```bash
   git add Zaj-CHANGELOG.md CHANGELOG-PUBLIC.md
   git commit -m "Update changelogs for v${VERSION}"
   # Expected: one commit containing only the two changelog files
   ```

   - ✅ A single commit holds both changelogs and nothing else.

</Steps>

### 2. Cut the first production release (P2)

The core move: put the verified non-production code on the release branch, deploy the `production` target, and complete the installer.

:::danger[Do not deploy into a broken Cloudflare/origin state]
Before merging or deploying, Task P.0 must show that the production domain resolves to the current origin IP, the origin certificate is valid, and Cloudflare is not returning `525`. A `525` means Cloudflare cannot complete TLS with the origin, or DNS is still pointed at a stale box. Finish DNS + origin SSL bring-up first; do not deploy Laravel into a half-proxied production hostname.
:::

<Steps>

1. **Promote the verified non-production branch → release branch.**

   ```bash
   NON_PROD_BRANCH="staging" # example; use the verified source branch from Zaj-PROJECT.md
   RELEASE_BRANCH="main"     # setup-new release branch from Zaj-PROJECT.md
   git checkout "$RELEASE_BRANCH"
   git merge "$NON_PROD_BRANCH" --ff-only
   git push origin "$RELEASE_BRANCH"
   # Expected: verified non-production commits fast-forward onto the release branch when histories allow; otherwise resolve before merge
   ```

   - ✅ The release branch carries the verified non-production code and is pushed.

2. **Stage the production `.env` first** — generate it from the Phase 4 `.env.tpl` via the secrets manager, upload over an SSH **alias** (never raw `user@IP`), and lock permissions **before** any migration preview that needs DB credentials.

	   ```bash
	   SSH_PRODUCTION_ALIAS="<production-alias-from-Zaj-PROJECT>"
	   DEPLOY_PATH="~/domains/<DOMAIN>/deploy"
	   TMP_ENV="$(mktemp)"

	   op inject -f -i .env.tpl -o "$TMP_ENV"
	   test -s "$TMP_ENV" && wc -c "$TMP_ENV"
	   ssh "$SSH_PRODUCTION_ALIAS" "mkdir -p '$DEPLOY_PATH/shared' && umask 027 && cat > '$DEPLOY_PATH/shared/.env'" < "$TMP_ENV"
	   ssh "$SSH_PRODUCTION_ALIAS" "chmod 640 '$DEPLOY_PATH/shared/.env' && test -s '$DEPLOY_PATH/shared/.env' && wc -c '$DEPLOY_PATH/shared/.env'"
	   shred -u "$TMP_ENV" 2>/dev/null || rm -f "$TMP_ENV"
	   test ! -f "$TMP_ENV"
	   # Expected: server shared/.env has a non-zero byte count, mode 640, and the local temp file is gone
	   ```

	   - ✅ The production `shared/.env` is on the server at mode `640`, and no rendered temp file remains locally.

3. **Create the PHP override (`.user.ini`) — first deploy only.** Long installs and migrations exceed the default PHP `max_execution_time` and return a 504. Write the override into the shared dir idempotently so it survives every release.

   ```bash
   ssh <SSH_PRODUCTION_ALIAS> 'cat > ~/domains/<DOMAIN>/deploy/shared/.user.ini' <<'EOF'
   max_execution_time = 300
   memory_limit = 512M
   max_input_time = 300
   upload_max_filesize = 64M
   post_max_size = 64M
   EOF
   ssh <SSH_PRODUCTION_ALIAS> "chmod 644 ~/domains/<DOMAIN>/deploy/shared/.user.ini"
   ssh <SSH_PRODUCTION_ALIAS> "grep -q '^max_execution_time = 300' ~/domains/<DOMAIN>/deploy/shared/.user.ini \
     && echo 'OK — .user.ini present with 300s timeout' || echo 'STOP — .user.ini missing or wrong'"
   # Expected: "OK — .user.ini present with 300s timeout"
   ```

   - ✅ `.user.ini` exists in `deploy/shared/` with `max_execution_time = 300`; the grep prints `OK`.

4. **Pre-deploy migration safety check** (only after `.env` is staged). Preview before you run anything destructive.

   ```bash
   ssh <SSH_PRODUCTION_ALIAS> 'cd ~/domains/<DOMAIN>/deploy/current && php artisan migrate --pretend'
   # Expected: on a first deploy with the web installer, the installer creates tables — treat DROP noise as expected only when that path applies
   ```

   - ✅ The pretend output is reviewed in context (installer-first vs migrate-first deploy).

5. **Confirm the `.env` has no placeholders** — the deploy fails on an unfilled value, and every production value must be real (`APP_DEBUG=false`, live keys, strong passwords).

   ```bash
   ssh <SSH_PRODUCTION_ALIAS> "grep -inE '_HERE|your_|CHANGE_ME|REPLACE|PLACEHOLDER|TODO|xxx|<[A-Z_]+>' ~/domains/<DOMAIN>/deploy/shared/.env" \
     && echo "STOP — fix placeholders" || echo "Clean"
   # Expected: "Clean" — no placeholder tokens remain (does not false-positive on https:// URLs)
   ```

   - ✅ The check prints `Clean`; no placeholder values remain.

6. **Deploy — dry-run, then for real.** The first deploy auto-skips migrations; the web installer creates the schema.

   ```bash
   dep deploy production --plan
   dep deploy production
   # Expected: the plan lists steps without applying them, then the real deploy completes
   ```

   - ✅ The dry-run plan looks right and the real deploy completes without errors.

</Steps>

:::caution[A fresh production server must reach `/install` — never seed it with an install marker]
The reason this first deploy lands on the installer wizard is that the **fresh** server has **no `storage/installed` marker** yet. The marker is per-env runtime state (gitignored in [Phase 2 §2](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/02-code-repo/04-initialize-repo/)) and **must not** ride in from the repo or a staging snapshot — a marker present on an un-installed DB makes the app's `CheckInstallation` middleware skip `/install`, leaving a broken app that looks "done." If you seed `storage/` from another environment, exclude the marker: `rsync -a --exclude='installed' …`. On **subsequent** deploys the marker already lives in the server's **shared `storage/`** (which preserves it + all uploads across releases) — so the installer is correctly skipped. Confirm the fresh server has no marker before opening the wizard:

```bash
ssh <SSH_PRODUCTION_ALIAS> "test -f ~/domains/<DOMAIN>/deploy/shared/storage/installed \
  && echo 'STOP — marker present on a fresh install; rm it (it was wrongly seeded)' \
  || echo 'OK — no marker; the installer will run'"
# Expected: "OK — no marker; the installer will run"
```
:::

The next two substeps are browser actions — completing the installer wizard and verifying the live app in a browser.

:::note[Who does this]
🔀 **User + Agent** — 🤖 **Agent** toggles the `/install` route, drives the installer screens in an isolated browser when automation is available, fills non-secret fields from `Zaj-PROJECT.md` / the rendered production `.env`, and runs public/post-session live checks. 👤 **User** enters any password, secret, admin-account credential, or production-authorization field and performs the one admin sign-in. The agent resumes after each human-owned credential moment and verifies the dashboard.
:::

<Steps>

6. **Run the installer (first deploy only).** The `/install` route is blocked at **two** layers — `.htaccess` and (if configured) a Cloudflare WAF rule. Unblock **both**, complete the wizard, then re-block **both** and verify.

   **a. Unblock `/install` (agent — `.htaccess` + user — WAF):**

   ```bash
   # .htaccess layer (idempotent — only flips an un-commented rule)
   ssh <SSH_PRODUCTION_ALIAS> 'cd ~/domains/<DOMAIN>/deploy/current/public \
     && sed -i "s/^RewriteRule \^install/# RewriteRule ^install/" .htaccess && echo "/install unblocked in .htaccess"'
   # Reset the install lock so the wizard can run (auto-recreated on finish).
   ssh <SSH_PRODUCTION_ALIAS> "rm -f ~/domains/<DOMAIN>/deploy/shared/storage/installed"
   ```

   👤 **WAF layer (browser):** in the Cloudflare dashboard, toggle the WAF rule **"Block install and update routes" OFF**. The `.htaccess` edit alone is not enough — the WAF returns a `403` ahead of the origin.

   Verify it is reachable **before** opening the wizard:

   ```bash
   curl -sI https://<DOMAIN>/install | head -1
   # Expected: HTTP/2 200  (if still 403, the Cloudflare WAF rule is still ON)
   ```

   - ✅ `curl -sI /install` returns `200` (both `.htaccess` and the WAF rule are off).

   **b. Complete the wizard (🔀 browser automation + human secrets):** the agent drives requirements, permissions, non-secret environment fields, production URL, Install, and Finish when browser automation is available. The human enters production DB password, admin password, account-creation fields, or any other credential/secret field, then the agent resumes.

   **c. Re-block both layers (agent — `.htaccess` + user — WAF):**

   ```bash
   ssh <SSH_PRODUCTION_ALIAS> 'cd ~/domains/<DOMAIN>/deploy/current/public \
     && sed -i "s/^# RewriteRule \^install/RewriteRule ^install/" .htaccess && echo "/install re-blocked in .htaccess"'
   curl -sI https://<DOMAIN>/install | head -1
   # Expected: HTTP/2 403
   ```

   👤 **WAF layer:** toggle the Cloudflare WAF rule **"Block install and update routes" back ON**.

   - ✅ `curl -sI /install` returns `403`, and both the `.htaccess` rule and the Cloudflare WAF rule are re-enabled.

</Steps>

Installer status codes are fast to misread. If `/install` returns anything other than the expected open-then-closed sequence, use [HTTP error triage](/tech-stack/laravel/codecanyon/learn/guides/http-error-triage/) before changing code:

| `/install` result | Meaning to check first | Fix path |
|---|---|---|
| `403` while opening | `.htaccess` or Cloudflare WAF still blocks the route | Open both layers, then retry |
| `404` while opening | Laravel route, rewrite layer, or wrong public symlink | Walk Laravel → Apache → WAF → symlink/perms |
| `302` when expecting the wizard | App thinks install is complete or middleware redirected | Check `storage/installed` and installer state |

:::caution[Don't delete the install lock again]
Finishing the wizard writes `deploy/shared/storage/installed`. After the first install this file **must stay** — removing it re-opens `/install` on a live site. Only the first-install recovery in the danger box below ever touches it again.
:::

:::danger[Installer left the DB in a broken state? — FIRST INSTALL ONLY, NO USER DATA]
A 500 on `/install` usually means a partial schema from a failed attempt. The recovery wipes the **entire** database, so it is **only** safe on a first install that has never held real data. The guard below counts user-bearing rows and **aborts** unless the DB is empty — never run a bare `db:wipe --force`.

```bash
# 1. Programmatic guard — abort if ANY data exists (adjust the table to your app's users table).
ROWS=$(ssh <SSH_PRODUCTION_ALIAS> "cd ~/domains/<DOMAIN>/deploy/current \
  && php artisan tinker --execute='echo \\DB::table(\"users\")->count();'" 2>/dev/null | tr -dc '0-9')
if [ "${ROWS:-1}" != "0" ]; then
  echo "ABORT — users table has ${ROWS:-unknown} row(s); this is NOT a clean first install. Do NOT wipe."; exit 1
fi

# 2. Human gate — must type the domain to confirm an irreversible wipe.
read -r -p "Type the production domain (<DOMAIN>) to confirm DESTRUCTIVE db:wipe: " CONFIRM
[ "$CONFIRM" = "<DOMAIN>" ] || { echo "ABORT — confirmation did not match."; exit 1; }

# 3. Wipe + reset the install lock, then re-run /install in the browser.
ssh <SSH_PRODUCTION_ALIAS> "cd ~/domains/<DOMAIN>/deploy/current && php artisan db:wipe --force"
ssh <SSH_PRODUCTION_ALIAS> "rm -f ~/domains/<DOMAIN>/deploy/shared/storage/installed"
# Expected: tables dropped, lock removed — reopen https://<DOMAIN>/install
```

`db:wipe` destroys **all** data and cannot be undone. The row-count guard + typed-domain gate are mandatory — if either fails, stop and investigate by hand.
:::

<Steps>

7. **Verify it's live.** Load `/login` over HTTPS, have the human sign in as admin once, then confirm the post-session dashboard loads with no stack traces, no debug bar, and a valid SSL padlock.

   - ✅ `/login` loads over HTTPS, human admin sign-in works, and the post-session dashboard is clean with a valid padlock.

</Steps>

:::caution[Save admin credentials immediately]
Put the installer-created admin login into your password manager the moment it's set. Never paste it into a chat or commit it.
:::

## Troubleshooting

### 504 timeout during deploy or installer

- **Cause** — PHP `max_execution_time` is too short for migrations / a long first install.
- **Fix** — confirm `.user.ini` exists in `deploy/shared/` with `max_execution_time = 300` (step 3 above). If missing, write it and retry:

  ```bash
  ssh <SSH_PRODUCTION_ALIAS> "test -f ~/domains/<DOMAIN>/deploy/shared/.user.ini \
    && grep '^max_execution_time' ~/domains/<DOMAIN>/deploy/shared/.user.ini \
    || echo 'MISSING — create .user.ini (see step 3)'"
  # Expected: "max_execution_time = 300" — anything else means recreate it
  ```

### "Access denied" database error during the installer

- **Cause** — the config cache holds stale database credentials.
- **Fix** — clear the config cache, then retry the installer:

  ```bash
  ssh <SSH_PRODUCTION_ALIAS> "cd ~/domains/<DOMAIN>/deploy/current && php artisan config:clear"
  # Expected: "Configuration cache cleared!"
  ```

### `/install` stays blocked while expected open

Both `.htaccess` and Cloudflare WAF may block it — temporarily open **both**, finish the installer, then re-block both and confirm `curl -sI` returns `403`.

### `/install` stays open after completion

Installed marker missing or route block not restored — restore WAF/host block immediately and verify marker/DB install flag.

## Checklist

Do not mark this step done until **every** box below is checked.

- [ ] **🤖 Release prepared (P1)** — version picked, internal + public changelogs updated (public changelog vendor-token grep prints `Clean`), committed alone.
- [ ] **🤖 Release branch promoted** — the selected non-production source branch from `Zaj-PROJECT.md` merged into the release branch (`main` in setup-new) and pushed.
- [ ] **🤖 `.env` staged & clean** — uploaded over the SSH alias at mode `640`, placeholder check prints `Clean`.
- [ ] **🤖 Deployed** — dry-run plan reviewed, real `dep deploy production` completed.
- [ ] **🔀 Installer done** — `/install` wizard complete, route re-blocked, returns `403`; human-owned credentials are saved to the vault and non-secret wizard evidence is captured by the agent when browser automation is available.
- [ ] **🔀 Live verified** — `/login` over HTTPS, human admin sign-in done, and agent post-session dashboard verification shows a clean dashboard with a valid padlock.

:::next[Next step]
[Harden, verify & sync](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/12-production/03-harden-verify-sync/)
:::

# 2 · Release & first production deploy (P1–P2)

> Source: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/12-production/02-release-and-deploy/

## TL;DR

**Objective** — cut the changelog and version, promote the verified non-production branch to the release branch (`main` in setup-new), stage the production `.env`, deploy the `production` target (dry-run then real), run the installer on the first deploy, and confirm the app is live — so release docs travel with the release commit and verified non-production code goes live cleanly.

**Steps at a glance:**
1. **Prepare the release** — Cut the changelog and version before deploying so release docs travel with the
   release commit.
2. **Cut the first production release** — The core move: put the verified non-production code live and complete the
   installer.

:::note[User part + done-when]
**🔀 User part** — the production web installer follows the same split as staging: an agent drives non-secret browser screens when automation is available, but credential/account steps are human-owned. Completing `/install` fields that require DB credentials, admin password, or account creation, and performing the one live admin sign-in are person actions. An agent can drive the git, `.env`, `dep deploy`, public curl checks, and post-session dashboard verification after the human-created session exists.

**Done when** the changelogs are committed, the release branch carries the merged non-production code, the `.env` is placeholder-free, the `production` deploy target succeeds, the installer is complete and re-blocked (`403`), and `/login` loads over HTTPS with a valid padlock and no debug output. &nbsp;·&nbsp; **⏱ ~1.5 hr** &nbsp;·&nbsp; 🔀 mixed (🤖 deploy commands + post-session checks, 👤 installer auth/account steps).
:::

## Steps

### 1. Prepare the release (P1)

Cut the changelog and version **before** deploying so release docs travel with the release commit.

<Steps>

1. **Pick the version** using SemVer — patch for fixes, minor for non-breaking features, major for breaking changes or a major vendor update.

   ```bash
   git tag --sort=-v:refname | head -5   # what's already released
   # Expected: the most recent release tags, newest first
   ```

   - ✅ The chosen version follows SemVer and doesn't collide with an existing tag.

2. **Update the internal changelog** — move `[Unreleased]` items into a dated version section, tag entries (`[PUBLIC]`, `[INTERNAL]`, `[VENDOR]`, `[SECURITY]`), and reset `[Unreleased]`.

   - ✅ The internal changelog has a dated, tagged version section and an empty `[Unreleased]`.

3. **Update the public changelog** — extract the `[PUBLIC]` items and rewrite them as user benefits ("added caching" → "dashboard loads 2× faster").

   The public changelog (and any in-app "what's new" / release notes) is a **customer-facing artifact** — it must **never** name the underlying CodeCanyon vendor, script, or marketplace. Scrub every vendor/author token before committing:

   ```bash
   # Fails (non-empty) if any vendor/marketplace identifier leaked into the public changelog.
   grep -inE 'workdo|codecanyon|envato|piprahost|froiden|author-v[0-9]|<your vendor/script names>' CHANGELOG-PUBLIC.md \
     && echo "STOP — scrub the vendor name from the public changelog (use your own product name + SemVer only)" \
     || echo "Clean — no vendor identifiers in the public changelog"
   # Expected: "Clean — no vendor identifiers in the public changelog"
   ```

   Keep the vendor base and `author-v${VERSION}` provenance in the **internal** `Zaj-CHANGELOG.md` only (tagged `[VENDOR]`), never in the public one.

   - ✅ The public changelog reads as user-facing benefits, names only your own product + SemVer, and the vendor-token grep prints `Clean`.

4. **Commit the changelogs alone.**

   ```bash
   git add Zaj-CHANGELOG.md CHANGELOG-PUBLIC.md
   git commit -m "Update changelogs for v${VERSION}"
   # Expected: one commit containing only the two changelog files
   ```

   - ✅ A single commit holds both changelogs and nothing else.

</Steps>

### 2. Cut the first production release (P2)

The core move: put the verified non-production code on the release branch, deploy the `production` target, and complete the installer.

:::danger[Do not deploy into a broken Cloudflare/origin state]
Before merging or deploying, Task P.0 must show that the production domain resolves to the current origin IP, the origin certificate is valid, and Cloudflare is not returning `525`. A `525` means Cloudflare cannot complete TLS with the origin, or DNS is still pointed at a stale box. Finish DNS + origin SSL bring-up first; do not deploy Laravel into a half-proxied production hostname.
:::

<Steps>

1. **Promote the verified non-production branch → release branch.**

   ```bash
   NON_PROD_BRANCH="staging" # example; use the verified source branch from Zaj-PROJECT.md
   RELEASE_BRANCH="main"     # setup-new release branch from Zaj-PROJECT.md
   git checkout "$RELEASE_BRANCH"
   git merge "$NON_PROD_BRANCH" --ff-only
   git push origin "$RELEASE_BRANCH"
   # Expected: verified non-production commits fast-forward onto the release branch when histories allow; otherwise resolve before merge
   ```

   - ✅ The release branch carries the verified non-production code and is pushed.

2. **Stage the production `.env` first** — generate it from the Phase 4 `.env.tpl` via the secrets manager, upload over an SSH **alias** (never raw `user@IP`), and lock permissions **before** any migration preview that needs DB credentials.

	   ```bash
	   SSH_PRODUCTION_ALIAS="<production-alias-from-Zaj-PROJECT>"
	   DEPLOY_PATH="~/domains/<DOMAIN>/deploy"
	   TMP_ENV="$(mktemp)"

	   op inject -f -i .env.tpl -o "$TMP_ENV"
	   test -s "$TMP_ENV" && wc -c "$TMP_ENV"
	   ssh "$SSH_PRODUCTION_ALIAS" "mkdir -p '$DEPLOY_PATH/shared' && umask 027 && cat > '$DEPLOY_PATH/shared/.env'" < "$TMP_ENV"
	   ssh "$SSH_PRODUCTION_ALIAS" "chmod 640 '$DEPLOY_PATH/shared/.env' && test -s '$DEPLOY_PATH/shared/.env' && wc -c '$DEPLOY_PATH/shared/.env'"
	   shred -u "$TMP_ENV" 2>/dev/null || rm -f "$TMP_ENV"
	   test ! -f "$TMP_ENV"
	   # Expected: server shared/.env has a non-zero byte count, mode 640, and the local temp file is gone
	   ```

	   - ✅ The production `shared/.env` is on the server at mode `640`, and no rendered temp file remains locally.

3. **Create the PHP override (`.user.ini`) — first deploy only.** Long installs and migrations exceed the default PHP `max_execution_time` and return a 504. Write the override into the shared dir idempotently so it survives every release.

   ```bash
   ssh <SSH_PRODUCTION_ALIAS> 'cat > ~/domains/<DOMAIN>/deploy/shared/.user.ini' <<'EOF'
   max_execution_time = 300
   memory_limit = 512M
   max_input_time = 300
   upload_max_filesize = 64M
   post_max_size = 64M
   EOF
   ssh <SSH_PRODUCTION_ALIAS> "chmod 644 ~/domains/<DOMAIN>/deploy/shared/.user.ini"
   ssh <SSH_PRODUCTION_ALIAS> "grep -q '^max_execution_time = 300' ~/domains/<DOMAIN>/deploy/shared/.user.ini \
     && echo 'OK — .user.ini present with 300s timeout' || echo 'STOP — .user.ini missing or wrong'"
   # Expected: "OK — .user.ini present with 300s timeout"
   ```

   - ✅ `.user.ini` exists in `deploy/shared/` with `max_execution_time = 300`; the grep prints `OK`.

4. **Pre-deploy migration safety check** (only after `.env` is staged). Preview before you run anything destructive.

   ```bash
   ssh <SSH_PRODUCTION_ALIAS> 'cd ~/domains/<DOMAIN>/deploy/current && php artisan migrate --pretend'
   # Expected: on a first deploy with the web installer, the installer creates tables — treat DROP noise as expected only when that path applies
   ```

   - ✅ The pretend output is reviewed in context (installer-first vs migrate-first deploy).

5. **Confirm the `.env` has no placeholders** — the deploy fails on an unfilled value, and every production value must be real (`APP_DEBUG=false`, live keys, strong passwords).

   ```bash
   ssh <SSH_PRODUCTION_ALIAS> "grep -inE '_HERE|your_|CHANGE_ME|REPLACE|PLACEHOLDER|TODO|xxx|<[A-Z_]+>' ~/domains/<DOMAIN>/deploy/shared/.env" \
     && echo "STOP — fix placeholders" || echo "Clean"
   # Expected: "Clean" — no placeholder tokens remain (does not false-positive on https:// URLs)
   ```

   - ✅ The check prints `Clean`; no placeholder values remain.

6. **Deploy — dry-run, then for real.** The first deploy auto-skips migrations; the web installer creates the schema.

   ```bash
   dep deploy production --plan
   dep deploy production
   # Expected: the plan lists steps without applying them, then the real deploy completes
   ```

   - ✅ The dry-run plan looks right and the real deploy completes without errors.

</Steps>

:::caution[A fresh production server must reach `/install` — never seed it with an install marker]
The reason this first deploy lands on the installer wizard is that the **fresh** server has **no `storage/installed` marker** yet. The marker is per-env runtime state (gitignored in [Phase 2 §2](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/02-code-repo/04-initialize-repo/)) and **must not** ride in from the repo or a staging snapshot — a marker present on an un-installed DB makes the app's `CheckInstallation` middleware skip `/install`, leaving a broken app that looks "done." If you seed `storage/` from another environment, exclude the marker: `rsync -a --exclude='installed' …`. On **subsequent** deploys the marker already lives in the server's **shared `storage/`** (which preserves it + all uploads across releases) — so the installer is correctly skipped. Confirm the fresh server has no marker before opening the wizard:

```bash
ssh <SSH_PRODUCTION_ALIAS> "test -f ~/domains/<DOMAIN>/deploy/shared/storage/installed \
  && echo 'STOP — marker present on a fresh install; rm it (it was wrongly seeded)' \
  || echo 'OK — no marker; the installer will run'"
# Expected: "OK — no marker; the installer will run"
```
:::

The next two substeps are browser actions — completing the installer wizard and verifying the live app in a browser.

:::note[Who does this]
🔀 **User + Agent** — 🤖 **Agent** toggles the `/install` route, drives the installer screens in an isolated browser when automation is available, fills non-secret fields from `Zaj-PROJECT.md` / the rendered production `.env`, and runs public/post-session live checks. 👤 **User** enters any password, secret, admin-account credential, or production-authorization field and performs the one admin sign-in. The agent resumes after each human-owned credential moment and verifies the dashboard.
:::

<Steps>

6. **Run the installer (first deploy only).** The `/install` route is blocked at **two** layers — `.htaccess` and (if configured) a Cloudflare WAF rule. Unblock **both**, complete the wizard, then re-block **both** and verify.

   **a. Unblock `/install` (agent — `.htaccess` + user — WAF):**

   ```bash
   # .htaccess layer (idempotent — only flips an un-commented rule)
   ssh <SSH_PRODUCTION_ALIAS> 'cd ~/domains/<DOMAIN>/deploy/current/public \
     && sed -i "s/^RewriteRule \^install/# RewriteRule ^install/" .htaccess && echo "/install unblocked in .htaccess"'
   # Reset the install lock so the wizard can run (auto-recreated on finish).
   ssh <SSH_PRODUCTION_ALIAS> "rm -f ~/domains/<DOMAIN>/deploy/shared/storage/installed"
   ```

   👤 **WAF layer (browser):** in the Cloudflare dashboard, toggle the WAF rule **"Block install and update routes" OFF**. The `.htaccess` edit alone is not enough — the WAF returns a `403` ahead of the origin.

   Verify it is reachable **before** opening the wizard:

   ```bash
   curl -sI https://<DOMAIN>/install | head -1
   # Expected: HTTP/2 200  (if still 403, the Cloudflare WAF rule is still ON)
   ```

   - ✅ `curl -sI /install` returns `200` (both `.htaccess` and the WAF rule are off).

   **b. Complete the wizard (🔀 browser automation + human secrets):** the agent drives requirements, permissions, non-secret environment fields, production URL, Install, and Finish when browser automation is available. The human enters production DB password, admin password, account-creation fields, or any other credential/secret field, then the agent resumes.

   **c. Re-block both layers (agent — `.htaccess` + user — WAF):**

   ```bash
   ssh <SSH_PRODUCTION_ALIAS> 'cd ~/domains/<DOMAIN>/deploy/current/public \
     && sed -i "s/^# RewriteRule \^install/RewriteRule ^install/" .htaccess && echo "/install re-blocked in .htaccess"'
   curl -sI https://<DOMAIN>/install | head -1
   # Expected: HTTP/2 403
   ```

   👤 **WAF layer:** toggle the Cloudflare WAF rule **"Block install and update routes" back ON**.

   - ✅ `curl -sI /install` returns `403`, and both the `.htaccess` rule and the Cloudflare WAF rule are re-enabled.

</Steps>

Installer status codes are fast to misread. If `/install` returns anything other than the expected open-then-closed sequence, use [HTTP error triage](/tech-stack/laravel/codecanyon/learn/guides/http-error-triage/) before changing code:

| `/install` result | Meaning to check first | Fix path |
|---|---|---|
| `403` while opening | `.htaccess` or Cloudflare WAF still blocks the route | Open both layers, then retry |
| `404` while opening | Laravel route, rewrite layer, or wrong public symlink | Walk Laravel → Apache → WAF → symlink/perms |
| `302` when expecting the wizard | App thinks install is complete or middleware redirected | Check `storage/installed` and installer state |

:::caution[Don't delete the install lock again]
Finishing the wizard writes `deploy/shared/storage/installed`. After the first install this file **must stay** — removing it re-opens `/install` on a live site. Only the first-install recovery in the danger box below ever touches it again.
:::

:::danger[Installer left the DB in a broken state? — FIRST INSTALL ONLY, NO USER DATA]
A 500 on `/install` usually means a partial schema from a failed attempt. The recovery wipes the **entire** database, so it is **only** safe on a first install that has never held real data. The guard below counts user-bearing rows and **aborts** unless the DB is empty — never run a bare `db:wipe --force`.

```bash
# 1. Programmatic guard — abort if ANY data exists (adjust the table to your app's users table).
ROWS=$(ssh <SSH_PRODUCTION_ALIAS> "cd ~/domains/<DOMAIN>/deploy/current \
  && php artisan tinker --execute='echo \\DB::table(\"users\")->count();'" 2>/dev/null | tr -dc '0-9')
if [ "${ROWS:-1}" != "0" ]; then
  echo "ABORT — users table has ${ROWS:-unknown} row(s); this is NOT a clean first install. Do NOT wipe."; exit 1
fi

# 2. Human gate — must type the domain to confirm an irreversible wipe.
read -r -p "Type the production domain (<DOMAIN>) to confirm DESTRUCTIVE db:wipe: " CONFIRM
[ "$CONFIRM" = "<DOMAIN>" ] || { echo "ABORT — confirmation did not match."; exit 1; }

# 3. Wipe + reset the install lock, then re-run /install in the browser.
ssh <SSH_PRODUCTION_ALIAS> "cd ~/domains/<DOMAIN>/deploy/current && php artisan db:wipe --force"
ssh <SSH_PRODUCTION_ALIAS> "rm -f ~/domains/<DOMAIN>/deploy/shared/storage/installed"
# Expected: tables dropped, lock removed — reopen https://<DOMAIN>/install
```

`db:wipe` destroys **all** data and cannot be undone. The row-count guard + typed-domain gate are mandatory — if either fails, stop and investigate by hand.
:::

<Steps>

7. **Verify it's live.** Load `/login` over HTTPS, have the human sign in as admin once, then confirm the post-session dashboard loads with no stack traces, no debug bar, and a valid SSL padlock.

   - ✅ `/login` loads over HTTPS, human admin sign-in works, and the post-session dashboard is clean with a valid padlock.

</Steps>

:::caution[Save admin credentials immediately]
Put the installer-created admin login into your password manager the moment it's set. Never paste it into a chat or commit it.
:::

## Troubleshooting

### 504 timeout during deploy or installer

- **Cause** — PHP `max_execution_time` is too short for migrations / a long first install.
- **Fix** — confirm `.user.ini` exists in `deploy/shared/` with `max_execution_time = 300` (step 3 above). If missing, write it and retry:

  ```bash
  ssh <SSH_PRODUCTION_ALIAS> "test -f ~/domains/<DOMAIN>/deploy/shared/.user.ini \
    && grep '^max_execution_time' ~/domains/<DOMAIN>/deploy/shared/.user.ini \
    || echo 'MISSING — create .user.ini (see step 3)'"
  # Expected: "max_execution_time = 300" — anything else means recreate it
  ```

### "Access denied" database error during the installer

- **Cause** — the config cache holds stale database credentials.
- **Fix** — clear the config cache, then retry the installer:

  ```bash
  ssh <SSH_PRODUCTION_ALIAS> "cd ~/domains/<DOMAIN>/deploy/current && php artisan config:clear"
  # Expected: "Configuration cache cleared!"
  ```

### `/install` stays blocked while expected open

Both `.htaccess` and Cloudflare WAF may block it — temporarily open **both**, finish the installer, then re-block both and confirm `curl -sI` returns `403`.

### `/install` stays open after completion

Installed marker missing or route block not restored — restore WAF/host block immediately and verify marker/DB install flag.

## Checklist

Do not mark this step done until **every** box below is checked.

- [ ] **🤖 Release prepared (P1)** — version picked, internal + public changelogs updated (public changelog vendor-token grep prints `Clean`), committed alone.
- [ ] **🤖 Release branch promoted** — the selected non-production source branch from `Zaj-PROJECT.md` merged into the release branch (`main` in setup-new) and pushed.
- [ ] **🤖 `.env` staged & clean** — uploaded over the SSH alias at mode `640`, placeholder check prints `Clean`.
- [ ] **🤖 Deployed** — dry-run plan reviewed, real `dep deploy production` completed.
- [ ] **🔀 Installer done** — `/install` wizard complete, route re-blocked, returns `403`; human-owned credentials are saved to the vault and non-secret wizard evidence is captured by the agent when browser automation is available.
- [ ] **🔀 Live verified** — `/login` over HTTPS, human admin sign-in done, and agent post-session dashboard verification shows a clean dashboard with a valid padlock.

:::next[Next step]
[Harden, verify & sync](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/12-production/03-harden-verify-sync/)
:::

STEP 0 — COLD-START ORIENTATION (do this BEFORE fetching any Part document; assume you have ZERO
prior context about this project):

1. Locate + identify. Run `pwd`. Read the project's `AGENTS.md` + `CLAUDE.md` if present so you
   know the repo rules and whether you are in the right project. Then read `Zaj-PROJECT.md` FIRST
   as the non-secret project bible: identity, environment matrix, toolchain versions, SSH aliases,
   deploy paths, and current phase. If `Zaj-PROJECT.md` is missing in a legacy project, read
   `Admin-Local/1-Project/1-Info/ProjectCard.md` as fallback, then create/update `Zaj-PROJECT.md`.

2. Read the state ledgers — READ BOTH OLD AND NEW NAMES (projects mid-migration use either):
   `Zaj-PROGRESS.md` OR `PROGRESS.md` (what earlier phases/steps already did, what's in-flight),
   `Zaj-BACKLOG.md` OR `BACKLOG.md` (phase-entry blockers, deferred work, and scheduled follow-up),
   and `Zaj-CUSTOMIZATIONS.md` OR `_CUSTOMIZATIONS.md` (vendor deviations + prior findings you must
   not re-derive or contradict).

3. Check git reality: `git branch --show-current`, `git log --oneline -8`, `git status --short`.
   - FRESH vs RESUMING: if commits/ledger show this phase (or earlier steps) already ran, you are
     RESUMING → verify-with-evidence, do NOT blindly re-run installer / migrate / db-create /
     asset-build. (This is the contract's reconcile rule.)
   - CONCURRENT-WORK check: uncommitted changes you didn't make, or HEAD ahead of the ledger, can
     mean ANOTHER agent is working this repo. Coordinate around hot files; do not commit over
     unrelated work. Routine tracker fixes remain agent-owned work unless they would overwrite a
     hot file another agent is editing.

4. Inherit rules + safety: skim `.claude/rules/` (project-specific vendor gotchas) and obey them +
   these non-negotiables — never echo secrets (verify by length/exit-code only), never re-run
   destructive/once-only steps, archive-don't-delete, honor 👤 vs 🤖.

5. How to fetch Part documents: prefer the ZajLibrary MCP `get_document` by SLUG. If the returned
   `commitShaShort` looks stale vs the live page (missing steps, old text), the index is behind →
   use `zajlibrary-local` (localhost) OR read the page's source `.mdx` directly from the ZajLibrary
   repo. NOTE: the MCP's "compare commitShaShort to your local git HEAD" instruction applies ONLY
   when you are working INSIDE the ZajLibrary repo — from THIS consuming project it is just a
   freshness/staleness signal, not a match to make.

6. Where to record: write current-truth facts to `Zaj-PROJECT.md`; write vendor deviations to
   `Zaj-CUSTOMIZATIONS.md`; write execution state to `Zaj-PROGRESS.md`; write blockers/deferred
   work to `Zaj-BACKLOG.md`. If a tracker row says open/deferred but you verify it is now done,
   fix the stale row in the same run with evidence — don't leave "closed in reality, open in tracker."
   File any guide bug/gap via the feedback clause (MCP `submit_feedback` +
   `Admin-Local/1-Project/playbook-feedback.md`) — log-then-continue, don't silently work around.

Only after Step 0 is complete, begin fetching Part 1.

AUTONOMY CONTRACT — complete accurate work unless a real human gate is required:
1. Treat ZajLibrary guidance as operational guidance, not a suggestion to summarize. If the user asked you to follow/apply/implement the page, do the work end to end in the real project until the page's exit criteria are met or a hard blocker is proven.
2. Do not ask the user whether to do routine agent-owned work: reading project rules, checking git state, updating progress/customization/feedback ledgers, running verification, fixing clear best-practice issues, or choosing the safer/professional default. Do it, cite evidence, and report what changed.
3. Ask the human only for true human-owned actions: credentials, API keys, paid/provider dashboards, DNS/production cutovers, destructive or irreversible operations, personal/business choices, legal/commercial decisions, or cases where two options are genuinely equal and the guide/project gives no tie-breaker.
4. If one option is clearly more secure, more professional, more maintainable, or better aligned with the guide/project rules, choose it and document the rationale instead of asking for a preference.
5. When you discover already-completed or partially-completed work, reconcile from evidence. Verify the end state, update the relevant ledger/checklist if state changed, and avoid re-running destructive or once-only commands.
6. Banned routine asks: "should I update trackers?", "should I commit?", "should I run verification?", "should I fix the stale ledger?", or "which option do you prefer?" when the guide/project makes one option clearly better.
7. If the guide has a gap or mismatch, log it through the project's documented feedback path and continue with the safest evidence-backed implementation when possible. Stop only when continuing would be unsafe, destructive, or would require a human-owned decision.

AUTHENTICATION BOUNDARY — hard, non-overridable:
An AI agent cannot type a password to authenticate, cannot log in, and cannot create an account in ANY environment (dev/staging included), even when the user authorizes it and the password is in the vault.
For every login-gated verification step (dashboard walk, user journey, admin panel, hPanel, registrar/provider dashboard): 👤 Human performs the ONE login, dashboard sign-in, account creation, or credential-entry moment. 🤖 Agent drives everything after the authenticated session exists — clicks, navigation, non-secret form fills, screenshots, checks.
For account creation, login, password-change, or password-reset forms, the human completes the credential/auth transaction through submit; the agent resumes after the account/session/credential change exists. Everything an agent can do without authenticating stays 🤖: public pages, viewport/mobile checks, API calls with an already-provided token, SSH/DB checks, and browser-driven configuration up to (but not including) a password/secret field. Only credential entry and the authentication/account-creation act are 👤.

Autonomy: Do all 🤖 work without asking — tracker updates, verification, signed commits, reconciling stale items to reality are the job, not questions. Stop for the human ONLY at genuine 👤 gates: real secrets/credentials, irreversible actions (prod deploy, real money, data deletion, force-push), or genuine WHAT/scope/business decisions.

Full ≠ optional: Autonomy does not mean minimal. Execute each Part fully — every Step, every # Expected: check, all states/sub-flows wired end-to-end. Never ship a happy-path subset as "done." If something genuinely can't finish in-session, it must be a real 👤/external gate (not a shortcut), stated exactly — what is deferred and why — as a tracked item before moving on. When the user says "do fully," honor it to completion.

EXECUTION CONTRACT — full coverage, no silent skips:
1. Before finishing a Part, you MUST account for EVERY item in the Part's `## Steps` (including each numbered sub-step inside <Steps> blocks) AND every box in `## Checklist`. Nothing is implicitly done.
2. Scope labels are not skip permission. `MUST`, `SHOULD`, `OPTIONAL`, quality-track, companion, and fast-mode labels explain gate priority; they do NOT remove an item from coverage. Default to FULL execution. Run `MUST-only`, `MUST+SHOULD-only`, gate-only, or fast mode only when the user explicitly asks for that mode. Even then, name every skipped `SHOULD` / `OPTIONAL` item that the chosen mode leaves out as ⏭ DEFERRED with why and when.
3. For EACH sub-step and EACH checklist box, do ONE of — and record which, with evidence:
     ✅ WALKED         — you ran the command/action; paste/point to the output it produced.
     🔍 VERIFIED-STATE — end-state already satisfied (idempotent step, or a prior session did it). Allowed, but you MUST cite the evidence (command output/file/DB state) proving it — never assert "already done" without proof.
     ⏭ DEFERRED        — legitimately out of scope now (a :::note[Who does this] 👤 step you're waiting on, or an explicit "later phase" pointer). State why + to when.
     ◐ PARTIAL         — some sub-parts done, some deferred; list exactly which and why.
4. Honor every `# Expected:` / ✅ bullet — compare actual output. On mismatch, first investigate safely and reconcile from evidence; STOP and ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices. Honor :::caution/:::danger as hard gates. Honor 👤 vs 🤖.
5. Reconciliation is allowed (don't blindly re-run installers/migrations/db-create/asset builds) — but reconciliation without per-item disclosure is BANNED.
6. You may NOT declare the Part/Phase "done" while any `## Steps` Step, sub-step, or `## Checklist` box is unclassified. Silent omission = incomplete.
7. Server continuity: if a local/server URL was working before edits, capture a baseline first. After edits, verify the server still starts and the same URL still responds. For localhost, prefer the current route or the phase/page route the user is viewing. If the server was not running before, mark server continuity as N/A with evidence instead of pretending it was verified.
8. END every run with a COVERAGE ASSERTION table (one row per sub-step + per checklist box, plus a server-continuity row when edits touched code, config, docs UI, routes, assets, or generated prompt behavior):
     | Item (§/step or checklist box) | ✅WALKED / 🔍VERIFIED / ⏭DEFERRED / ◐PARTIAL | Evidence / why |
   Then confirm the page/phase Gate condition is observably met. If the table has any row that isn't ✅/🔍 (or a justified ⏭/◐), the step is NOT done.
9. Progress/state updates are part of execution: when the guide changes project state, update `Zaj-PROJECT.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, `Zaj-CUSTOMIZATIONS.md`, and/or `playbook-feedback.md` yourself unless the project explicitly marks that exact write human-owned. Stale-open tracker rows that evidence proves done are bugs to fix, not notes to ask about.
10. Authentication boundary: an agent never types passwords, logs in, or creates accounts. Human performs the credential/authentication/account-creation transaction; agent resumes after the session or non-secret evidence exists.
11. Secrets: never put keys/passwords/.env values in code, commits, or chat; verify by length/exit-code only.

TL;DR

Objective — cut the changelog and version, promote the verified non-production branch to the release branch (main in setup-new), stage the production .env, deploy the production target (dry-run then real), run the installer on the first deploy, and confirm the app is live — so release docs travel with the release commit and verified non-production code goes live cleanly.

Steps at a glance:

Prepare the release — Cut the changelog and version before deploying so release docs travel with the release commit.
Cut the first production release — The core move: put the verified non-production code live and complete the installer.

🔀 User part — the production web installer follows the same split as staging: an agent drives non-secret browser screens when automation is available, but credential/account steps are human-owned. Completing /install fields that require DB credentials, admin password, or account creation, and performing the one live admin sign-in are person actions. An agent can drive the git, .env, dep deploy, public curl checks, and post-session dashboard verification after the human-created session exists.

Done when the changelogs are committed, the release branch carries the merged non-production code, the .env is placeholder-free, the production deploy target succeeds, the installer is complete and re-blocked (403), and /login loads over HTTPS with a valid padlock and no debug output. · ⏱ ~1.5 hr · 🔀 mixed (🤖 deploy commands + post-session checks, 👤 installer auth/account steps).

Steps

1. Prepare the release (P1)

Cut the changelog and version before deploying so release docs travel with the release commit.

Pick the version using SemVer — patch for fixes, minor for non-breaking features, major for breaking changes or a major vendor update.
Terminal window
```
git tag --sort=-v:refname | head -5   # what's already released
# Expected: the most recent release tags, newest first
```
- ✅ The chosen version follows SemVer and doesn’t collide with an existing tag.
Update the internal changelog — move [Unreleased] items into a dated version section, tag entries ([PUBLIC], [INTERNAL], [VENDOR], [SECURITY]), and reset [Unreleased].
- ✅ The internal changelog has a dated, tagged version section and an empty [Unreleased].
Update the public changelog — extract the [PUBLIC] items and rewrite them as user benefits (“added caching” → “dashboard loads 2× faster”).

The public changelog (and any in-app “what’s new” / release notes) is a customer-facing artifact — it must never name the underlying CodeCanyon vendor, script, or marketplace. Scrub every vendor/author token before committing:
Terminal window
```
# Fails (non-empty) if any vendor/marketplace identifier leaked into the public changelog.
grep -inE 'workdo|codecanyon|envato|piprahost|froiden|author-v[0-9]|<your vendor/script names>' CHANGELOG-PUBLIC.md \
  && echo "STOP — scrub the vendor name from the public changelog (use your own product name + SemVer only)" \
  || echo "Clean — no vendor identifiers in the public changelog"
# Expected: "Clean — no vendor identifiers in the public changelog"
```
Keep the vendor base and author-v${VERSION} provenance in the internal Zaj-CHANGELOG.md only (tagged [VENDOR]), never in the public one.
- ✅ The public changelog reads as user-facing benefits, names only your own product + SemVer, and the vendor-token grep prints Clean.

Commit the changelogs alone.

git add Zaj-CHANGELOG.md CHANGELOG-PUBLIC.md
git commit -m "Update changelogs for v${VERSION}"
# Expected: one commit containing only the two changelog files

✅ A single commit holds both changelogs and nothing else.

2. Cut the first production release (P2)

The core move: put the verified non-production code on the release branch, deploy the production target, and complete the installer.

Promote the verified non-production branch → release branch.

NON_PROD_BRANCH="staging" # example; use the verified source branch from Zaj-PROJECT.md
RELEASE_BRANCH="main"     # setup-new release branch from Zaj-PROJECT.md
git checkout "$RELEASE_BRANCH"
git merge "$NON_PROD_BRANCH" --ff-only
git push origin "$RELEASE_BRANCH"
# Expected: verified non-production commits fast-forward onto the release branch when histories allow; otherwise resolve before merge

✅ The release branch carries the verified non-production code and is pushed.

Stage the production .env first — generate it from the Phase 4 .env.tpl via the secrets manager, upload over an SSH alias (never raw user@IP), and lock permissions before any migration preview that needs DB credentials.

SSH_PRODUCTION_ALIAS="<production-alias-from-Zaj-PROJECT>"
DEPLOY_PATH="~/domains/<DOMAIN>/deploy"
TMP_ENV="$(mktemp)"

op inject -f -i .env.tpl -o "$TMP_ENV"
test -s "$TMP_ENV" && wc -c "$TMP_ENV"
ssh "$SSH_PRODUCTION_ALIAS" "mkdir -p '$DEPLOY_PATH/shared' && umask 027 && cat > '$DEPLOY_PATH/shared/.env'" < "$TMP_ENV"
ssh "$SSH_PRODUCTION_ALIAS" "chmod 640 '$DEPLOY_PATH/shared/.env' && test -s '$DEPLOY_PATH/shared/.env' && wc -c '$DEPLOY_PATH/shared/.env'"
shred -u "$TMP_ENV" 2>/dev/null || rm -f "$TMP_ENV"
test ! -f "$TMP_ENV"
# Expected: server shared/.env has a non-zero byte count, mode 640, and the local temp file is gone

✅ The production shared/.env is on the server at mode 640, and no rendered temp file remains locally.

Create the PHP override (.user.ini) — first deploy only. Long installs and migrations exceed the default PHP max_execution_time and return a 504. Write the override into the shared dir idempotently so it survives every release.

ssh <SSH_PRODUCTION_ALIAS> 'cat > ~/domains/<DOMAIN>/deploy/shared/.user.ini' <<'EOF'
max_execution_time = 300
memory_limit = 512M
max_input_time = 300
upload_max_filesize = 64M
post_max_size = 64M
EOF
ssh <SSH_PRODUCTION_ALIAS> "chmod 644 ~/domains/<DOMAIN>/deploy/shared/.user.ini"
ssh <SSH_PRODUCTION_ALIAS> "grep -q '^max_execution_time = 300' ~/domains/<DOMAIN>/deploy/shared/.user.ini \
  && echo 'OK — .user.ini present with 300s timeout' || echo 'STOP — .user.ini missing or wrong'"
# Expected: "OK — .user.ini present with 300s timeout"

✅ .user.ini exists in deploy/shared/ with max_execution_time = 300; the grep prints OK.

Pre-deploy migration safety check (only after .env is staged). Preview before you run anything destructive.

ssh <SSH_PRODUCTION_ALIAS> 'cd ~/domains/<DOMAIN>/deploy/current && php artisan migrate --pretend'
# Expected: on a first deploy with the web installer, the installer creates tables — treat DROP noise as expected only when that path applies

✅ The pretend output is reviewed in context (installer-first vs migrate-first deploy).

Confirm the .env has no placeholders — the deploy fails on an unfilled value, and every production value must be real (APP_DEBUG=false, live keys, strong passwords).

ssh <SSH_PRODUCTION_ALIAS> "grep -inE '_HERE|your_|CHANGE_ME|REPLACE|PLACEHOLDER|TODO|xxx|<[A-Z_]+>' ~/domains/<DOMAIN>/deploy/shared/.env" \
  && echo "STOP — fix placeholders" || echo "Clean"
# Expected: "Clean" — no placeholder tokens remain (does not false-positive on https:// URLs)

✅ The check prints Clean; no placeholder values remain.

Deploy — dry-run, then for real. The first deploy auto-skips migrations; the web installer creates the schema.
Terminal window
```
dep deploy production --plan
dep deploy production
# Expected: the plan lists steps without applying them, then the real deploy completes
```
- ✅ The dry-run plan looks right and the real deploy completes without errors.

A fresh production server must reach /install — never seed it with an install marker

The reason this first deploy lands on the installer wizard is that the fresh server has no storage/installed marker yet. The marker is per-env runtime state (gitignored in Phase 2 §2) and must not ride in from the repo or a staging snapshot — a marker present on an un-installed DB makes the app’s CheckInstallation middleware skip /install, leaving a broken app that looks “done.” If you seed storage/ from another environment, exclude the marker: rsync -a --exclude='installed' …. On subsequent deploys the marker already lives in the server’s shared storage/ (which preserves it + all uploads across releases) — so the installer is correctly skipped. Confirm the fresh server has no marker before opening the wizard:

ssh <SSH_PRODUCTION_ALIAS> "test -f ~/domains/<DOMAIN>/deploy/shared/storage/installed \
  && echo 'STOP — marker present on a fresh install; rm it (it was wrongly seeded)' \
  || echo 'OK — no marker; the installer will run'"
# Expected: "OK — no marker; the installer will run"

The next two substeps are browser actions — completing the installer wizard and verifying the live app in a browser.

Run the installer (first deploy only). The /install route is blocked at two layers — .htaccess and (if configured) a Cloudflare WAF rule. Unblock both, complete the wizard, then re-block both and verify.

a. Unblock /install (agent — .htaccess + user — WAF):
Terminal window
```
# .htaccess layer (idempotent — only flips an un-commented rule)
ssh <SSH_PRODUCTION_ALIAS> 'cd ~/domains/<DOMAIN>/deploy/current/public \
  && sed -i "s/^RewriteRule \^install/# RewriteRule ^install/" .htaccess && echo "/install unblocked in .htaccess"'
# Reset the install lock so the wizard can run (auto-recreated on finish).
ssh <SSH_PRODUCTION_ALIAS> "rm -f ~/domains/<DOMAIN>/deploy/shared/storage/installed"
```
👤 WAF layer (browser): in the Cloudflare dashboard, toggle the WAF rule “Block install and update routes” OFF. The .htaccess edit alone is not enough — the WAF returns a 403 ahead of the origin.

Verify it is reachable before opening the wizard:
Terminal window
```
curl -sI https://<DOMAIN>/install | head -1
# Expected: HTTP/2 200  (if still 403, the Cloudflare WAF rule is still ON)
```
- ✅ curl -sI /install returns 200 (both .htaccess and the WAF rule are off).
b. Complete the wizard (🔀 browser automation + human secrets): the agent drives requirements, permissions, non-secret environment fields, production URL, Install, and Finish when browser automation is available. The human enters production DB password, admin password, account-creation fields, or any other credential/secret field, then the agent resumes.

c. Re-block both layers (agent — .htaccess + user — WAF):
Terminal window
```
ssh <SSH_PRODUCTION_ALIAS> 'cd ~/domains/<DOMAIN>/deploy/current/public \
  && sed -i "s/^# RewriteRule \^install/RewriteRule ^install/" .htaccess && echo "/install re-blocked in .htaccess"'
curl -sI https://<DOMAIN>/install | head -1
# Expected: HTTP/2 403
```
👤 WAF layer: toggle the Cloudflare WAF rule “Block install and update routes” back ON.
- ✅ curl -sI /install returns 403, and both the .htaccess rule and the Cloudflare WAF rule are re-enabled.

Installer status codes are fast to misread. If /install returns anything other than the expected open-then-closed sequence, use HTTP error triage before changing code:

`/install` result	Meaning to check first	Fix path
`403` while opening	`.htaccess` or Cloudflare WAF still blocks the route	Open both layers, then retry
`404` while opening	Laravel route, rewrite layer, or wrong public symlink	Walk Laravel → Apache → WAF → symlink/perms
`302` when expecting the wizard	App thinks install is complete or middleware redirected	Check `storage/installed` and installer state

A 500 on /install usually means a partial schema from a failed attempt. The recovery wipes the entire database, so it is only safe on a first install that has never held real data. The guard below counts user-bearing rows and aborts unless the DB is empty — never run a bare db:wipe --force.

# 1. Programmatic guard — abort if ANY data exists (adjust the table to your app's users table).
ROWS=$(ssh <SSH_PRODUCTION_ALIAS> "cd ~/domains/<DOMAIN>/deploy/current \
  && php artisan tinker --execute='echo \\DB::table(\"users\")->count();'" 2>/dev/null | tr -dc '0-9')
if [ "${ROWS:-1}" != "0" ]; then
  echo "ABORT — users table has ${ROWS:-unknown} row(s); this is NOT a clean first install. Do NOT wipe."; exit 1
fi

# 2. Human gate — must type the domain to confirm an irreversible wipe.
read -r -p "Type the production domain (<DOMAIN>) to confirm DESTRUCTIVE db:wipe: " CONFIRM
[ "$CONFIRM" = "<DOMAIN>" ] || { echo "ABORT — confirmation did not match."; exit 1; }

# 3. Wipe + reset the install lock, then re-run /install in the browser.
ssh <SSH_PRODUCTION_ALIAS> "cd ~/domains/<DOMAIN>/deploy/current && php artisan db:wipe --force"
ssh <SSH_PRODUCTION_ALIAS> "rm -f ~/domains/<DOMAIN>/deploy/shared/storage/installed"
# Expected: tables dropped, lock removed — reopen https://<DOMAIN>/install

db:wipe destroys all data and cannot be undone. The row-count guard + typed-domain gate are mandatory — if either fails, stop and investigate by hand.

Verify it’s live. Load /login over HTTPS, have the human sign in as admin once, then confirm the post-session dashboard loads with no stack traces, no debug bar, and a valid SSL padlock.
- ✅ /login loads over HTTPS, human admin sign-in works, and the post-session dashboard is clean with a valid padlock.

Troubleshooting

504 timeout during deploy or installer

Cause — PHP max_execution_time is too short for migrations / a long first install.

Fix — confirm .user.ini exists in deploy/shared/ with max_execution_time = 300 (step 3 above). If missing, write it and retry:

ssh <SSH_PRODUCTION_ALIAS> "test -f ~/domains/<DOMAIN>/deploy/shared/.user.ini \
  && grep '^max_execution_time' ~/domains/<DOMAIN>/deploy/shared/.user.ini \
  || echo 'MISSING — create .user.ini (see step 3)'"
# Expected: "max_execution_time = 300" — anything else means recreate it

“Access denied” database error during the installer

Cause — the config cache holds stale database credentials.

Fix — clear the config cache, then retry the installer:

ssh <SSH_PRODUCTION_ALIAS> "cd ~/domains/<DOMAIN>/deploy/current && php artisan config:clear"
# Expected: "Configuration cache cleared!"

`/install` stays blocked while expected open

Both .htaccess and Cloudflare WAF may block it — temporarily open both, finish the installer, then re-block both and confirm curl -sI returns 403.

`/install` stays open after completion

Installed marker missing or route block not restored — restore WAF/host block immediately and verify marker/DB install flag.

Checklist

Do not mark this step done until every box below is checked.

🤖 Release prepared (P1) — version picked, internal + public changelogs updated (public changelog vendor-token grep prints Clean), committed alone.
🤖 Release branch promoted — the selected non-production source branch from Zaj-PROJECT.md merged into the release branch (main in setup-new) and pushed.
🤖 .env staged & clean — uploaded over the SSH alias at mode 640, placeholder check prints Clean.
🤖 Deployed — dry-run plan reviewed, real dep deploy production completed.
🔀 Installer done — /install wizard complete, route re-blocked, returns 403; human-owned credentials are saved to the vault and non-secret wizard evidence is captured by the agent when browser automation is available.
🔀 Live verified — /login over HTTPS, human admin sign-in done, and agent post-session dashboard verification shows a clean dashboard with a valid padlock.

Harden, verify & sync

STEP 0 — COLD-START ORIENTATION (do this BEFORE fetching any Part document; assume you have ZERO
prior context about this project):

1. Locate + identify. Run `pwd`. Read the project's `AGENTS.md` + `CLAUDE.md` if present so you
   know the repo rules and whether you are in the right project. Then read `Zaj-PROJECT.md` FIRST
   as the non-secret project bible: identity, environment matrix, toolchain versions, SSH aliases,
   deploy paths, and current phase. If `Zaj-PROJECT.md` is missing in a legacy project, read
   `Admin-Local/1-Project/1-Info/ProjectCard.md` as fallback, then create/update `Zaj-PROJECT.md`.

2. Read the state ledgers — READ BOTH OLD AND NEW NAMES (projects mid-migration use either):
   `Zaj-PROGRESS.md` OR `PROGRESS.md` (what earlier phases/steps already did, what's in-flight),
   `Zaj-BACKLOG.md` OR `BACKLOG.md` (phase-entry blockers, deferred work, and scheduled follow-up),
   and `Zaj-CUSTOMIZATIONS.md` OR `_CUSTOMIZATIONS.md` (vendor deviations + prior findings you must
   not re-derive or contradict).

3. Check git reality: `git branch --show-current`, `git log --oneline -8`, `git status --short`.
   - FRESH vs RESUMING: if commits/ledger show this phase (or earlier steps) already ran, you are
     RESUMING → verify-with-evidence, do NOT blindly re-run installer / migrate / db-create /
     asset-build. (This is the contract's reconcile rule.)
   - CONCURRENT-WORK check: uncommitted changes you didn't make, or HEAD ahead of the ledger, can
     mean ANOTHER agent is working this repo. Coordinate around hot files; do not commit over
     unrelated work. Routine tracker fixes remain agent-owned work unless they would overwrite a
     hot file another agent is editing.

4. Inherit rules + safety: skim `.claude/rules/` (project-specific vendor gotchas) and obey them +
   these non-negotiables — never echo secrets (verify by length/exit-code only), never re-run
   destructive/once-only steps, archive-don't-delete, honor 👤 vs 🤖.

5. How to fetch Part documents: prefer the ZajLibrary MCP `get_document` by SLUG. If the returned
   `commitShaShort` looks stale vs the live page (missing steps, old text), the index is behind →
   use `zajlibrary-local` (localhost) OR read the page's source `.mdx` directly from the ZajLibrary
   repo. NOTE: the MCP's "compare commitShaShort to your local git HEAD" instruction applies ONLY
   when you are working INSIDE the ZajLibrary repo — from THIS consuming project it is just a
   freshness/staleness signal, not a match to make.

6. Where to record: write current-truth facts to `Zaj-PROJECT.md`; write vendor deviations to
   `Zaj-CUSTOMIZATIONS.md`; write execution state to `Zaj-PROGRESS.md`; write blockers/deferred
   work to `Zaj-BACKLOG.md`. If a tracker row says open/deferred but you verify it is now done,
   fix the stale row in the same run with evidence — don't leave "closed in reality, open in tracker."
   File any guide bug/gap via the feedback clause (MCP `submit_feedback` +
   `Admin-Local/1-Project/playbook-feedback.md`) — log-then-continue, don't silently work around.

Only after Step 0 is complete, begin fetching Part 1.

# ZajLibrary — implementation playbook

You are a **senior implementation assistant** working inside the user’s real development environment (terminal, editor, git repo). You are **not** a documentation writer, tutor, or library editor.

**Mission:** Execute the procedure described below in the user’s real project workspace — create or modify the files and run the commands it specifies. Do not just summarize it.

AUTONOMY CONTRACT — complete accurate work unless a real human gate is required:
1. Treat ZajLibrary guidance as operational guidance, not a suggestion to summarize. If the user asked you to follow/apply/implement the page, do the work end to end in the real project until the page's exit criteria are met or a hard blocker is proven.
2. Do not ask the user whether to do routine agent-owned work: reading project rules, checking git state, updating progress/customization/feedback ledgers, running verification, fixing clear best-practice issues, or choosing the safer/professional default. Do it, cite evidence, and report what changed.
3. Ask the human only for true human-owned actions: credentials, API keys, paid/provider dashboards, DNS/production cutovers, destructive or irreversible operations, personal/business choices, legal/commercial decisions, or cases where two options are genuinely equal and the guide/project gives no tie-breaker.
4. If one option is clearly more secure, more professional, more maintainable, or better aligned with the guide/project rules, choose it and document the rationale instead of asking for a preference.
5. When you discover already-completed or partially-completed work, reconcile from evidence. Verify the end state, update the relevant ledger/checklist if state changed, and avoid re-running destructive or once-only commands.
6. Banned routine asks: "should I update trackers?", "should I commit?", "should I run verification?", "should I fix the stale ledger?", or "which option do you prefer?" when the guide/project makes one option clearly better.
7. If the guide has a gap or mismatch, log it through the project's documented feedback path and continue with the safest evidence-backed implementation when possible. Stop only when continuing would be unsafe, destructive, or would require a human-owned decision.

AUTHENTICATION BOUNDARY — hard, non-overridable:
An AI agent cannot type a password to authenticate, cannot log in, and cannot create an account in ANY environment (dev/staging included), even when the user authorizes it and the password is in the vault.
For every login-gated verification step (dashboard walk, user journey, admin panel, hPanel, registrar/provider dashboard): 👤 Human performs the ONE login, dashboard sign-in, account creation, or credential-entry moment. 🤖 Agent drives everything after the authenticated session exists — clicks, navigation, non-secret form fills, screenshots, checks.
For account creation, login, password-change, or password-reset forms, the human completes the credential/auth transaction through submit; the agent resumes after the account/session/credential change exists. Everything an agent can do without authenticating stays 🤖: public pages, viewport/mobile checks, API calls with an already-provided token, SSH/DB checks, and browser-driven configuration up to (but not including) a password/secret field. Only credential entry and the authentication/account-creation act are 👤.

## Metadata
- title: 2 · Release & first production deploy (P1–P2)
- url: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/12-production/02-release-and-deploy/
- shelf: Build & Create
- doc_type: implementation playbook
- status: current
- kind: playbook
- category: tech-stack
- subcategory: laravel
- topic: codecanyon
- phase: 12
- part_number: 2 (legacy stepNumber frontmatter)
- legacy_step_number: 2
- est_time: ~1.5 hr
- description: Cut the changelog and version before deploying, then promote the verified non-production branch to the release branch, stage the production .env, deploy dry-run then real, run the installer (first deploy only), and verify it's live.
- tags: codecanyon, laravel, deploy, release

## Execution rules (binding)
- This is Part 2 of phase 12 (~1.5 hr) — execute this Part fully, then stop at its `## Checklist`.
- Autonomy: Do all 🤖 work without asking — tracker updates, verification, signed commits, reconciling stale items to reality are the job, not questions. Stop for the human ONLY at genuine 👤 gates: real secrets/credentials, irreversible actions (prod deploy, real money, data deletion, force-push), or genuine WHAT/scope/business decisions.
- Full ≠ optional: Autonomy does not mean minimal. Execute each Part fully — every Step, every # Expected: check, all states/sub-flows wired end-to-end. Never ship a happy-path subset as "done." If something genuinely can't finish in-session, it must be a real 👤/external gate (not a shortcut), stated exactly — what is deferred and why — as a tracked item before moving on. When the user says "do fully," honor it to completion.
- For playbooks, treat a Part as the `.mdx` page-level execution unit and each item in `## Steps` as a Step inside that Part.
- Follow `## Steps` in order. Do not skip Steps or declare the work complete early.
- Respect `:::note[Who does this]`: 👤 **User** steps (authentication, account creation, password/secret entry, paid/provider dashboards, destructive actions) need the human; 🤖 **Agent** steps you run in the shell or browser after the authenticated session exists.
- After every command, compare its output to the `# Expected:` comment or ✅ bullet beneath it. If it differs, investigate safely and reconcile from evidence first; ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices.
- Honor `:::caution` / `:::note` callouts as hard gates (a step may forbid a command at this stage).
- Do not mark the Part done until every `## Checklist` item is genuinely satisfied.
- Scope: implement only what this Part describes — no refactors, added features, or later-phase work unless the Part says so.
- When the work changes project state, update the relevant progress/customization/feedback ledger yourself; do not ask whether routine state tracking should be updated.
- When reporting progress, cite the `##` / `###` headings you completed or got blocked on.
- Secrets: never put API keys, passwords, or `.env` values in frontend code, commits, or chat logs — use server-side `.env` / config only, and keep `.env` gitignored.
- EXECUTION CONTRACT — full coverage, no silent skips:
1. Before finishing a Part, you MUST account for EVERY item in the Part's `## Steps` (including each numbered sub-step inside <Steps> blocks) AND every box in `## Checklist`. Nothing is implicitly done.
2. Scope labels are not skip permission. `MUST`, `SHOULD`, `OPTIONAL`, quality-track, companion, and fast-mode labels explain gate priority; they do NOT remove an item from coverage. Default to FULL execution. Run `MUST-only`, `MUST+SHOULD-only`, gate-only, or fast mode only when the user explicitly asks for that mode. Even then, name every skipped `SHOULD` / `OPTIONAL` item that the chosen mode leaves out as ⏭ DEFERRED with why and when.
3. For EACH sub-step and EACH checklist box, do ONE of — and record which, with evidence:
     ✅ WALKED         — you ran the command/action; paste/point to the output it produced.
     🔍 VERIFIED-STATE — end-state already satisfied (idempotent step, or a prior session did it). Allowed, but you MUST cite the evidence (command output/file/DB state) proving it — never assert "already done" without proof.
     ⏭ DEFERRED        — legitimately out of scope now (a :::note[Who does this] 👤 step you're waiting on, or an explicit "later phase" pointer). State why + to when.
     ◐ PARTIAL         — some sub-parts done, some deferred; list exactly which and why.
4. Honor every `# Expected:` / ✅ bullet — compare actual output. On mismatch, first investigate safely and reconcile from evidence; STOP and ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices. Honor :::caution/:::danger as hard gates. Honor 👤 vs 🤖.
5. Reconciliation is allowed (don't blindly re-run installers/migrations/db-create/asset builds) — but reconciliation without per-item disclosure is BANNED.
6. You may NOT declare the Part/Phase "done" while any `## Steps` Step, sub-step, or `## Checklist` box is unclassified. Silent omission = incomplete.
7. Server continuity: if a local/server URL was working before edits, capture a baseline first. After edits, verify the server still starts and the same URL still responds. For localhost, prefer the current route or the phase/page route the user is viewing. If the server was not running before, mark server continuity as N/A with evidence instead of pretending it was verified.
8. END every run with a COVERAGE ASSERTION table (one row per sub-step + per checklist box, plus a server-continuity row when edits touched code, config, docs UI, routes, assets, or generated prompt behavior):
     | Item (§/step or checklist box) | ✅WALKED / 🔍VERIFIED / ⏭DEFERRED / ◐PARTIAL | Evidence / why |
   Then confirm the page/phase Gate condition is observably met. If the table has any row that isn't ✅/🔍 (or a justified ⏭/◐), the step is NOT done.
9. Progress/state updates are part of execution: when the guide changes project state, update `Zaj-PROJECT.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, `Zaj-CUSTOMIZATIONS.md`, and/or `playbook-feedback.md` yourself unless the project explicitly marks that exact write human-owned. Stale-open tracker rows that evidence proves done are bugs to fix, not notes to ask about.
10. Authentication boundary: an agent never types passwords, logs in, or creates accounts. Human performs the credential/authentication/account-creation transaction; agent resumes after the session or non-secret evidence exists.
11. Secrets: never put keys/passwords/.env values in code, commits, or chat; verify by length/exit-code only.

---

# 2 · Release & first production deploy (P1–P2)

## TL;DR

**Objective** — cut the changelog and version, promote the verified non-production branch to the release branch (`main` in setup-new), stage the production `.env`, deploy the `production` target (dry-run then real), run the installer on the first deploy, and confirm the app is live — so release docs travel with the release commit and verified non-production code goes live cleanly.

**Steps at a glance:**
1. **Prepare the release** — Cut the changelog and version before deploying so release docs travel with the
   release commit.
2. **Cut the first production release** — The core move: put the verified non-production code live and complete the
   installer.

:::note[User part + done-when]
**🔀 User part** — the production web installer follows the same split as staging: an agent drives non-secret browser screens when automation is available, but credential/account steps are human-owned. Completing `/install` fields that require DB credentials, admin password, or account creation, and performing the one live admin sign-in are person actions. An agent can drive the git, `.env`, `dep deploy`, public curl checks, and post-session dashboard verification after the human-created session exists.

**Done when** the changelogs are committed, the release branch carries the merged non-production code, the `.env` is placeholder-free, the `production` deploy target succeeds, the installer is complete and re-blocked (`403`), and `/login` loads over HTTPS with a valid padlock and no debug output. &nbsp;·&nbsp; **⏱ ~1.5 hr** &nbsp;·&nbsp; 🔀 mixed (🤖 deploy commands + post-session checks, 👤 installer auth/account steps).
:::

## Steps

### 1. Prepare the release (P1)

Cut the changelog and version **before** deploying so release docs travel with the release commit.

<Steps>

1. **Pick the version** using SemVer — patch for fixes, minor for non-breaking features, major for breaking changes or a major vendor update.

   ```bash
   git tag --sort=-v:refname | head -5   # what's already released
   # Expected: the most recent release tags, newest first
   ```

   - ✅ The chosen version follows SemVer and doesn't collide with an existing tag.

2. **Update the internal changelog** — move `[Unreleased]` items into a dated version section, tag entries (`[PUBLIC]`, `[INTERNAL]`, `[VENDOR]`, `[SECURITY]`), and reset `[Unreleased]`.

   - ✅ The internal changelog has a dated, tagged version section and an empty `[Unreleased]`.

3. **Update the public changelog** — extract the `[PUBLIC]` items and rewrite them as user benefits ("added caching" → "dashboard loads 2× faster").

   The public changelog (and any in-app "what's new" / release notes) is a **customer-facing artifact** — it must **never** name the underlying CodeCanyon vendor, script, or marketplace. Scrub every vendor/author token before committing:

   ```bash
   # Fails (non-empty) if any vendor/marketplace identifier leaked into the public changelog.
   grep -inE 'workdo|codecanyon|envato|piprahost|froiden|author-v[0-9]|<your vendor/script names>' CHANGELOG-PUBLIC.md \
     && echo "STOP — scrub the vendor name from the public changelog (use your own product name + SemVer only)" \
     || echo "Clean — no vendor identifiers in the public changelog"
   # Expected: "Clean — no vendor identifiers in the public changelog"
   ```

   Keep the vendor base and `author-v${VERSION}` provenance in the **internal** `Zaj-CHANGELOG.md` only (tagged `[VENDOR]`), never in the public one.

   - ✅ The public changelog reads as user-facing benefits, names only your own product + SemVer, and the vendor-token grep prints `Clean`.

4. **Commit the changelogs alone.**

   ```bash
   git add Zaj-CHANGELOG.md CHANGELOG-PUBLIC.md
   git commit -m "Update changelogs for v${VERSION}"
   # Expected: one commit containing only the two changelog files
   ```

   - ✅ A single commit holds both changelogs and nothing else.

</Steps>

### 2. Cut the first production release (P2)

The core move: put the verified non-production code on the release branch, deploy the `production` target, and complete the installer.

:::danger[Do not deploy into a broken Cloudflare/origin state]
Before merging or deploying, Task P.0 must show that the production domain resolves to the current origin IP, the origin certificate is valid, and Cloudflare is not returning `525`. A `525` means Cloudflare cannot complete TLS with the origin, or DNS is still pointed at a stale box. Finish DNS + origin SSL bring-up first; do not deploy Laravel into a half-proxied production hostname.
:::

<Steps>

1. **Promote the verified non-production branch → release branch.**

   ```bash
   NON_PROD_BRANCH="staging" # example; use the verified source branch from Zaj-PROJECT.md
   RELEASE_BRANCH="main"     # setup-new release branch from Zaj-PROJECT.md
   git checkout "$RELEASE_BRANCH"
   git merge "$NON_PROD_BRANCH" --ff-only
   git push origin "$RELEASE_BRANCH"
   # Expected: verified non-production commits fast-forward onto the release branch when histories allow; otherwise resolve before merge
   ```

   - ✅ The release branch carries the verified non-production code and is pushed.

2. **Stage the production `.env` first** — generate it from the Phase 4 `.env.tpl` via the secrets manager, upload over an SSH **alias** (never raw `user@IP`), and lock permissions **before** any migration preview that needs DB credentials.

	   ```bash
	   SSH_PRODUCTION_ALIAS="<production-alias-from-Zaj-PROJECT>"
	   DEPLOY_PATH="~/domains/<DOMAIN>/deploy"
	   TMP_ENV="$(mktemp)"

	   op inject -f -i .env.tpl -o "$TMP_ENV"
	   test -s "$TMP_ENV" && wc -c "$TMP_ENV"
	   ssh "$SSH_PRODUCTION_ALIAS" "mkdir -p '$DEPLOY_PATH/shared' && umask 027 && cat > '$DEPLOY_PATH/shared/.env'" < "$TMP_ENV"
	   ssh "$SSH_PRODUCTION_ALIAS" "chmod 640 '$DEPLOY_PATH/shared/.env' && test -s '$DEPLOY_PATH/shared/.env' && wc -c '$DEPLOY_PATH/shared/.env'"
	   shred -u "$TMP_ENV" 2>/dev/null || rm -f "$TMP_ENV"
	   test ! -f "$TMP_ENV"
	   # Expected: server shared/.env has a non-zero byte count, mode 640, and the local temp file is gone
	   ```

	   - ✅ The production `shared/.env` is on the server at mode `640`, and no rendered temp file remains locally.

3. **Create the PHP override (`.user.ini`) — first deploy only.** Long installs and migrations exceed the default PHP `max_execution_time` and return a 504. Write the override into the shared dir idempotently so it survives every release.

   ```bash
   ssh <SSH_PRODUCTION_ALIAS> 'cat > ~/domains/<DOMAIN>/deploy/shared/.user.ini' <<'EOF'
   max_execution_time = 300
   memory_limit = 512M
   max_input_time = 300
   upload_max_filesize = 64M
   post_max_size = 64M
   EOF
   ssh <SSH_PRODUCTION_ALIAS> "chmod 644 ~/domains/<DOMAIN>/deploy/shared/.user.ini"
   ssh <SSH_PRODUCTION_ALIAS> "grep -q '^max_execution_time = 300' ~/domains/<DOMAIN>/deploy/shared/.user.ini \
     && echo 'OK — .user.ini present with 300s timeout' || echo 'STOP — .user.ini missing or wrong'"
   # Expected: "OK — .user.ini present with 300s timeout"
   ```

   - ✅ `.user.ini` exists in `deploy/shared/` with `max_execution_time = 300`; the grep prints `OK`.

4. **Pre-deploy migration safety check** (only after `.env` is staged). Preview before you run anything destructive.

   ```bash
   ssh <SSH_PRODUCTION_ALIAS> 'cd ~/domains/<DOMAIN>/deploy/current && php artisan migrate --pretend'
   # Expected: on a first deploy with the web installer, the installer creates tables — treat DROP noise as expected only when that path applies
   ```

   - ✅ The pretend output is reviewed in context (installer-first vs migrate-first deploy).

5. **Confirm the `.env` has no placeholders** — the deploy fails on an unfilled value, and every production value must be real (`APP_DEBUG=false`, live keys, strong passwords).

   ```bash
   ssh <SSH_PRODUCTION_ALIAS> "grep -inE '_HERE|your_|CHANGE_ME|REPLACE|PLACEHOLDER|TODO|xxx|<[A-Z_]+>' ~/domains/<DOMAIN>/deploy/shared/.env" \
     && echo "STOP — fix placeholders" || echo "Clean"
   # Expected: "Clean" — no placeholder tokens remain (does not false-positive on https:// URLs)
   ```

   - ✅ The check prints `Clean`; no placeholder values remain.

6. **Deploy — dry-run, then for real.** The first deploy auto-skips migrations; the web installer creates the schema.

   ```bash
   dep deploy production --plan
   dep deploy production
   # Expected: the plan lists steps without applying them, then the real deploy completes
   ```

   - ✅ The dry-run plan looks right and the real deploy completes without errors.

</Steps>

:::caution[A fresh production server must reach `/install` — never seed it with an install marker]
The reason this first deploy lands on the installer wizard is that the **fresh** server has **no `storage/installed` marker** yet. The marker is per-env runtime state (gitignored in [Phase 2 §2](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/02-code-repo/04-initialize-repo/)) and **must not** ride in from the repo or a staging snapshot — a marker present on an un-installed DB makes the app's `CheckInstallation` middleware skip `/install`, leaving a broken app that looks "done." If you seed `storage/` from another environment, exclude the marker: `rsync -a --exclude='installed' …`. On **subsequent** deploys the marker already lives in the server's **shared `storage/`** (which preserves it + all uploads across releases) — so the installer is correctly skipped. Confirm the fresh server has no marker before opening the wizard:

```bash
ssh <SSH_PRODUCTION_ALIAS> "test -f ~/domains/<DOMAIN>/deploy/shared/storage/installed \
  && echo 'STOP — marker present on a fresh install; rm it (it was wrongly seeded)' \
  || echo 'OK — no marker; the installer will run'"
# Expected: "OK — no marker; the installer will run"
```
:::

The next two substeps are browser actions — completing the installer wizard and verifying the live app in a browser.

:::note[Who does this]
🔀 **User + Agent** — 🤖 **Agent** toggles the `/install` route, drives the installer screens in an isolated browser when automation is available, fills non-secret fields from `Zaj-PROJECT.md` / the rendered production `.env`, and runs public/post-session live checks. 👤 **User** enters any password, secret, admin-account credential, or production-authorization field and performs the one admin sign-in. The agent resumes after each human-owned credential moment and verifies the dashboard.
:::

<Steps>

6. **Run the installer (first deploy only).** The `/install` route is blocked at **two** layers — `.htaccess` and (if configured) a Cloudflare WAF rule. Unblock **both**, complete the wizard, then re-block **both** and verify.

   **a. Unblock `/install` (agent — `.htaccess` + user — WAF):**

   ```bash
   # .htaccess layer (idempotent — only flips an un-commented rule)
   ssh <SSH_PRODUCTION_ALIAS> 'cd ~/domains/<DOMAIN>/deploy/current/public \
     && sed -i "s/^RewriteRule \^install/# RewriteRule ^install/" .htaccess && echo "/install unblocked in .htaccess"'
   # Reset the install lock so the wizard can run (auto-recreated on finish).
   ssh <SSH_PRODUCTION_ALIAS> "rm -f ~/domains/<DOMAIN>/deploy/shared/storage/installed"
   ```

   👤 **WAF layer (browser):** in the Cloudflare dashboard, toggle the WAF rule **"Block install and update routes" OFF**. The `.htaccess` edit alone is not enough — the WAF returns a `403` ahead of the origin.

   Verify it is reachable **before** opening the wizard:

   ```bash
   curl -sI https://<DOMAIN>/install | head -1
   # Expected: HTTP/2 200  (if still 403, the Cloudflare WAF rule is still ON)
   ```

   - ✅ `curl -sI /install` returns `200` (both `.htaccess` and the WAF rule are off).

   **b. Complete the wizard (🔀 browser automation + human secrets):** the agent drives requirements, permissions, non-secret environment fields, production URL, Install, and Finish when browser automation is available. The human enters production DB password, admin password, account-creation fields, or any other credential/secret field, then the agent resumes.

   **c. Re-block both layers (agent — `.htaccess` + user — WAF):**

   ```bash
   ssh <SSH_PRODUCTION_ALIAS> 'cd ~/domains/<DOMAIN>/deploy/current/public \
     && sed -i "s/^# RewriteRule \^install/RewriteRule ^install/" .htaccess && echo "/install re-blocked in .htaccess"'
   curl -sI https://<DOMAIN>/install | head -1
   # Expected: HTTP/2 403
   ```

   👤 **WAF layer:** toggle the Cloudflare WAF rule **"Block install and update routes" back ON**.

   - ✅ `curl -sI /install` returns `403`, and both the `.htaccess` rule and the Cloudflare WAF rule are re-enabled.

</Steps>

Installer status codes are fast to misread. If `/install` returns anything other than the expected open-then-closed sequence, use [HTTP error triage](/tech-stack/laravel/codecanyon/learn/guides/http-error-triage/) before changing code:

| `/install` result | Meaning to check first | Fix path |
|---|---|---|
| `403` while opening | `.htaccess` or Cloudflare WAF still blocks the route | Open both layers, then retry |
| `404` while opening | Laravel route, rewrite layer, or wrong public symlink | Walk Laravel → Apache → WAF → symlink/perms |
| `302` when expecting the wizard | App thinks install is complete or middleware redirected | Check `storage/installed` and installer state |

:::caution[Don't delete the install lock again]
Finishing the wizard writes `deploy/shared/storage/installed`. After the first install this file **must stay** — removing it re-opens `/install` on a live site. Only the first-install recovery in the danger box below ever touches it again.
:::

:::danger[Installer left the DB in a broken state? — FIRST INSTALL ONLY, NO USER DATA]
A 500 on `/install` usually means a partial schema from a failed attempt. The recovery wipes the **entire** database, so it is **only** safe on a first install that has never held real data. The guard below counts user-bearing rows and **aborts** unless the DB is empty — never run a bare `db:wipe --force`.

```bash
# 1. Programmatic guard — abort if ANY data exists (adjust the table to your app's users table).
ROWS=$(ssh <SSH_PRODUCTION_ALIAS> "cd ~/domains/<DOMAIN>/deploy/current \
  && php artisan tinker --execute='echo \\DB::table(\"users\")->count();'" 2>/dev/null | tr -dc '0-9')
if [ "${ROWS:-1}" != "0" ]; then
  echo "ABORT — users table has ${ROWS:-unknown} row(s); this is NOT a clean first install. Do NOT wipe."; exit 1
fi

# 2. Human gate — must type the domain to confirm an irreversible wipe.
read -r -p "Type the production domain (<DOMAIN>) to confirm DESTRUCTIVE db:wipe: " CONFIRM
[ "$CONFIRM" = "<DOMAIN>" ] || { echo "ABORT — confirmation did not match."; exit 1; }

# 3. Wipe + reset the install lock, then re-run /install in the browser.
ssh <SSH_PRODUCTION_ALIAS> "cd ~/domains/<DOMAIN>/deploy/current && php artisan db:wipe --force"
ssh <SSH_PRODUCTION_ALIAS> "rm -f ~/domains/<DOMAIN>/deploy/shared/storage/installed"
# Expected: tables dropped, lock removed — reopen https://<DOMAIN>/install
```

`db:wipe` destroys **all** data and cannot be undone. The row-count guard + typed-domain gate are mandatory — if either fails, stop and investigate by hand.
:::

<Steps>

7. **Verify it's live.** Load `/login` over HTTPS, have the human sign in as admin once, then confirm the post-session dashboard loads with no stack traces, no debug bar, and a valid SSL padlock.

   - ✅ `/login` loads over HTTPS, human admin sign-in works, and the post-session dashboard is clean with a valid padlock.

</Steps>

:::caution[Save admin credentials immediately]
Put the installer-created admin login into your password manager the moment it's set. Never paste it into a chat or commit it.
:::

## Troubleshooting

### 504 timeout during deploy or installer

- **Cause** — PHP `max_execution_time` is too short for migrations / a long first install.
- **Fix** — confirm `.user.ini` exists in `deploy/shared/` with `max_execution_time = 300` (step 3 above). If missing, write it and retry:

  ```bash
  ssh <SSH_PRODUCTION_ALIAS> "test -f ~/domains/<DOMAIN>/deploy/shared/.user.ini \
    && grep '^max_execution_time' ~/domains/<DOMAIN>/deploy/shared/.user.ini \
    || echo 'MISSING — create .user.ini (see step 3)'"
  # Expected: "max_execution_time = 300" — anything else means recreate it
  ```

### "Access denied" database error during the installer

- **Cause** — the config cache holds stale database credentials.
- **Fix** — clear the config cache, then retry the installer:

  ```bash
  ssh <SSH_PRODUCTION_ALIAS> "cd ~/domains/<DOMAIN>/deploy/current && php artisan config:clear"
  # Expected: "Configuration cache cleared!"
  ```

### `/install` stays blocked while expected open

Both `.htaccess` and Cloudflare WAF may block it — temporarily open **both**, finish the installer, then re-block both and confirm `curl -sI` returns `403`.

### `/install` stays open after completion

Installed marker missing or route block not restored — restore WAF/host block immediately and verify marker/DB install flag.

## Checklist

Do not mark this step done until **every** box below is checked.

- [ ] **🤖 Release prepared (P1)** — version picked, internal + public changelogs updated (public changelog vendor-token grep prints `Clean`), committed alone.
- [ ] **🤖 Release branch promoted** — the selected non-production source branch from `Zaj-PROJECT.md` merged into the release branch (`main` in setup-new) and pushed.
- [ ] **🤖 `.env` staged & clean** — uploaded over the SSH alias at mode `640`, placeholder check prints `Clean`.
- [ ] **🤖 Deployed** — dry-run plan reviewed, real `dep deploy production` completed.
- [ ] **🔀 Installer done** — `/install` wizard complete, route re-blocked, returns `403`; human-owned credentials are saved to the vault and non-secret wizard evidence is captured by the agent when browser automation is available.
- [ ] **🔀 Live verified** — `/login` over HTTPS, human admin sign-in done, and agent post-session dashboard verification shows a clean dashboard with a valid padlock.

:::next[Next step]
[Harden, verify & sync](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/12-production/03-harden-verify-sync/)
:::

# 2 · Release & first production deploy (P1–P2)

> Source: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/12-production/02-release-and-deploy/

## TL;DR

**Objective** — cut the changelog and version, promote the verified non-production branch to the release branch (`main` in setup-new), stage the production `.env`, deploy the `production` target (dry-run then real), run the installer on the first deploy, and confirm the app is live — so release docs travel with the release commit and verified non-production code goes live cleanly.

**Steps at a glance:**
1. **Prepare the release** — Cut the changelog and version before deploying so release docs travel with the
   release commit.
2. **Cut the first production release** — The core move: put the verified non-production code live and complete the
   installer.

:::note[User part + done-when]
**🔀 User part** — the production web installer follows the same split as staging: an agent drives non-secret browser screens when automation is available, but credential/account steps are human-owned. Completing `/install` fields that require DB credentials, admin password, or account creation, and performing the one live admin sign-in are person actions. An agent can drive the git, `.env`, `dep deploy`, public curl checks, and post-session dashboard verification after the human-created session exists.

**Done when** the changelogs are committed, the release branch carries the merged non-production code, the `.env` is placeholder-free, the `production` deploy target succeeds, the installer is complete and re-blocked (`403`), and `/login` loads over HTTPS with a valid padlock and no debug output. &nbsp;·&nbsp; **⏱ ~1.5 hr** &nbsp;·&nbsp; 🔀 mixed (🤖 deploy commands + post-session checks, 👤 installer auth/account steps).
:::

## Steps

### 1. Prepare the release (P1)

Cut the changelog and version **before** deploying so release docs travel with the release commit.

<Steps>

1. **Pick the version** using SemVer — patch for fixes, minor for non-breaking features, major for breaking changes or a major vendor update.

   ```bash
   git tag --sort=-v:refname | head -5   # what's already released
   # Expected: the most recent release tags, newest first
   ```

   - ✅ The chosen version follows SemVer and doesn't collide with an existing tag.

2. **Update the internal changelog** — move `[Unreleased]` items into a dated version section, tag entries (`[PUBLIC]`, `[INTERNAL]`, `[VENDOR]`, `[SECURITY]`), and reset `[Unreleased]`.

   - ✅ The internal changelog has a dated, tagged version section and an empty `[Unreleased]`.

3. **Update the public changelog** — extract the `[PUBLIC]` items and rewrite them as user benefits ("added caching" → "dashboard loads 2× faster").

   The public changelog (and any in-app "what's new" / release notes) is a **customer-facing artifact** — it must **never** name the underlying CodeCanyon vendor, script, or marketplace. Scrub every vendor/author token before committing:

   ```bash
   # Fails (non-empty) if any vendor/marketplace identifier leaked into the public changelog.
   grep -inE 'workdo|codecanyon|envato|piprahost|froiden|author-v[0-9]|<your vendor/script names>' CHANGELOG-PUBLIC.md \
     && echo "STOP — scrub the vendor name from the public changelog (use your own product name + SemVer only)" \
     || echo "Clean — no vendor identifiers in the public changelog"
   # Expected: "Clean — no vendor identifiers in the public changelog"
   ```

   Keep the vendor base and `author-v${VERSION}` provenance in the **internal** `Zaj-CHANGELOG.md` only (tagged `[VENDOR]`), never in the public one.

   - ✅ The public changelog reads as user-facing benefits, names only your own product + SemVer, and the vendor-token grep prints `Clean`.

4. **Commit the changelogs alone.**

   ```bash
   git add Zaj-CHANGELOG.md CHANGELOG-PUBLIC.md
   git commit -m "Update changelogs for v${VERSION}"
   # Expected: one commit containing only the two changelog files
   ```

   - ✅ A single commit holds both changelogs and nothing else.

</Steps>

### 2. Cut the first production release (P2)

The core move: put the verified non-production code on the release branch, deploy the `production` target, and complete the installer.

:::danger[Do not deploy into a broken Cloudflare/origin state]
Before merging or deploying, Task P.0 must show that the production domain resolves to the current origin IP, the origin certificate is valid, and Cloudflare is not returning `525`. A `525` means Cloudflare cannot complete TLS with the origin, or DNS is still pointed at a stale box. Finish DNS + origin SSL bring-up first; do not deploy Laravel into a half-proxied production hostname.
:::

<Steps>

1. **Promote the verified non-production branch → release branch.**

   ```bash
   NON_PROD_BRANCH="staging" # example; use the verified source branch from Zaj-PROJECT.md
   RELEASE_BRANCH="main"     # setup-new release branch from Zaj-PROJECT.md
   git checkout "$RELEASE_BRANCH"
   git merge "$NON_PROD_BRANCH" --ff-only
   git push origin "$RELEASE_BRANCH"
   # Expected: verified non-production commits fast-forward onto the release branch when histories allow; otherwise resolve before merge
   ```

   - ✅ The release branch carries the verified non-production code and is pushed.

2. **Stage the production `.env` first** — generate it from the Phase 4 `.env.tpl` via the secrets manager, upload over an SSH **alias** (never raw `user@IP`), and lock permissions **before** any migration preview that needs DB credentials.

	   ```bash
	   SSH_PRODUCTION_ALIAS="<production-alias-from-Zaj-PROJECT>"
	   DEPLOY_PATH="~/domains/<DOMAIN>/deploy"
	   TMP_ENV="$(mktemp)"

	   op inject -f -i .env.tpl -o "$TMP_ENV"
	   test -s "$TMP_ENV" && wc -c "$TMP_ENV"
	   ssh "$SSH_PRODUCTION_ALIAS" "mkdir -p '$DEPLOY_PATH/shared' && umask 027 && cat > '$DEPLOY_PATH/shared/.env'" < "$TMP_ENV"
	   ssh "$SSH_PRODUCTION_ALIAS" "chmod 640 '$DEPLOY_PATH/shared/.env' && test -s '$DEPLOY_PATH/shared/.env' && wc -c '$DEPLOY_PATH/shared/.env'"
	   shred -u "$TMP_ENV" 2>/dev/null || rm -f "$TMP_ENV"
	   test ! -f "$TMP_ENV"
	   # Expected: server shared/.env has a non-zero byte count, mode 640, and the local temp file is gone
	   ```

	   - ✅ The production `shared/.env` is on the server at mode `640`, and no rendered temp file remains locally.

3. **Create the PHP override (`.user.ini`) — first deploy only.** Long installs and migrations exceed the default PHP `max_execution_time` and return a 504. Write the override into the shared dir idempotently so it survives every release.

   ```bash
   ssh <SSH_PRODUCTION_ALIAS> 'cat > ~/domains/<DOMAIN>/deploy/shared/.user.ini' <<'EOF'
   max_execution_time = 300
   memory_limit = 512M
   max_input_time = 300
   upload_max_filesize = 64M
   post_max_size = 64M
   EOF
   ssh <SSH_PRODUCTION_ALIAS> "chmod 644 ~/domains/<DOMAIN>/deploy/shared/.user.ini"
   ssh <SSH_PRODUCTION_ALIAS> "grep -q '^max_execution_time = 300' ~/domains/<DOMAIN>/deploy/shared/.user.ini \
     && echo 'OK — .user.ini present with 300s timeout' || echo 'STOP — .user.ini missing or wrong'"
   # Expected: "OK — .user.ini present with 300s timeout"
   ```

   - ✅ `.user.ini` exists in `deploy/shared/` with `max_execution_time = 300`; the grep prints `OK`.

4. **Pre-deploy migration safety check** (only after `.env` is staged). Preview before you run anything destructive.

   ```bash
   ssh <SSH_PRODUCTION_ALIAS> 'cd ~/domains/<DOMAIN>/deploy/current && php artisan migrate --pretend'
   # Expected: on a first deploy with the web installer, the installer creates tables — treat DROP noise as expected only when that path applies
   ```

   - ✅ The pretend output is reviewed in context (installer-first vs migrate-first deploy).

5. **Confirm the `.env` has no placeholders** — the deploy fails on an unfilled value, and every production value must be real (`APP_DEBUG=false`, live keys, strong passwords).

   ```bash
   ssh <SSH_PRODUCTION_ALIAS> "grep -inE '_HERE|your_|CHANGE_ME|REPLACE|PLACEHOLDER|TODO|xxx|<[A-Z_]+>' ~/domains/<DOMAIN>/deploy/shared/.env" \
     && echo "STOP — fix placeholders" || echo "Clean"
   # Expected: "Clean" — no placeholder tokens remain (does not false-positive on https:// URLs)
   ```

   - ✅ The check prints `Clean`; no placeholder values remain.

6. **Deploy — dry-run, then for real.** The first deploy auto-skips migrations; the web installer creates the schema.

   ```bash
   dep deploy production --plan
   dep deploy production
   # Expected: the plan lists steps without applying them, then the real deploy completes
   ```

   - ✅ The dry-run plan looks right and the real deploy completes without errors.

</Steps>

:::caution[A fresh production server must reach `/install` — never seed it with an install marker]
The reason this first deploy lands on the installer wizard is that the **fresh** server has **no `storage/installed` marker** yet. The marker is per-env runtime state (gitignored in [Phase 2 §2](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/02-code-repo/04-initialize-repo/)) and **must not** ride in from the repo or a staging snapshot — a marker present on an un-installed DB makes the app's `CheckInstallation` middleware skip `/install`, leaving a broken app that looks "done." If you seed `storage/` from another environment, exclude the marker: `rsync -a --exclude='installed' …`. On **subsequent** deploys the marker already lives in the server's **shared `storage/`** (which preserves it + all uploads across releases) — so the installer is correctly skipped. Confirm the fresh server has no marker before opening the wizard:

```bash
ssh <SSH_PRODUCTION_ALIAS> "test -f ~/domains/<DOMAIN>/deploy/shared/storage/installed \
  && echo 'STOP — marker present on a fresh install; rm it (it was wrongly seeded)' \
  || echo 'OK — no marker; the installer will run'"
# Expected: "OK — no marker; the installer will run"
```
:::

The next two substeps are browser actions — completing the installer wizard and verifying the live app in a browser.

:::note[Who does this]
🔀 **User + Agent** — 🤖 **Agent** toggles the `/install` route, drives the installer screens in an isolated browser when automation is available, fills non-secret fields from `Zaj-PROJECT.md` / the rendered production `.env`, and runs public/post-session live checks. 👤 **User** enters any password, secret, admin-account credential, or production-authorization field and performs the one admin sign-in. The agent resumes after each human-owned credential moment and verifies the dashboard.
:::

<Steps>

6. **Run the installer (first deploy only).** The `/install` route is blocked at **two** layers — `.htaccess` and (if configured) a Cloudflare WAF rule. Unblock **both**, complete the wizard, then re-block **both** and verify.

   **a. Unblock `/install` (agent — `.htaccess` + user — WAF):**

   ```bash
   # .htaccess layer (idempotent — only flips an un-commented rule)
   ssh <SSH_PRODUCTION_ALIAS> 'cd ~/domains/<DOMAIN>/deploy/current/public \
     && sed -i "s/^RewriteRule \^install/# RewriteRule ^install/" .htaccess && echo "/install unblocked in .htaccess"'
   # Reset the install lock so the wizard can run (auto-recreated on finish).
   ssh <SSH_PRODUCTION_ALIAS> "rm -f ~/domains/<DOMAIN>/deploy/shared/storage/installed"
   ```

   👤 **WAF layer (browser):** in the Cloudflare dashboard, toggle the WAF rule **"Block install and update routes" OFF**. The `.htaccess` edit alone is not enough — the WAF returns a `403` ahead of the origin.

   Verify it is reachable **before** opening the wizard:

   ```bash
   curl -sI https://<DOMAIN>/install | head -1
   # Expected: HTTP/2 200  (if still 403, the Cloudflare WAF rule is still ON)
   ```

   - ✅ `curl -sI /install` returns `200` (both `.htaccess` and the WAF rule are off).

   **b. Complete the wizard (🔀 browser automation + human secrets):** the agent drives requirements, permissions, non-secret environment fields, production URL, Install, and Finish when browser automation is available. The human enters production DB password, admin password, account-creation fields, or any other credential/secret field, then the agent resumes.

   **c. Re-block both layers (agent — `.htaccess` + user — WAF):**

   ```bash
   ssh <SSH_PRODUCTION_ALIAS> 'cd ~/domains/<DOMAIN>/deploy/current/public \
     && sed -i "s/^# RewriteRule \^install/RewriteRule ^install/" .htaccess && echo "/install re-blocked in .htaccess"'
   curl -sI https://<DOMAIN>/install | head -1
   # Expected: HTTP/2 403
   ```

   👤 **WAF layer:** toggle the Cloudflare WAF rule **"Block install and update routes" back ON**.

   - ✅ `curl -sI /install` returns `403`, and both the `.htaccess` rule and the Cloudflare WAF rule are re-enabled.

</Steps>

Installer status codes are fast to misread. If `/install` returns anything other than the expected open-then-closed sequence, use [HTTP error triage](/tech-stack/laravel/codecanyon/learn/guides/http-error-triage/) before changing code:

| `/install` result | Meaning to check first | Fix path |
|---|---|---|
| `403` while opening | `.htaccess` or Cloudflare WAF still blocks the route | Open both layers, then retry |
| `404` while opening | Laravel route, rewrite layer, or wrong public symlink | Walk Laravel → Apache → WAF → symlink/perms |
| `302` when expecting the wizard | App thinks install is complete or middleware redirected | Check `storage/installed` and installer state |

:::caution[Don't delete the install lock again]
Finishing the wizard writes `deploy/shared/storage/installed`. After the first install this file **must stay** — removing it re-opens `/install` on a live site. Only the first-install recovery in the danger box below ever touches it again.
:::

:::danger[Installer left the DB in a broken state? — FIRST INSTALL ONLY, NO USER DATA]
A 500 on `/install` usually means a partial schema from a failed attempt. The recovery wipes the **entire** database, so it is **only** safe on a first install that has never held real data. The guard below counts user-bearing rows and **aborts** unless the DB is empty — never run a bare `db:wipe --force`.

```bash
# 1. Programmatic guard — abort if ANY data exists (adjust the table to your app's users table).
ROWS=$(ssh <SSH_PRODUCTION_ALIAS> "cd ~/domains/<DOMAIN>/deploy/current \
  && php artisan tinker --execute='echo \\DB::table(\"users\")->count();'" 2>/dev/null | tr -dc '0-9')
if [ "${ROWS:-1}" != "0" ]; then
  echo "ABORT — users table has ${ROWS:-unknown} row(s); this is NOT a clean first install. Do NOT wipe."; exit 1
fi

# 2. Human gate — must type the domain to confirm an irreversible wipe.
read -r -p "Type the production domain (<DOMAIN>) to confirm DESTRUCTIVE db:wipe: " CONFIRM
[ "$CONFIRM" = "<DOMAIN>" ] || { echo "ABORT — confirmation did not match."; exit 1; }

# 3. Wipe + reset the install lock, then re-run /install in the browser.
ssh <SSH_PRODUCTION_ALIAS> "cd ~/domains/<DOMAIN>/deploy/current && php artisan db:wipe --force"
ssh <SSH_PRODUCTION_ALIAS> "rm -f ~/domains/<DOMAIN>/deploy/shared/storage/installed"
# Expected: tables dropped, lock removed — reopen https://<DOMAIN>/install
```

`db:wipe` destroys **all** data and cannot be undone. The row-count guard + typed-domain gate are mandatory — if either fails, stop and investigate by hand.
:::

<Steps>

7. **Verify it's live.** Load `/login` over HTTPS, have the human sign in as admin once, then confirm the post-session dashboard loads with no stack traces, no debug bar, and a valid SSL padlock.

   - ✅ `/login` loads over HTTPS, human admin sign-in works, and the post-session dashboard is clean with a valid padlock.

</Steps>

:::caution[Save admin credentials immediately]
Put the installer-created admin login into your password manager the moment it's set. Never paste it into a chat or commit it.
:::

## Troubleshooting

### 504 timeout during deploy or installer

- **Cause** — PHP `max_execution_time` is too short for migrations / a long first install.
- **Fix** — confirm `.user.ini` exists in `deploy/shared/` with `max_execution_time = 300` (step 3 above). If missing, write it and retry:

  ```bash
  ssh <SSH_PRODUCTION_ALIAS> "test -f ~/domains/<DOMAIN>/deploy/shared/.user.ini \
    && grep '^max_execution_time' ~/domains/<DOMAIN>/deploy/shared/.user.ini \
    || echo 'MISSING — create .user.ini (see step 3)'"
  # Expected: "max_execution_time = 300" — anything else means recreate it
  ```

### "Access denied" database error during the installer

- **Cause** — the config cache holds stale database credentials.
- **Fix** — clear the config cache, then retry the installer:

  ```bash
  ssh <SSH_PRODUCTION_ALIAS> "cd ~/domains/<DOMAIN>/deploy/current && php artisan config:clear"
  # Expected: "Configuration cache cleared!"
  ```

### `/install` stays blocked while expected open

Both `.htaccess` and Cloudflare WAF may block it — temporarily open **both**, finish the installer, then re-block both and confirm `curl -sI` returns `403`.

### `/install` stays open after completion

Installed marker missing or route block not restored — restore WAF/host block immediately and verify marker/DB install flag.

## Checklist

Do not mark this step done until **every** box below is checked.

- [ ] **🤖 Release prepared (P1)** — version picked, internal + public changelogs updated (public changelog vendor-token grep prints `Clean`), committed alone.
- [ ] **🤖 Release branch promoted** — the selected non-production source branch from `Zaj-PROJECT.md` merged into the release branch (`main` in setup-new) and pushed.
- [ ] **🤖 `.env` staged & clean** — uploaded over the SSH alias at mode `640`, placeholder check prints `Clean`.
- [ ] **🤖 Deployed** — dry-run plan reviewed, real `dep deploy production` completed.
- [ ] **🔀 Installer done** — `/install` wizard complete, route re-blocked, returns `403`; human-owned credentials are saved to the vault and non-secret wizard evidence is captured by the agent when browser automation is available.
- [ ] **🔀 Live verified** — `/login` over HTTPS, human admin sign-in done, and agent post-session dashboard verification shows a clean dashboard with a valid padlock.

:::next[Next step]
[Harden, verify & sync](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/12-production/03-harden-verify-sync/)
:::