7 · Shared-hosting readiness

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: 7 · Shared-hosting readiness
- url: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/07-shared-hosting-readiness/
- shelf: Build & Create
- doc_type: implementation playbook
- status: current
- kind: playbook
- category: tech-stack
- subcategory: laravel
- topic: codecanyon
- phase: 3
- part_number: 7 (legacy stepNumber frontmatter)
- legacy_step_number: 7
- est_time: ~10-45 min
- description: Verify that the hosting account has the Admin-Server toolkit before the deploy pipeline starts, or run the shared-hosting playbook first.
- tags: codecanyon, laravel, hosting, deploy

## Execution rules (binding)
- This is Part 7 of phase 3 (~10-45 min) — 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.

---

# 7 · Shared-hosting readiness

## TL;DR

**Objective** — prove the hosting account is ready for deployment before Phase 4 starts. If this server was already prepared, run the Admin-Server status check. If this is the first app on the hosting account, run the shared-hosting playbook first, then come back here and verify it.

**Steps at a glance:**
1. **Choose the hosting account and SSH alias** — Confirm which hosting account this app will deploy to and
   which local SSH alias reaches it. Use the same alias you will use in Phase 4 and Phase 5.
2. **Check whether Admin-Server already exists and is alive** — Run the status script and log-freshness probe if
   the server already has `~/Admin-Server/`. Scripts on disk are not enough; dead cron jobs block Phase 4.
3. **Run the shared-hosting playbook when this account is new** — If the status script is missing or clearly
   incomplete, stop this app playbook and run the shared-hosting playbook for the hosting account.
4. **Record the server readiness note locally** — Write the result where future sessions can find it without
   re-discovering the hosting account.

:::note[For beginners and agents]
This is a real Phase 3 step because Phase 4 assumes the server-wide toolkit already exists. Agents: do not start Deployer until every checklist box here is checked.
:::

## Background

The **[Set up shared hosting](/infrastructure/hosting/shared-hosting/build/playbooks/setup-shared-hosting/)** playbook is once per hosting account, not once per app. It installs the server-wide `~/Admin-Server/` toolkit that later deploy tasks use for deploy webhooks, ops alerts, monitoring scripts, baselines, and server notes.

This page does not duplicate that server playbook. It only decides whether the hosting account is already ready, routes first-time setup to the right place, registers this app's domain path in the integrity baseline, and gives Phase 4 a clean gate.

## Steps

### 1. Choose the hosting account and SSH alias

Confirm which hosting account this app will deploy to and which local SSH alias reaches it. Use the same alias you will use in Phase 4 and Phase 5.

:::note[Who does this]
🔀 **User + Agent** — the user confirms the intended hosting account; the agent can run the SSH checks once the alias is known.
:::

<Steps>

1. **Discover any existing SSH alias before treating SSH as unconfigured.**

   ```bash
   grep -nE '^Host |HostName|User|Port|IdentityFile' ~/.ssh/config 2>/dev/null
   # Match the target hosting IP/domain from Zaj-PROJECT.md or the onboarding summary.
   # Expected: either a reusable Host alias appears, or you know one must be created.
   ```

   - Expected: if an existing alias matches host/user/port, reuse it and record that alias in `Zaj-PROJECT.md`. If it points at an old IP, update the stanza. If no alias exists, return to Phase 2 SSH setup and create one.

2. **Set the alias for this terminal session.**

   ```bash
   export SSH_ALIAS="<selected-hosting-account-ssh-alias>"
   export PHPBIN="${PHPBIN:-php}" # replace with /opt/alt/phpXX/usr/bin/php once Phase 4 confirms it
   ssh -o BatchMode=yes -o ConnectTimeout=8 "$SSH_ALIAS" "pwd && $PHPBIN -v | head -1"
   # Expected: SSH connects without an interactive password prompt and prints a remote path plus PHP version.
   ```

   - Expected: the command exits `0`; a timeout, password prompt, or unknown host means SSH is not ready for Phase 4.

</Steps>

### 2. Check whether Admin-Server already exists and is alive

Run the status script and freshness probe if the server already has `~/Admin-Server/`. This is the fast path for a hosting account that was prepared by a previous project — but only if the cron-backed logs are fresh.

<Steps>

1. **Run the status and freshness check.**

   ```bash
   ssh "$SSH_ALIAS" 'bash -s' <<'REMOTE'
   set -euo pipefail
   cd ~/Admin-Server
   test -x scripts/status.sh
   ./scripts/status.sh
   now=$(date +%s)

   check_log() {
     label="$1"; path="$2"; max_age="$3"
     if [ ! -f "$path" ]; then echo "❌ STALE $label — missing $path"; exit 1; fi
     mtime=$(stat -c %Y "$path")
     age=$((now - mtime))
     if [ "$age" -gt "$max_age" ]; then
       echo "❌ STALE $label — last run $(date -d "@$mtime" -Is), age ${age}s, max ${max_age}s"; exit 1
     fi
     echo "✅ fresh $label — last run $(date -d "@$mtime" -Is)"
   }

   check_any_log() {
     label="$1"; max_age="$2"; shift 2
     for path in "$@"; do
       [ -f "$path" ] && check_log "$label" "$path" "$max_age" && return 0
     done
     echo "❌ STALE $label — missing expected log: $*"; exit 1
   }

   check_any_log "config snapshot"   172800  logs/snapshot-config.log
   check_any_log "integrity"         172800  logs/integrity.log logs/integrity-check.log
   check_any_log "disk/inode"         43200  logs/resource.log logs/resources.log logs/resource-check.log
   check_any_log "PHP error scan"     43200  logs/error-log.log logs/error-log-check.log
   check_any_log "domain inventory" 2592000  logs/domain-inventory.log
   check_any_log "log rotation"     1209600  logs/rotate-logs.log
   REMOTE
   # Expected: status.sh exits 0 and every log row prints "fresh"; any STALE row blocks Phase 4.
   ```

   - Expected: the script runs and every log freshness row passes. If the file is missing, not executable, reports missing setup, or prints `STALE`, continue to step 3 and fix the shared-hosting playbook before Phase 4.

2. **Add this app's domain path to the Admin-Server integrity baseline.**

   ```bash
   APP_DOMAIN="<selected-domain-from-Zaj-PROJECT>"
   ssh "$SSH_ALIAS" "APP_DOMAIN='$APP_DOMAIN' bash -s" <<'REMOTE'
   set -euo pipefail
   cd ~/Admin-Server
   path="$HOME/domains/$APP_DOMAIN"
   conf="config/monitored-paths.conf"
   touch "$conf"
   for monitored in "$HOME/.ssh/authorized_keys" "$path"; do
     grep -Fxq "$monitored" "$conf" 2>/dev/null || printf '%s\n' "$monitored" >> "$conf"
     grep -Fx "$monitored" "$conf"
   done
   ./scripts/generate-baseline.sh
   git add "$conf" baselines/checksums.md5
   git diff --cached --quiet || git commit -m "Monitor $APP_DOMAIN domain path"
   REMOTE
   # Expected: monitored-paths.conf contains authorized_keys + the app domain path; baseline regenerated.
   ```

   - Expected: `~/.ssh/authorized_keys` and the domain path are present in `monitored-paths.conf`, so integrity monitoring catches planted SSH keys and app-path drift once the app is deployed.

</Steps>

### 3. Run the shared-hosting playbook when this account is new

If the status script is missing or clearly incomplete, stop this app playbook and run the shared-hosting playbook for the hosting account. Return here only after that server playbook reaches its checklist.

:::note[Who does this]
🔀 **User + Agent** — the shared-hosting playbook may require hosting-panel access, webhook secrets, or account-level choices. Do not paste secrets into chat.
:::

<Steps>

1. **Open and complete the shared-hosting playbook.**

   - [Set up shared hosting](/infrastructure/hosting/shared-hosting/build/playbooks/setup-shared-hosting/)

   - Expected: the hosting account has `~/Admin-Server/`, executable scripts, configured monitoring/alert state, and a documented SSH alias.

2. **Re-run the status + freshness check after setup.**

   ```bash
   ssh "$SSH_ALIAS" '~/Admin-Server/scripts/status.sh'
   # Expected: status.sh shows the correct identity. Then rerun step 2's freshness probe and require no STALE rows.
   ```

   - Expected: no missing Admin-Server toolkit and no stale cron-backed logs. Fix failed checks in the shared-hosting playbook before continuing.

</Steps>

### 4. Record the server readiness note

Write the result where future sessions can find it without re-discovering the hosting account.

<Steps>

1. **Record the non-secret server mapping in `Zaj-PROJECT.md`.**

   ```bash
   cat <<'EOF' >> Zaj-PROJECT.md

   ## Shared-hosting readiness — <environment> — <YYYY-MM-DD>
   - SSH alias: <SSH_ALIAS>
   - Host/user/port: <host> · <user> · <port>
   - Hosting account: <host/account nickname>
   - Admin-Server status: verified with fresh logs; monitored-paths.conf includes ~/.ssh/authorized_keys and this domain
   - Shared-hosting playbook: completed or previously verified
   EOF
   # Expected: Zaj-PROJECT.md records the reusable non-secret alias/readiness facts.
   ```

   - Expected: `Zaj-PROJECT.md` now carries the alias/readiness state that Phase 4 consumes.

2. **Record personal/machine-only notes in `CLAUDE.local.md` when useful.**

   ```bash
   cat <<'EOF' >> CLAUDE.local.md

   ## Shared-hosting readiness
   - SSH alias: <SSH_ALIAS>
   - Hosting account: <host/account nickname>
   - Admin-Server status: verified with fresh logs on <YYYY-MM-DD>
   - monitored-paths.conf includes: ~/.ssh/authorized_keys and ~/domains/<domain>
   - Shared-hosting playbook: completed or previously verified
   EOF
   # Expected: CLAUDE.local.md records the alias and readiness state without secrets.
   ```

   - Expected: `CLAUDE.local.md` remains gitignored; no webhook URL, password, token, or private key is written into tracked files.

</Steps>

## Checklist

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

- [ ] **🔀 Hosting account chosen** — the app's intended hosting account and SSH alias are known.
- [ ] **🤖 SSH works** — `ssh "$SSH_ALIAS" ...` connects without an interactive password prompt.
- [ ] **🤖 Admin-Server present** — `~/Admin-Server/scripts/status.sh` exists and is executable.
- [ ] **🔀 Shared-hosting setup complete** — first-time accounts completed the shared-hosting playbook before this app moved on.
- [ ] **🤖 Status + liveness clean** — `status.sh` exits 0 and the log freshness probe has no `STALE` rows.
- [ ] **🤖 Integrity baseline covers app** — `~/Admin-Server/config/monitored-paths.conf` includes `~/.ssh/authorized_keys` and this app's `~/domains/<domain>` path, the baseline was regenerated, and the change is committed in the Admin-Server repo.
- [ ] **🤖 Project state updated** — `Zaj-PROJECT.md` records the non-secret alias/readiness state Phase 4 consumes.
- [ ] **🔀 Local note updated** — `CLAUDE.local.md` records any machine-only alias/readiness note and remains gitignored.

:::next[Next step]
[Dev tooling](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/08-dev-tooling/)
:::

# 7 · Shared-hosting readiness

> Source: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/07-shared-hosting-readiness/

## TL;DR

**Objective** — prove the hosting account is ready for deployment before Phase 4 starts. If this server was already prepared, run the Admin-Server status check. If this is the first app on the hosting account, run the shared-hosting playbook first, then come back here and verify it.

**Steps at a glance:**
1. **Choose the hosting account and SSH alias** — Confirm which hosting account this app will deploy to and
   which local SSH alias reaches it. Use the same alias you will use in Phase 4 and Phase 5.
2. **Check whether Admin-Server already exists and is alive** — Run the status script and log-freshness probe if
   the server already has `~/Admin-Server/`. Scripts on disk are not enough; dead cron jobs block Phase 4.
3. **Run the shared-hosting playbook when this account is new** — If the status script is missing or clearly
   incomplete, stop this app playbook and run the shared-hosting playbook for the hosting account.
4. **Record the server readiness note locally** — Write the result where future sessions can find it without
   re-discovering the hosting account.

:::note[For beginners and agents]
This is a real Phase 3 step because Phase 4 assumes the server-wide toolkit already exists. Agents: do not start Deployer until every checklist box here is checked.
:::

## Background

The **[Set up shared hosting](/infrastructure/hosting/shared-hosting/build/playbooks/setup-shared-hosting/)** playbook is once per hosting account, not once per app. It installs the server-wide `~/Admin-Server/` toolkit that later deploy tasks use for deploy webhooks, ops alerts, monitoring scripts, baselines, and server notes.

This page does not duplicate that server playbook. It only decides whether the hosting account is already ready, routes first-time setup to the right place, registers this app's domain path in the integrity baseline, and gives Phase 4 a clean gate.

## Steps

### 1. Choose the hosting account and SSH alias

Confirm which hosting account this app will deploy to and which local SSH alias reaches it. Use the same alias you will use in Phase 4 and Phase 5.

:::note[Who does this]
🔀 **User + Agent** — the user confirms the intended hosting account; the agent can run the SSH checks once the alias is known.
:::

<Steps>

1. **Discover any existing SSH alias before treating SSH as unconfigured.**

   ```bash
   grep -nE '^Host |HostName|User|Port|IdentityFile' ~/.ssh/config 2>/dev/null
   # Match the target hosting IP/domain from Zaj-PROJECT.md or the onboarding summary.
   # Expected: either a reusable Host alias appears, or you know one must be created.
   ```

   - Expected: if an existing alias matches host/user/port, reuse it and record that alias in `Zaj-PROJECT.md`. If it points at an old IP, update the stanza. If no alias exists, return to Phase 2 SSH setup and create one.

2. **Set the alias for this terminal session.**

   ```bash
   export SSH_ALIAS="<selected-hosting-account-ssh-alias>"
   export PHPBIN="${PHPBIN:-php}" # replace with /opt/alt/phpXX/usr/bin/php once Phase 4 confirms it
   ssh -o BatchMode=yes -o ConnectTimeout=8 "$SSH_ALIAS" "pwd && $PHPBIN -v | head -1"
   # Expected: SSH connects without an interactive password prompt and prints a remote path plus PHP version.
   ```

   - Expected: the command exits `0`; a timeout, password prompt, or unknown host means SSH is not ready for Phase 4.

</Steps>

### 2. Check whether Admin-Server already exists and is alive

Run the status script and freshness probe if the server already has `~/Admin-Server/`. This is the fast path for a hosting account that was prepared by a previous project — but only if the cron-backed logs are fresh.

<Steps>

1. **Run the status and freshness check.**

   ```bash
   ssh "$SSH_ALIAS" 'bash -s' <<'REMOTE'
   set -euo pipefail
   cd ~/Admin-Server
   test -x scripts/status.sh
   ./scripts/status.sh
   now=$(date +%s)

   check_log() {
     label="$1"; path="$2"; max_age="$3"
     if [ ! -f "$path" ]; then echo "❌ STALE $label — missing $path"; exit 1; fi
     mtime=$(stat -c %Y "$path")
     age=$((now - mtime))
     if [ "$age" -gt "$max_age" ]; then
       echo "❌ STALE $label — last run $(date -d "@$mtime" -Is), age ${age}s, max ${max_age}s"; exit 1
     fi
     echo "✅ fresh $label — last run $(date -d "@$mtime" -Is)"
   }

   check_any_log() {
     label="$1"; max_age="$2"; shift 2
     for path in "$@"; do
       [ -f "$path" ] && check_log "$label" "$path" "$max_age" && return 0
     done
     echo "❌ STALE $label — missing expected log: $*"; exit 1
   }

   check_any_log "config snapshot"   172800  logs/snapshot-config.log
   check_any_log "integrity"         172800  logs/integrity.log logs/integrity-check.log
   check_any_log "disk/inode"         43200  logs/resource.log logs/resources.log logs/resource-check.log
   check_any_log "PHP error scan"     43200  logs/error-log.log logs/error-log-check.log
   check_any_log "domain inventory" 2592000  logs/domain-inventory.log
   check_any_log "log rotation"     1209600  logs/rotate-logs.log
   REMOTE
   # Expected: status.sh exits 0 and every log row prints "fresh"; any STALE row blocks Phase 4.
   ```

   - Expected: the script runs and every log freshness row passes. If the file is missing, not executable, reports missing setup, or prints `STALE`, continue to step 3 and fix the shared-hosting playbook before Phase 4.

2. **Add this app's domain path to the Admin-Server integrity baseline.**

   ```bash
   APP_DOMAIN="<selected-domain-from-Zaj-PROJECT>"
   ssh "$SSH_ALIAS" "APP_DOMAIN='$APP_DOMAIN' bash -s" <<'REMOTE'
   set -euo pipefail
   cd ~/Admin-Server
   path="$HOME/domains/$APP_DOMAIN"
   conf="config/monitored-paths.conf"
   touch "$conf"
   for monitored in "$HOME/.ssh/authorized_keys" "$path"; do
     grep -Fxq "$monitored" "$conf" 2>/dev/null || printf '%s\n' "$monitored" >> "$conf"
     grep -Fx "$monitored" "$conf"
   done
   ./scripts/generate-baseline.sh
   git add "$conf" baselines/checksums.md5
   git diff --cached --quiet || git commit -m "Monitor $APP_DOMAIN domain path"
   REMOTE
   # Expected: monitored-paths.conf contains authorized_keys + the app domain path; baseline regenerated.
   ```

   - Expected: `~/.ssh/authorized_keys` and the domain path are present in `monitored-paths.conf`, so integrity monitoring catches planted SSH keys and app-path drift once the app is deployed.

</Steps>

### 3. Run the shared-hosting playbook when this account is new

If the status script is missing or clearly incomplete, stop this app playbook and run the shared-hosting playbook for the hosting account. Return here only after that server playbook reaches its checklist.

:::note[Who does this]
🔀 **User + Agent** — the shared-hosting playbook may require hosting-panel access, webhook secrets, or account-level choices. Do not paste secrets into chat.
:::

<Steps>

1. **Open and complete the shared-hosting playbook.**

   - [Set up shared hosting](/infrastructure/hosting/shared-hosting/build/playbooks/setup-shared-hosting/)

   - Expected: the hosting account has `~/Admin-Server/`, executable scripts, configured monitoring/alert state, and a documented SSH alias.

2. **Re-run the status + freshness check after setup.**

   ```bash
   ssh "$SSH_ALIAS" '~/Admin-Server/scripts/status.sh'
   # Expected: status.sh shows the correct identity. Then rerun step 2's freshness probe and require no STALE rows.
   ```

   - Expected: no missing Admin-Server toolkit and no stale cron-backed logs. Fix failed checks in the shared-hosting playbook before continuing.

</Steps>

### 4. Record the server readiness note

Write the result where future sessions can find it without re-discovering the hosting account.

<Steps>

1. **Record the non-secret server mapping in `Zaj-PROJECT.md`.**

   ```bash
   cat <<'EOF' >> Zaj-PROJECT.md

   ## Shared-hosting readiness — <environment> — <YYYY-MM-DD>
   - SSH alias: <SSH_ALIAS>
   - Host/user/port: <host> · <user> · <port>
   - Hosting account: <host/account nickname>
   - Admin-Server status: verified with fresh logs; monitored-paths.conf includes ~/.ssh/authorized_keys and this domain
   - Shared-hosting playbook: completed or previously verified
   EOF
   # Expected: Zaj-PROJECT.md records the reusable non-secret alias/readiness facts.
   ```

   - Expected: `Zaj-PROJECT.md` now carries the alias/readiness state that Phase 4 consumes.

2. **Record personal/machine-only notes in `CLAUDE.local.md` when useful.**

   ```bash
   cat <<'EOF' >> CLAUDE.local.md

   ## Shared-hosting readiness
   - SSH alias: <SSH_ALIAS>
   - Hosting account: <host/account nickname>
   - Admin-Server status: verified with fresh logs on <YYYY-MM-DD>
   - monitored-paths.conf includes: ~/.ssh/authorized_keys and ~/domains/<domain>
   - Shared-hosting playbook: completed or previously verified
   EOF
   # Expected: CLAUDE.local.md records the alias and readiness state without secrets.
   ```

   - Expected: `CLAUDE.local.md` remains gitignored; no webhook URL, password, token, or private key is written into tracked files.

</Steps>

## Checklist

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

- [ ] **🔀 Hosting account chosen** — the app's intended hosting account and SSH alias are known.
- [ ] **🤖 SSH works** — `ssh "$SSH_ALIAS" ...` connects without an interactive password prompt.
- [ ] **🤖 Admin-Server present** — `~/Admin-Server/scripts/status.sh` exists and is executable.
- [ ] **🔀 Shared-hosting setup complete** — first-time accounts completed the shared-hosting playbook before this app moved on.
- [ ] **🤖 Status + liveness clean** — `status.sh` exits 0 and the log freshness probe has no `STALE` rows.
- [ ] **🤖 Integrity baseline covers app** — `~/Admin-Server/config/monitored-paths.conf` includes `~/.ssh/authorized_keys` and this app's `~/domains/<domain>` path, the baseline was regenerated, and the change is committed in the Admin-Server repo.
- [ ] **🤖 Project state updated** — `Zaj-PROJECT.md` records the non-secret alias/readiness state Phase 4 consumes.
- [ ] **🔀 Local note updated** — `CLAUDE.local.md` records any machine-only alias/readiness note and remains gitignored.

:::next[Next step]
[Dev tooling](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/08-dev-tooling/)
:::

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 — prove the hosting account is ready for deployment before Phase 4 starts. If this server was already prepared, run the Admin-Server status check. If this is the first app on the hosting account, run the shared-hosting playbook first, then come back here and verify it.

Steps at a glance:

Choose the hosting account and SSH alias — Confirm which hosting account this app will deploy to and which local SSH alias reaches it. Use the same alias you will use in Phase 4 and Phase 5.
Check whether Admin-Server already exists and is alive — Run the status script and log-freshness probe if the server already has ~/Admin-Server/. Scripts on disk are not enough; dead cron jobs block Phase 4.
Run the shared-hosting playbook when this account is new — If the status script is missing or clearly incomplete, stop this app playbook and run the shared-hosting playbook for the hosting account.
Record the server readiness note locally — Write the result where future sessions can find it without re-discovering the hosting account.

Background

The Set up shared hosting playbook is once per hosting account, not once per app. It installs the server-wide ~/Admin-Server/ toolkit that later deploy tasks use for deploy webhooks, ops alerts, monitoring scripts, baselines, and server notes.

This page does not duplicate that server playbook. It only decides whether the hosting account is already ready, routes first-time setup to the right place, registers this app’s domain path in the integrity baseline, and gives Phase 4 a clean gate.

Steps

1. Choose the hosting account and SSH alias

Confirm which hosting account this app will deploy to and which local SSH alias reaches it. Use the same alias you will use in Phase 4 and Phase 5.

Discover any existing SSH alias before treating SSH as unconfigured.
Terminal window
```
grep -nE '^Host |HostName|User|Port|IdentityFile' ~/.ssh/config 2>/dev/null
# Match the target hosting IP/domain from Zaj-PROJECT.md or the onboarding summary.
# Expected: either a reusable Host alias appears, or you know one must be created.
```
- Expected: if an existing alias matches host/user/port, reuse it and record that alias in Zaj-PROJECT.md. If it points at an old IP, update the stanza. If no alias exists, return to Phase 2 SSH setup and create one.

Set the alias for this terminal session.

export SSH_ALIAS="<selected-hosting-account-ssh-alias>"
export PHPBIN="${PHPBIN:-php}" # replace with /opt/alt/phpXX/usr/bin/php once Phase 4 confirms it
ssh -o BatchMode=yes -o ConnectTimeout=8 "$SSH_ALIAS" "pwd && $PHPBIN -v | head -1"
# Expected: SSH connects without an interactive password prompt and prints a remote path plus PHP version.

Expected: the command exits 0; a timeout, password prompt, or unknown host means SSH is not ready for Phase 4.

2. Check whether Admin-Server already exists and is alive

Run the status script and freshness probe if the server already has ~/Admin-Server/. This is the fast path for a hosting account that was prepared by a previous project — but only if the cron-backed logs are fresh.

Run the status and freshness check.

ssh "$SSH_ALIAS" 'bash -s' <<'REMOTE'
set -euo pipefail
cd ~/Admin-Server
test -x scripts/status.sh
./scripts/status.sh
now=$(date +%s)

check_log() {
  label="$1"; path="$2"; max_age="$3"
  if [ ! -f "$path" ]; then echo "❌ STALE $label — missing $path"; exit 1; fi
  mtime=$(stat -c %Y "$path")
  age=$((now - mtime))
  if [ "$age" -gt "$max_age" ]; then
    echo "❌ STALE $label — last run $(date -d "@$mtime" -Is), age ${age}s, max ${max_age}s"; exit 1
  fi
  echo "✅ fresh $label — last run $(date -d "@$mtime" -Is)"
}

check_any_log() {
  label="$1"; max_age="$2"; shift 2
  for path in "$@"; do
    [ -f "$path" ] && check_log "$label" "$path" "$max_age" && return 0
  done
  echo "❌ STALE $label — missing expected log: $*"; exit 1
}

check_any_log "config snapshot"   172800  logs/snapshot-config.log
check_any_log "integrity"         172800  logs/integrity.log logs/integrity-check.log
check_any_log "disk/inode"         43200  logs/resource.log logs/resources.log logs/resource-check.log
check_any_log "PHP error scan"     43200  logs/error-log.log logs/error-log-check.log
check_any_log "domain inventory" 2592000  logs/domain-inventory.log
check_any_log "log rotation"     1209600  logs/rotate-logs.log
REMOTE
# Expected: status.sh exits 0 and every log row prints "fresh"; any STALE row blocks Phase 4.

Expected: the script runs and every log freshness row passes. If the file is missing, not executable, reports missing setup, or prints STALE, continue to step 3 and fix the shared-hosting playbook before Phase 4.

Add this app’s domain path to the Admin-Server integrity baseline.

APP_DOMAIN="<selected-domain-from-Zaj-PROJECT>"
ssh "$SSH_ALIAS" "APP_DOMAIN='$APP_DOMAIN' bash -s" <<'REMOTE'
set -euo pipefail
cd ~/Admin-Server
path="$HOME/domains/$APP_DOMAIN"
conf="config/monitored-paths.conf"
touch "$conf"
for monitored in "$HOME/.ssh/authorized_keys" "$path"; do
  grep -Fxq "$monitored" "$conf" 2>/dev/null || printf '%s\n' "$monitored" >> "$conf"
  grep -Fx "$monitored" "$conf"
done
./scripts/generate-baseline.sh
git add "$conf" baselines/checksums.md5
git diff --cached --quiet || git commit -m "Monitor $APP_DOMAIN domain path"
REMOTE
# Expected: monitored-paths.conf contains authorized_keys + the app domain path; baseline regenerated.

Expected: ~/.ssh/authorized_keys and the domain path are present in monitored-paths.conf, so integrity monitoring catches planted SSH keys and app-path drift once the app is deployed.

3. Run the shared-hosting playbook when this account is new

If the status script is missing or clearly incomplete, stop this app playbook and run the shared-hosting playbook for the hosting account. Return here only after that server playbook reaches its checklist.

Open and complete the shared-hosting playbook.
- Set up shared hosting
- Expected: the hosting account has ~/Admin-Server/, executable scripts, configured monitoring/alert state, and a documented SSH alias.
Re-run the status + freshness check after setup.
Terminal window
```
ssh "$SSH_ALIAS" '~/Admin-Server/scripts/status.sh'
# Expected: status.sh shows the correct identity. Then rerun step 2's freshness probe and require no STALE rows.
```
- Expected: no missing Admin-Server toolkit and no stale cron-backed logs. Fix failed checks in the shared-hosting playbook before continuing.

4. Record the server readiness note

Write the result where future sessions can find it without re-discovering the hosting account.

Record the non-secret server mapping in Zaj-PROJECT.md.

cat <<'EOF' >> Zaj-PROJECT.md

## Shared-hosting readiness — <environment> — <YYYY-MM-DD>
- SSH alias: <SSH_ALIAS>
- Host/user/port: <host> · <user> · <port>
- Hosting account: <host/account nickname>
- Admin-Server status: verified with fresh logs; monitored-paths.conf includes ~/.ssh/authorized_keys and this domain
- Shared-hosting playbook: completed or previously verified
EOF
# Expected: Zaj-PROJECT.md records the reusable non-secret alias/readiness facts.

Expected: Zaj-PROJECT.md now carries the alias/readiness state that Phase 4 consumes.

Record personal/machine-only notes in CLAUDE.local.md when useful.

cat <<'EOF' >> CLAUDE.local.md

## Shared-hosting readiness
- SSH alias: <SSH_ALIAS>
- Hosting account: <host/account nickname>
- Admin-Server status: verified with fresh logs on <YYYY-MM-DD>
- monitored-paths.conf includes: ~/.ssh/authorized_keys and ~/domains/<domain>
- Shared-hosting playbook: completed or previously verified
EOF
# Expected: CLAUDE.local.md records the alias and readiness state without secrets.

Expected: CLAUDE.local.md remains gitignored; no webhook URL, password, token, or private key is written into tracked files.

Checklist

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

🔀 Hosting account chosen — the app’s intended hosting account and SSH alias are known.
🤖 SSH works — ssh "$SSH_ALIAS" ... connects without an interactive password prompt.
🤖 Admin-Server present — ~/Admin-Server/scripts/status.sh exists and is executable.
🔀 Shared-hosting setup complete — first-time accounts completed the shared-hosting playbook before this app moved on.
🤖 Status + liveness clean — status.sh exits 0 and the log freshness probe has no STALE rows.
🤖 Integrity baseline covers app — ~/Admin-Server/config/monitored-paths.conf includes ~/.ssh/authorized_keys and this app’s ~/domains/<domain> path, the baseline was regenerated, and the change is committed in the Admin-Server repo.
🤖 Project state updated — Zaj-PROJECT.md records the non-secret alias/readiness state Phase 4 consumes.
🔀 Local note updated — CLAUDE.local.md records any machine-only alias/readiness note and remains gitignored.

Dev tooling

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: 7 · Shared-hosting readiness
- url: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/07-shared-hosting-readiness/
- shelf: Build & Create
- doc_type: implementation playbook
- status: current
- kind: playbook
- category: tech-stack
- subcategory: laravel
- topic: codecanyon
- phase: 3
- part_number: 7 (legacy stepNumber frontmatter)
- legacy_step_number: 7
- est_time: ~10-45 min
- description: Verify that the hosting account has the Admin-Server toolkit before the deploy pipeline starts, or run the shared-hosting playbook first.
- tags: codecanyon, laravel, hosting, deploy

## Execution rules (binding)
- This is Part 7 of phase 3 (~10-45 min) — 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.

---

# 7 · Shared-hosting readiness

## TL;DR

**Objective** — prove the hosting account is ready for deployment before Phase 4 starts. If this server was already prepared, run the Admin-Server status check. If this is the first app on the hosting account, run the shared-hosting playbook first, then come back here and verify it.

**Steps at a glance:**
1. **Choose the hosting account and SSH alias** — Confirm which hosting account this app will deploy to and
   which local SSH alias reaches it. Use the same alias you will use in Phase 4 and Phase 5.
2. **Check whether Admin-Server already exists and is alive** — Run the status script and log-freshness probe if
   the server already has `~/Admin-Server/`. Scripts on disk are not enough; dead cron jobs block Phase 4.
3. **Run the shared-hosting playbook when this account is new** — If the status script is missing or clearly
   incomplete, stop this app playbook and run the shared-hosting playbook for the hosting account.
4. **Record the server readiness note locally** — Write the result where future sessions can find it without
   re-discovering the hosting account.

:::note[For beginners and agents]
This is a real Phase 3 step because Phase 4 assumes the server-wide toolkit already exists. Agents: do not start Deployer until every checklist box here is checked.
:::

## Background

The **[Set up shared hosting](/infrastructure/hosting/shared-hosting/build/playbooks/setup-shared-hosting/)** playbook is once per hosting account, not once per app. It installs the server-wide `~/Admin-Server/` toolkit that later deploy tasks use for deploy webhooks, ops alerts, monitoring scripts, baselines, and server notes.

This page does not duplicate that server playbook. It only decides whether the hosting account is already ready, routes first-time setup to the right place, registers this app's domain path in the integrity baseline, and gives Phase 4 a clean gate.

## Steps

### 1. Choose the hosting account and SSH alias

Confirm which hosting account this app will deploy to and which local SSH alias reaches it. Use the same alias you will use in Phase 4 and Phase 5.

:::note[Who does this]
🔀 **User + Agent** — the user confirms the intended hosting account; the agent can run the SSH checks once the alias is known.
:::

<Steps>

1. **Discover any existing SSH alias before treating SSH as unconfigured.**

   ```bash
   grep -nE '^Host |HostName|User|Port|IdentityFile' ~/.ssh/config 2>/dev/null
   # Match the target hosting IP/domain from Zaj-PROJECT.md or the onboarding summary.
   # Expected: either a reusable Host alias appears, or you know one must be created.
   ```

   - Expected: if an existing alias matches host/user/port, reuse it and record that alias in `Zaj-PROJECT.md`. If it points at an old IP, update the stanza. If no alias exists, return to Phase 2 SSH setup and create one.

2. **Set the alias for this terminal session.**

   ```bash
   export SSH_ALIAS="<selected-hosting-account-ssh-alias>"
   export PHPBIN="${PHPBIN:-php}" # replace with /opt/alt/phpXX/usr/bin/php once Phase 4 confirms it
   ssh -o BatchMode=yes -o ConnectTimeout=8 "$SSH_ALIAS" "pwd && $PHPBIN -v | head -1"
   # Expected: SSH connects without an interactive password prompt and prints a remote path plus PHP version.
   ```

   - Expected: the command exits `0`; a timeout, password prompt, or unknown host means SSH is not ready for Phase 4.

</Steps>

### 2. Check whether Admin-Server already exists and is alive

Run the status script and freshness probe if the server already has `~/Admin-Server/`. This is the fast path for a hosting account that was prepared by a previous project — but only if the cron-backed logs are fresh.

<Steps>

1. **Run the status and freshness check.**

   ```bash
   ssh "$SSH_ALIAS" 'bash -s' <<'REMOTE'
   set -euo pipefail
   cd ~/Admin-Server
   test -x scripts/status.sh
   ./scripts/status.sh
   now=$(date +%s)

   check_log() {
     label="$1"; path="$2"; max_age="$3"
     if [ ! -f "$path" ]; then echo "❌ STALE $label — missing $path"; exit 1; fi
     mtime=$(stat -c %Y "$path")
     age=$((now - mtime))
     if [ "$age" -gt "$max_age" ]; then
       echo "❌ STALE $label — last run $(date -d "@$mtime" -Is), age ${age}s, max ${max_age}s"; exit 1
     fi
     echo "✅ fresh $label — last run $(date -d "@$mtime" -Is)"
   }

   check_any_log() {
     label="$1"; max_age="$2"; shift 2
     for path in "$@"; do
       [ -f "$path" ] && check_log "$label" "$path" "$max_age" && return 0
     done
     echo "❌ STALE $label — missing expected log: $*"; exit 1
   }

   check_any_log "config snapshot"   172800  logs/snapshot-config.log
   check_any_log "integrity"         172800  logs/integrity.log logs/integrity-check.log
   check_any_log "disk/inode"         43200  logs/resource.log logs/resources.log logs/resource-check.log
   check_any_log "PHP error scan"     43200  logs/error-log.log logs/error-log-check.log
   check_any_log "domain inventory" 2592000  logs/domain-inventory.log
   check_any_log "log rotation"     1209600  logs/rotate-logs.log
   REMOTE
   # Expected: status.sh exits 0 and every log row prints "fresh"; any STALE row blocks Phase 4.
   ```

   - Expected: the script runs and every log freshness row passes. If the file is missing, not executable, reports missing setup, or prints `STALE`, continue to step 3 and fix the shared-hosting playbook before Phase 4.

2. **Add this app's domain path to the Admin-Server integrity baseline.**

   ```bash
   APP_DOMAIN="<selected-domain-from-Zaj-PROJECT>"
   ssh "$SSH_ALIAS" "APP_DOMAIN='$APP_DOMAIN' bash -s" <<'REMOTE'
   set -euo pipefail
   cd ~/Admin-Server
   path="$HOME/domains/$APP_DOMAIN"
   conf="config/monitored-paths.conf"
   touch "$conf"
   for monitored in "$HOME/.ssh/authorized_keys" "$path"; do
     grep -Fxq "$monitored" "$conf" 2>/dev/null || printf '%s\n' "$monitored" >> "$conf"
     grep -Fx "$monitored" "$conf"
   done
   ./scripts/generate-baseline.sh
   git add "$conf" baselines/checksums.md5
   git diff --cached --quiet || git commit -m "Monitor $APP_DOMAIN domain path"
   REMOTE
   # Expected: monitored-paths.conf contains authorized_keys + the app domain path; baseline regenerated.
   ```

   - Expected: `~/.ssh/authorized_keys` and the domain path are present in `monitored-paths.conf`, so integrity monitoring catches planted SSH keys and app-path drift once the app is deployed.

</Steps>

### 3. Run the shared-hosting playbook when this account is new

If the status script is missing or clearly incomplete, stop this app playbook and run the shared-hosting playbook for the hosting account. Return here only after that server playbook reaches its checklist.

:::note[Who does this]
🔀 **User + Agent** — the shared-hosting playbook may require hosting-panel access, webhook secrets, or account-level choices. Do not paste secrets into chat.
:::

<Steps>

1. **Open and complete the shared-hosting playbook.**

   - [Set up shared hosting](/infrastructure/hosting/shared-hosting/build/playbooks/setup-shared-hosting/)

   - Expected: the hosting account has `~/Admin-Server/`, executable scripts, configured monitoring/alert state, and a documented SSH alias.

2. **Re-run the status + freshness check after setup.**

   ```bash
   ssh "$SSH_ALIAS" '~/Admin-Server/scripts/status.sh'
   # Expected: status.sh shows the correct identity. Then rerun step 2's freshness probe and require no STALE rows.
   ```

   - Expected: no missing Admin-Server toolkit and no stale cron-backed logs. Fix failed checks in the shared-hosting playbook before continuing.

</Steps>

### 4. Record the server readiness note

Write the result where future sessions can find it without re-discovering the hosting account.

<Steps>

1. **Record the non-secret server mapping in `Zaj-PROJECT.md`.**

   ```bash
   cat <<'EOF' >> Zaj-PROJECT.md

   ## Shared-hosting readiness — <environment> — <YYYY-MM-DD>
   - SSH alias: <SSH_ALIAS>
   - Host/user/port: <host> · <user> · <port>
   - Hosting account: <host/account nickname>
   - Admin-Server status: verified with fresh logs; monitored-paths.conf includes ~/.ssh/authorized_keys and this domain
   - Shared-hosting playbook: completed or previously verified
   EOF
   # Expected: Zaj-PROJECT.md records the reusable non-secret alias/readiness facts.
   ```

   - Expected: `Zaj-PROJECT.md` now carries the alias/readiness state that Phase 4 consumes.

2. **Record personal/machine-only notes in `CLAUDE.local.md` when useful.**

   ```bash
   cat <<'EOF' >> CLAUDE.local.md

   ## Shared-hosting readiness
   - SSH alias: <SSH_ALIAS>
   - Hosting account: <host/account nickname>
   - Admin-Server status: verified with fresh logs on <YYYY-MM-DD>
   - monitored-paths.conf includes: ~/.ssh/authorized_keys and ~/domains/<domain>
   - Shared-hosting playbook: completed or previously verified
   EOF
   # Expected: CLAUDE.local.md records the alias and readiness state without secrets.
   ```

   - Expected: `CLAUDE.local.md` remains gitignored; no webhook URL, password, token, or private key is written into tracked files.

</Steps>

## Checklist

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

- [ ] **🔀 Hosting account chosen** — the app's intended hosting account and SSH alias are known.
- [ ] **🤖 SSH works** — `ssh "$SSH_ALIAS" ...` connects without an interactive password prompt.
- [ ] **🤖 Admin-Server present** — `~/Admin-Server/scripts/status.sh` exists and is executable.
- [ ] **🔀 Shared-hosting setup complete** — first-time accounts completed the shared-hosting playbook before this app moved on.
- [ ] **🤖 Status + liveness clean** — `status.sh` exits 0 and the log freshness probe has no `STALE` rows.
- [ ] **🤖 Integrity baseline covers app** — `~/Admin-Server/config/monitored-paths.conf` includes `~/.ssh/authorized_keys` and this app's `~/domains/<domain>` path, the baseline was regenerated, and the change is committed in the Admin-Server repo.
- [ ] **🤖 Project state updated** — `Zaj-PROJECT.md` records the non-secret alias/readiness state Phase 4 consumes.
- [ ] **🔀 Local note updated** — `CLAUDE.local.md` records any machine-only alias/readiness note and remains gitignored.

:::next[Next step]
[Dev tooling](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/08-dev-tooling/)
:::

# 7 · Shared-hosting readiness

> Source: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/07-shared-hosting-readiness/

## TL;DR

**Objective** — prove the hosting account is ready for deployment before Phase 4 starts. If this server was already prepared, run the Admin-Server status check. If this is the first app on the hosting account, run the shared-hosting playbook first, then come back here and verify it.

**Steps at a glance:**
1. **Choose the hosting account and SSH alias** — Confirm which hosting account this app will deploy to and
   which local SSH alias reaches it. Use the same alias you will use in Phase 4 and Phase 5.
2. **Check whether Admin-Server already exists and is alive** — Run the status script and log-freshness probe if
   the server already has `~/Admin-Server/`. Scripts on disk are not enough; dead cron jobs block Phase 4.
3. **Run the shared-hosting playbook when this account is new** — If the status script is missing or clearly
   incomplete, stop this app playbook and run the shared-hosting playbook for the hosting account.
4. **Record the server readiness note locally** — Write the result where future sessions can find it without
   re-discovering the hosting account.

:::note[For beginners and agents]
This is a real Phase 3 step because Phase 4 assumes the server-wide toolkit already exists. Agents: do not start Deployer until every checklist box here is checked.
:::

## Background

The **[Set up shared hosting](/infrastructure/hosting/shared-hosting/build/playbooks/setup-shared-hosting/)** playbook is once per hosting account, not once per app. It installs the server-wide `~/Admin-Server/` toolkit that later deploy tasks use for deploy webhooks, ops alerts, monitoring scripts, baselines, and server notes.

This page does not duplicate that server playbook. It only decides whether the hosting account is already ready, routes first-time setup to the right place, registers this app's domain path in the integrity baseline, and gives Phase 4 a clean gate.

## Steps

### 1. Choose the hosting account and SSH alias

Confirm which hosting account this app will deploy to and which local SSH alias reaches it. Use the same alias you will use in Phase 4 and Phase 5.

:::note[Who does this]
🔀 **User + Agent** — the user confirms the intended hosting account; the agent can run the SSH checks once the alias is known.
:::

<Steps>

1. **Discover any existing SSH alias before treating SSH as unconfigured.**

   ```bash
   grep -nE '^Host |HostName|User|Port|IdentityFile' ~/.ssh/config 2>/dev/null
   # Match the target hosting IP/domain from Zaj-PROJECT.md or the onboarding summary.
   # Expected: either a reusable Host alias appears, or you know one must be created.
   ```

   - Expected: if an existing alias matches host/user/port, reuse it and record that alias in `Zaj-PROJECT.md`. If it points at an old IP, update the stanza. If no alias exists, return to Phase 2 SSH setup and create one.

2. **Set the alias for this terminal session.**

   ```bash
   export SSH_ALIAS="<selected-hosting-account-ssh-alias>"
   export PHPBIN="${PHPBIN:-php}" # replace with /opt/alt/phpXX/usr/bin/php once Phase 4 confirms it
   ssh -o BatchMode=yes -o ConnectTimeout=8 "$SSH_ALIAS" "pwd && $PHPBIN -v | head -1"
   # Expected: SSH connects without an interactive password prompt and prints a remote path plus PHP version.
   ```

   - Expected: the command exits `0`; a timeout, password prompt, or unknown host means SSH is not ready for Phase 4.

</Steps>

### 2. Check whether Admin-Server already exists and is alive

Run the status script and freshness probe if the server already has `~/Admin-Server/`. This is the fast path for a hosting account that was prepared by a previous project — but only if the cron-backed logs are fresh.

<Steps>

1. **Run the status and freshness check.**

   ```bash
   ssh "$SSH_ALIAS" 'bash -s' <<'REMOTE'
   set -euo pipefail
   cd ~/Admin-Server
   test -x scripts/status.sh
   ./scripts/status.sh
   now=$(date +%s)

   check_log() {
     label="$1"; path="$2"; max_age="$3"
     if [ ! -f "$path" ]; then echo "❌ STALE $label — missing $path"; exit 1; fi
     mtime=$(stat -c %Y "$path")
     age=$((now - mtime))
     if [ "$age" -gt "$max_age" ]; then
       echo "❌ STALE $label — last run $(date -d "@$mtime" -Is), age ${age}s, max ${max_age}s"; exit 1
     fi
     echo "✅ fresh $label — last run $(date -d "@$mtime" -Is)"
   }

   check_any_log() {
     label="$1"; max_age="$2"; shift 2
     for path in "$@"; do
       [ -f "$path" ] && check_log "$label" "$path" "$max_age" && return 0
     done
     echo "❌ STALE $label — missing expected log: $*"; exit 1
   }

   check_any_log "config snapshot"   172800  logs/snapshot-config.log
   check_any_log "integrity"         172800  logs/integrity.log logs/integrity-check.log
   check_any_log "disk/inode"         43200  logs/resource.log logs/resources.log logs/resource-check.log
   check_any_log "PHP error scan"     43200  logs/error-log.log logs/error-log-check.log
   check_any_log "domain inventory" 2592000  logs/domain-inventory.log
   check_any_log "log rotation"     1209600  logs/rotate-logs.log
   REMOTE
   # Expected: status.sh exits 0 and every log row prints "fresh"; any STALE row blocks Phase 4.
   ```

   - Expected: the script runs and every log freshness row passes. If the file is missing, not executable, reports missing setup, or prints `STALE`, continue to step 3 and fix the shared-hosting playbook before Phase 4.

2. **Add this app's domain path to the Admin-Server integrity baseline.**

   ```bash
   APP_DOMAIN="<selected-domain-from-Zaj-PROJECT>"
   ssh "$SSH_ALIAS" "APP_DOMAIN='$APP_DOMAIN' bash -s" <<'REMOTE'
   set -euo pipefail
   cd ~/Admin-Server
   path="$HOME/domains/$APP_DOMAIN"
   conf="config/monitored-paths.conf"
   touch "$conf"
   for monitored in "$HOME/.ssh/authorized_keys" "$path"; do
     grep -Fxq "$monitored" "$conf" 2>/dev/null || printf '%s\n' "$monitored" >> "$conf"
     grep -Fx "$monitored" "$conf"
   done
   ./scripts/generate-baseline.sh
   git add "$conf" baselines/checksums.md5
   git diff --cached --quiet || git commit -m "Monitor $APP_DOMAIN domain path"
   REMOTE
   # Expected: monitored-paths.conf contains authorized_keys + the app domain path; baseline regenerated.
   ```

   - Expected: `~/.ssh/authorized_keys` and the domain path are present in `monitored-paths.conf`, so integrity monitoring catches planted SSH keys and app-path drift once the app is deployed.

</Steps>

### 3. Run the shared-hosting playbook when this account is new

If the status script is missing or clearly incomplete, stop this app playbook and run the shared-hosting playbook for the hosting account. Return here only after that server playbook reaches its checklist.

:::note[Who does this]
🔀 **User + Agent** — the shared-hosting playbook may require hosting-panel access, webhook secrets, or account-level choices. Do not paste secrets into chat.
:::

<Steps>

1. **Open and complete the shared-hosting playbook.**

   - [Set up shared hosting](/infrastructure/hosting/shared-hosting/build/playbooks/setup-shared-hosting/)

   - Expected: the hosting account has `~/Admin-Server/`, executable scripts, configured monitoring/alert state, and a documented SSH alias.

2. **Re-run the status + freshness check after setup.**

   ```bash
   ssh "$SSH_ALIAS" '~/Admin-Server/scripts/status.sh'
   # Expected: status.sh shows the correct identity. Then rerun step 2's freshness probe and require no STALE rows.
   ```

   - Expected: no missing Admin-Server toolkit and no stale cron-backed logs. Fix failed checks in the shared-hosting playbook before continuing.

</Steps>

### 4. Record the server readiness note

Write the result where future sessions can find it without re-discovering the hosting account.

<Steps>

1. **Record the non-secret server mapping in `Zaj-PROJECT.md`.**

   ```bash
   cat <<'EOF' >> Zaj-PROJECT.md

   ## Shared-hosting readiness — <environment> — <YYYY-MM-DD>
   - SSH alias: <SSH_ALIAS>
   - Host/user/port: <host> · <user> · <port>
   - Hosting account: <host/account nickname>
   - Admin-Server status: verified with fresh logs; monitored-paths.conf includes ~/.ssh/authorized_keys and this domain
   - Shared-hosting playbook: completed or previously verified
   EOF
   # Expected: Zaj-PROJECT.md records the reusable non-secret alias/readiness facts.
   ```

   - Expected: `Zaj-PROJECT.md` now carries the alias/readiness state that Phase 4 consumes.

2. **Record personal/machine-only notes in `CLAUDE.local.md` when useful.**

   ```bash
   cat <<'EOF' >> CLAUDE.local.md

   ## Shared-hosting readiness
   - SSH alias: <SSH_ALIAS>
   - Hosting account: <host/account nickname>
   - Admin-Server status: verified with fresh logs on <YYYY-MM-DD>
   - monitored-paths.conf includes: ~/.ssh/authorized_keys and ~/domains/<domain>
   - Shared-hosting playbook: completed or previously verified
   EOF
   # Expected: CLAUDE.local.md records the alias and readiness state without secrets.
   ```

   - Expected: `CLAUDE.local.md` remains gitignored; no webhook URL, password, token, or private key is written into tracked files.

</Steps>

## Checklist

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

- [ ] **🔀 Hosting account chosen** — the app's intended hosting account and SSH alias are known.
- [ ] **🤖 SSH works** — `ssh "$SSH_ALIAS" ...` connects without an interactive password prompt.
- [ ] **🤖 Admin-Server present** — `~/Admin-Server/scripts/status.sh` exists and is executable.
- [ ] **🔀 Shared-hosting setup complete** — first-time accounts completed the shared-hosting playbook before this app moved on.
- [ ] **🤖 Status + liveness clean** — `status.sh` exits 0 and the log freshness probe has no `STALE` rows.
- [ ] **🤖 Integrity baseline covers app** — `~/Admin-Server/config/monitored-paths.conf` includes `~/.ssh/authorized_keys` and this app's `~/domains/<domain>` path, the baseline was regenerated, and the change is committed in the Admin-Server repo.
- [ ] **🤖 Project state updated** — `Zaj-PROJECT.md` records the non-secret alias/readiness state Phase 4 consumes.
- [ ] **🔀 Local note updated** — `CLAUDE.local.md` records any machine-only alias/readiness note and remains gitignored.

:::next[Next step]
[Dev tooling](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/08-dev-tooling/)
:::