7 · Project standards (recommended)

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 · Project standards (recommended)
- url: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/02-code-repo/07-project-standards/
- shelf: Build & Create
- doc_type: implementation playbook
- status: current
- kind: playbook
- category: tech-stack
- subcategory: laravel
- topic: codecanyon
- phase: 2
- part_number: 7 (legacy stepNumber frontmatter)
- legacy_step_number: 7
- est_time: ~20–40 min if adopted
- description: Project-structure scaffolding (Admin-Local vault + docs), commit & documentation standards with the Zaj customization strategy, and version management (SemVer + Zaj-CHANGELOG) — SHOULD, not skip-by-default.
- tags: codecanyon, laravel, project-standards, versioning

## Execution rules (binding)
- This is Part 7 of phase 2 (~20–40 min if adopted) — 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 · Project standards (recommended)

## TL;DR

**Objective** — surface three **SHOULD-not-skip** topics (project structure, commit + doc standards with the Zaj customization strategy, and SemVer + Zaj-CHANGELOG version management) and capture the operator's decision on each — never silently drop them.

**Steps at a glance:**
1. **Decide which topics to adopt** — Present all three to the operator and record each choice in the project
   log before scaffolding anything.
2. **Scaffold the project structure** — A consistent `Admin-Local/` layout gives every later phase a known home
   for credentials, docs, version snapshots, schema baselines, and the `90-DevLog` build journal.
3. **Adopt commit & documentation standards** — Consistent commit hygiene prevents secrets leaking and makes
   history searchable. Never commit (already in `.gitignore`): `.env` / `.env.*` (except `.env.example`),
   `vendor/`, `node_modules/`, IDE settings.
4. **Adopt version management — SemVer + Zaj-CHANGELOG** — If you'll ship updates (almost everyone), adopt
   semantic versioning and a `Zaj-CHANGELOG.md` now so your versions stay distinct from the vendor's
   `author-vX.X.X` line.

:::note[User part + done-when]
**👤 User part** — these are **decisions**: the operator chooses which to adopt and records the call. The agent must present all three, never assume yes or no, and scaffold only what's chosen.

**Done when** each topic was surfaced and its decision recorded — and, for anything adopted, the scaffold / standards / `Zaj-CHANGELOG.md` actually exist. &nbsp;·&nbsp; **⏱ ~20–40 min if adopted** &nbsp;·&nbsp; 🔀 (👤 decisions, 🤖 scaffolding).
:::

## Background

These three topics are **SHOULD**, not skip-by-default. The agent must **surface** them and capture the operator's decision — never silently drop them.

| Topic | What it gives you | Adopt when |
|---|---|---|
| Project structure | A predictable `Admin-Local/` home for the vault, docs, and versions | You want the full scaffold from day one (recommended) |
| Commit & doc standards | Searchable history + an auditable vendor seam | Team work, or you want disciplined history |
| Version management | SemVer + `Zaj-CHANGELOG.md` distinct from the vendor's line | You'll ship updates over time (almost everyone) |

## Steps

### 1. Decide which topics to adopt

Present all three to the operator and record each choice in `Zaj-PROJECT.md` before scaffolding anything.

:::note[Who does this]
👤 **User** (the operator) decides adopt-or-not for each topic — this is a workflow preference, so the agent surfaces and records rather than assuming.
:::

<Steps>

1. **Surface the three topics and record the decisions.**

   - ✅ Each of the three topics was presented, and its adopt/skip decision is written in `Zaj-PROJECT.md`.

</Steps>

### 2. Scaffold the project structure (if adopted)

A consistent `Admin-Local/` layout gives every later phase a known home for credentials, docs, and version snapshots.

:::note[Where templates live — per-project, not a host-side pack]
Per-project templates live at **`Admin-Local/1-Project/3-Templates/`** (created by the scaffold step below). This page does **not** depend on any host-side `Guides-v2/Templates/` pack — that path is legacy and is **not** guaranteed to exist in a per-project tree. Everything this step needs is either inlined below or seeded into `3-Templates/` here.

```bash
TPL=Admin-Local/1-Project/3-Templates
if [ -d "$TPL" ]; then
  echo "✅ Per-project templates at $TPL/ ($(find "$TPL" -type f | wc -l | tr -d ' ') files)"
else
  echo "ℹ️  $TPL/ not created yet — the scaffold step below creates it"
fi
# Expected: the scaffold step (next) creates $TPL/ and seeds it
```

If you have your org's handbook pack available, you **may** copy its `_Docs` templates into `3-Templates/` instead of the inline stubs below — but the playbook never requires it. Never create empty stand-ins for deploy or env templates; if a real template is missing, use the minimal inline version here.
:::

<Steps>

1. **Create the `Admin-Local/` scaffold**.

   ```bash
   mkdir -p Admin-Local/{0-SuperAdmin,1-Project,2-Docs,3-Versions,4-Backups,5-Archive}
   mkdir -p Admin-Local/1-Project/{1-Info,2-Vault,3-Templates,4-Audit-Reports,5-Scripts,6-Schema,90-DevLog}
   mkdir -p Admin-Local/1-Project/90-DevLog/{Plans,Sessions,Decisions,Prompts,Handoffs,_Archive}
   mkdir -p Admin-Local/3-Versions/1-v${VERSION}/{1-Originals,2-Modifications}
   # Expected: the Admin-Local tree is created
   ```

   - ✅ Phases 3–12 now have a known home for credentials, docs, audit reports, replay-script records, schema baselines, the build journal, and versions.

2. **Lock the vault** so credentials can never be committed.

   ```bash
   printf '*\n!.gitignore\n!README.md\n' > Admin-Local/1-Project/2-Vault/.gitignore
   # Expected: the vault ignores everything except its .gitignore + README
   ```

   - ✅ `Admin-Local/1-Project/2-Vault/.gitignore` ignores all but itself + README.

3. **Create the replay-script index only.** Do not pre-create empty payment/email/content folders. Scripts are generated later from the guide step + rules + boilerplate, so the project starts with only the taxonomy and provider inventory matrix.

   ```bash
   cat > Admin-Local/1-Project/5-Scripts/README.md <<'EOF'
   # 5-Scripts — <PROJECT>

   Persist replay scripts here when a setup, operations, migration, or growth step needs repeatable writes to the vendor database or a third-party API.

   ## Taxonomy

   - `1-Setup/` — initial configuration during Phases 6-8.
   - `2-Operations/` — future re-syncs, cleanups, and health checks.
   - `3-Migrations/` — future data migrations and vendor-update data fixes.
   - `4-Growth/` — future promos, new tiers, and experiments.
   - `archive/` — retired scripts moved for audit, never deleted.

   ## Provider inventory

   | Function | Provider/service | Status | Script path | Notes |
   |---|---|---|---|---|
   | Payments | Stripe | 🟡 placeholder |  | Use if this app has Stripe billing. |
   | Payments | PayPal | ⬜ not used |  |  |
   | Email | SMTP | 🟡 placeholder |  |  |
   | Email | SendGrid | ⬜ not used |  |  |
   | Content | DemoContentCleanup | 🟡 placeholder |  | Use only if demo rows need scripted cleanup. |
   | Auth | Roles | 🟡 placeholder |  |  |
   | Branding | Assets | 🟡 placeholder |  |  |
   | Database | SchemaInspection | 🟡 placeholder |  |  |

   Status: `✅ configured` = script exists, `🟡 placeholder` = expected but no script yet, `⬜ not used` = intentionally out of scope.
   EOF
   # Expected: only 5-Scripts/README.md exists; lane/function/provider folders are lazy-created later
   ```

   - ✅ `Admin-Local/1-Project/5-Scripts/README.md` records the taxonomy and provider inventory without empty script folders.

4. **Seed the build journal.** `90-DevLog/` is the working journal for plans, session logs, decisions, prompt capture, and handoffs. It is a high-band meta lane: `1-9` lanes hold project content; `90-99` lanes hold process/meta artifacts that should sort last.

   ```bash
   DEVLOG=Admin-Local/1-Project/90-DevLog
   mkdir -p "$DEVLOG"/{Plans,Sessions,Decisions,Prompts,Handoffs,_Archive}
   touch "$DEVLOG"/{Plans,Sessions,Decisions,Handoffs,_Archive}/.gitkeep
   printf '# keep\n' > "$DEVLOG/Prompts/.gitkeep"
   cat > "$DEVLOG/Prompts/.gitignore" <<'EOF'
   *.jsonl
   distilled/
   !.gitignore
   !.gitkeep
   !README.md
   EOF
   cat > "$DEVLOG/README.md" <<'EOF'
   # 90-DevLog — the build journal

   Single home for dev-process artifacts: plans, session logs, decisions, prompts, and handoffs.
   Numbered `90-` as a reserved high band so it sorts last and never forces a renumber of the
   `1-9` content lanes (`1-Info`, `2-Vault`, `5-Scripts`, `6-Schema`, etc.).

   Boundary: root `Zaj-*` files are the canonical record of what shipped. `90-DevLog/` is the
   working journal for how the work happened.

   ## Lanes

   | Path | Holds | Naming |
   |---|---|---|
   | `STATUS.md` | Active plan, in-flight agents, hot-file locks, blockers | fixed name |
   | `Plans/` | Phase or feature plans | `NNN-type-slug.md` |
   | `Sessions/` | Per-session logs | `YYYY-MM-DD-HHMM-agent-slug.md` |
   | `Decisions/` | ADR-lite decisions | `NNN-type-slug.md` |
   | `Prompts/` | Local prompt JSONL from `UserPromptSubmit` | `YYYY-Www.jsonl` |
   | `Handoffs/` | Agent-switch handoffs | `YYYY-MM-DD-HHMM-from-to.md` |
   | `_Archive/` | Completed/stale journal artifacts | mirror source name |

   ## Rules

   - `1-9` = project content lanes; `90-99` = sorts-last/meta lanes.
   - Plans and Decisions use monotonic IDs; never reset, reuse, or reorder them.
   - Sessions, Handoffs, and Prompts use timestamps so parallel agents do not race a shared counter.
   - Agent identity belongs in frontmatter and slug, never as the sort key.
   - `STATUS.md` is the coordination surface; claim hot files before editing.
   EOF
   cat > "$DEVLOG/STATUS.md" <<'EOF'
   # DevLog STATUS — <PROJECT>

   Last updated: <YYYY-MM-DD> (<AGENT>)

   ## Where we are
   - Current phase: Phase 2 — Code & repository setup

   ## Active plan
   - None yet.

   ## In-flight agents
   | Agent | Working on | Hot files claimed |
   |---|---|---|
   | <agent> | <task> | `<path>` |

   > Hot-file locks: one agent per hot file. Do not edit, move, overwrite, or archive another live agent's claimed file without coordinating first.

   ## Blockers
   - None.
   EOF
   # Expected: 90-DevLog has README, STATUS, lanes, and prompt JSONL is ignored by default
   ```

   - ✅ `Admin-Local/1-Project/90-DevLog/` exists with `README.md`, `STATUS.md`, lane stubs, and local prompt JSONL ignored by default.

5. **Seed the per-project templates** into `3-Templates/`. These are minimal, self-contained, and require no external pack. (If your org's handbook `_Docs` pack is available, you may copy its richer versions over these instead.)

   ```bash
   TPL=Admin-Local/1-Project/3-Templates

   # Zaj-PROJECT template — current truth for non-secret project facts
   cat > "$TPL/T01-Zaj-PROJECT.md" <<'EOF'
   # Zaj-PROJECT — <PROJECT>

   Last updated: <YYYY-MM-DD>
   Current phase: Phase 2 — Code & repository setup

   > Non-secret project bible. Current truth for project identity, toolchain versions, paths, environments, SSH aliases, and tracker links.
   > Boundary: this file records current facts; `Zaj-CUSTOMIZATIONS.md` records vendor deviations and why they exist.

   ## Project Identity

   | Field | Value |
   |---|---|
   | Project name | <PROJECT> |
   | CodeCanyon item | <url> |
   | Vendor / author | <vendor> |
   | Vendor version | <author-vX.Y.Z> |
   | Product type | <SaaS / marketplace / directory / other> |

   ## Repository And Branch Model

   | Field | Value |
   |---|---|
   | Repo URL | <git@host:org/repo.git> |
   | Default branch | develop |
   | Release branch | main |

   ## Environment Matrix

   Use one row per real environment. `staging-primary` is only the common example; use the actual keys this project has, such as `qa`, `uat`, `client-demo`, `sandbox`, or multiple staging rows.

   | Env key | Role | URL / domain | Hosting account | SSH alias | Host | User | Port | Deploy target | Source branch | Web PHP | CLI PHP binary | DB name | Noindex / robots | Credential pointer | Last verified |
   |---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
   | local | Local dev | https://<project>.test | N/A | N/A | 127.0.0.1 | <local user> | N/A | local | develop | Herd <x.y> | <path> | <project>_local | N/A | op://<vault>/Local | <date> |
   | staging-primary | Non-production | https://nonprod.example.com | <account/order> | <alias> | <host/IP> | <user> | <port> | staging | staging | <pending Phase 4> | <pending Phase 4> | <project>_staging | noindex + Disallow | op://<vault>/Staging | <date> |
   | production | Production | https://<domain> | <account/order> | <alias> | <host/IP> | <user> | <port> | production | main | <pending Phase 12> | <pending Phase 4> | <project>_production | index allowed | op://<vault>/Production | <date> |

   ## Toolchain Parity

   | Surface | Local | Non-production target(s) | Production | Target / rule |
   |---|---|---|---|---|
   | PHP | <x.y.z> | <pending> | <pending> | strictest root `composer.json` + production package requirement in `composer.lock` |
   | Composer | <2.x> | <pending> | <pending> | same major/minor where practical |
   | Node | <x.y.z> | build-local only | build-local only | `.tool-versions` / package lock |
   | DB engine | <MySQL/MariaDB x.y> | <x.y> | <x.y> | same engine family when possible |
   | DB charset/collation | utf8mb4 / utf8mb4_unicode_ci | utf8mb4 / utf8mb4_unicode_ci | utf8mb4 / utf8mb4_unicode_ci | must match before deploy |

   ## Canonical Paths

   | Purpose | Path |
   |---|---|
   | Project profile | `Zaj-PROJECT.md` |
   | Progress tracker | `Zaj-PROGRESS.md` |
   | Deferred work | `Zaj-BACKLOG.md` |
   | Internal changelog | `Zaj-CHANGELOG.md` |
   | Vendor-deviation ledger | `Zaj-CUSTOMIZATIONS.md` |
   | Project info lane | `Admin-Local/1-Project/1-Info/` |
   | Research reports | `Admin-Local/1-Project/1-Info/Research/` |
   | Build journal | `Admin-Local/1-Project/90-DevLog/` |
   | Playbook feedback | `Admin-Local/1-Project/playbook-feedback.md` |

   ## 1Password Pointers

   | Item | Pointer | Expected fields |
   |---|---|---|
   | Local credential item | `op://<vault>/Local` | `DB_CONNECTION`, `DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`, `APP_KEY`, `env_file` |
   | Staging credential item | `op://<vault>/Staging` | Same flat field set; use the real non-production item name if this row is `qa`, `uat`, `client-demo`, etc. |
   | Production credential item | `op://<vault>/Production` | Same flat field set; `DB_PASSWORD`, `APP_KEY`, and `env_file` are concealed. |
   EOF

   cat > "$TPL/tool-versions.template" <<'EOF'
   php <PHP_VERSION>
   nodejs <NODE_VERSION>
   composer <COMPOSER_VERSION>
   EOF

   # Expected: T01-Zaj-PROJECT.md + tool-versions.template exist in 3-Templates/
   ```

6. **Instantiate the project records** from those templates:

   ```bash
   TPL=Admin-Local/1-Project/3-Templates
   cp "$TPL/T01-Zaj-PROJECT.md" Zaj-PROJECT.md
   cp "$TPL/tool-versions.template" .tool-versions
   printf '# Project vault\n\nGitignored credentials and env templates.\n' \
     > Admin-Local/1-Project/2-Vault/README.md
   # Expected: Zaj-PROJECT.md + .tool-versions + vault README exist
   ```

   Fill **Zaj-PROJECT** from infrastructure created in [Prerequisites](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/02-code-repo/01-prerequisites/) — domains, IPs, SSH aliases, repo URL, DB names, current local PHP/Composer/Node, and placeholder deploy PHP rows that Phase 4 will confirm. Keep `.tool-versions` aligned with the chosen PHP / Node / Composer targets. (`Zaj-CHANGELOG.md` is created in §4 below — keep it out of this step so the public/internal split is set up correctly.)

   **AI agent wiring:** if Phase 1 did not already seed rules, drop Cursor/Gemini/AntiGravity rule files into the project's own AI config (e.g. `.cursor/rules/`, `GEMINI.md`) and ensure `.cursorignore` / `.geminiignore` exclude `vendor/`, `node_modules/`, and `Admin-Local/1-Project/2-Vault/`. Do **not** assume a host-side `Guides-v2/Templates/` pack — author them in-project or copy from your handbook if you have one.

   - ✅ `Zaj-PROJECT.md` exists with real domains, IPs, SSH aliases, repo URL, DB names, local toolchain facts, and the `90-DevLog` canonical path; `.tool-versions` exists; per-project templates are seeded in `3-Templates/`; vault README explains the gitignored area.

</Steps>

### 3. Adopt commit & documentation standards (if adopted)

Consistent commit hygiene prevents secrets leaking and makes history searchable. **Never commit** (already in `.gitignore`): `.env` / `.env.*` (except `.env.example`), `vendor/`, `node_modules/`, IDE settings. **Always commit**: `composer.json` + `composer.lock`, `package.json` + `package-lock.json`, `config/*.php`, `database/migrations/*.php`, project docs.

A conventional commit format keeps the log self-documenting — emoji + type tag + verb-thing + description:

| Type | Format | Example |
|---|---|---|
| Author import | `📦 ⬜ T1 Setup-Author: …` | `📦 ⬜ T1 Setup-Author: Import v10.4` |
| Setup/config | `🔧 🟦 T2 Setup-Config: …` | `🔧 🟦 T2 Setup-Config: Add GA tracking` |
| App feature | `🔨 🟪 T3 Add-Feature: …` | `🔨 🟪 T3 Add-Feature: Arabic support` |
| Deploy | `🚀 🟩 T4 Deploy-App: …` | `🚀 🟩 T4 Deploy-App: Deploy v1.5.1` |
| ServerSync | `🔄 ⬛ T5 ServerSync-Setup: …` | `🔄 ⬛ T5 ServerSync-Setup: Capture SMTP config` |

**Documentation update schedule** — refresh when the trigger fires, not "whenever you remember":

| File | Update when |
| --- | --- |
| `Zaj-PROJECT.md` | Every current-truth change: repo, toolchain, DB names, SSH aliases, deploy paths, server/runtime versions |
| `Zaj-PROGRESS.md` | During active phase/step work and after each verified gate |
| `Zaj-BACKLOG.md` | Deferred work, phase-entry blockers, human-only follow-ups, and future work |
| `Zaj-CHANGELOG.md` | Each phase completion and release-worthy internal change |
| `Zaj-CUSTOMIZATIONS.md` | Any vendor/config deviation or operational decision that affects future upgrades |
| `Admin-Local/1-Project/90-DevLog/Decisions/` | Material "why" decisions that need an audit trail |
| `Admin-Local/1-Project/4-Audit-Reports/` | Security, compliance, audit, and QA evidence |
| `CLAUDE.md` / `AGENTS.md` | AI rules, vendor doc extracts, tooling changes |

Before any customization in this or later phases, know **which mechanism** to use — this is what prevents "modified vendor file" sprawl that blocks future updates:

| Mechanism | Use when | Lives in |
|---|---|---|
| **Vendor Customizations** | Patching an *existing* vendor file | `resources/vendor-customizations/` |
| **ZajModules** | Adding *new* functionality (route, view, service) | `packages/ZajModules/{Type}/{Cat}/{Name}/` |
| **`_zaj` migrations** | Extending a vendor *table schema* | `database/migrations/*_zaj.php` |

The decision is three questions: editing an existing vendor file → Vendor Customization; adding something new → ZajModule; adding columns to a vendor table → `_zaj` migration.

### 4. Adopt version management — SemVer + Zaj-CHANGELOG (if adopted)

If you'll ship updates (almost everyone), adopt semantic versioning and a `Zaj-CHANGELOG.md` now so your versions stay distinct from the vendor's `author-vX.X.X` line. `vMAJOR.MINOR.PATCH` — bump by the nature of the change:

| Change | Bump | Example |
|---|---|---|
| Bug fix / security patch | PATCH (`1.0.0 → 1.0.1`) | Fixed login error |
| New feature, backward compatible | MINOR (`1.0.0 → 1.1.0`) | Added export |
| Breaking change | MAJOR (`1.0.0 → 2.0.0`) | Changed API responses |

**Git tags:**

| Type | Command | Use for |
| --- | --- | --- |
| Annotated (recommended) | `git tag -a v1.0.0 -m "First stable release"` | Production releases |
| Lightweight | `git tag v1.0.0` | Quick local markers only |

**Release workflow:**

1. **Develop work** — `develop` branch; `Zaj-CHANGELOG.md` `[Unreleased]` section grows.
2. **Prepare release** — promote to staging, test, bump version in `composer.json` / `package.json`.
3. **Release** — deploy production, create annotated tag `vX.Y.Z`.
4. **Sync branches** — mirror production to `main` when your pipeline uses it.

**Decision journal** — the current version fields live in `Zaj-PROJECT.md`; the release history lives in `Zaj-CHANGELOG.md`; material "why" decisions live in `90-DevLog/Decisions/`. If this project needs an audit trail for the version-management choice, add one decision note there:

```bash
mkdir -p Admin-Local/1-Project/90-DevLog/Decisions
DECISION="Admin-Local/1-Project/90-DevLog/Decisions/001-decision-version-management.md"
if [ ! -f "$DECISION" ]; then
  cat > "$DECISION" <<'EOF'
# Decision 001 — Version management

Date: <YYYY-MM-DD>
Decision: Use project SemVer with root Zaj-CHANGELOG.md and internal Vendor base markers.
Rationale: Keep our release line separate from the CodeCanyon author snapshot line.
Evidence: composer.json/package.json version fields, author-vX.X.X tag, Zaj-CHANGELOG.md.
EOF
fi
# Expected: optional decision note lives under 90-DevLog/Decisions/; no separate 1-Info work-log file is created
```

Keep changelogs in [Keep a Changelog](https://keepachangelog.com) form (Added / Changed / Deprecated / Removed / Fixed / Security), and align package metadata: set `composer.json` and `package.json` `name`/`version`/`description`, change `license` to `proprietary`, and keep `package.json` `private: true`.

```bash
echo "composer.json:" && grep '"version"' composer.json | head -1
echo "package.json:" && grep '"version"' package.json | head -1
# Expected: both show "1.0.0" (your project line, not the vendor's author tag)
```

#### Two changelogs: INTERNAL (vendor-aware) vs PUBLIC (sanitized)

A public-facing CHANGELOG or release-notes page **must never name the CodeCanyon vendor** — not "WorkDo", "CodeCanyon", "Envato", the vendor product name, nor an `author-vX` tag. That's both a product-naming rule (customers see *your* brand, not the underlying script) and basic operational hygiene. So keep **two** documents:

| Document | Audience | May mention vendor? | Records |
|---|---|---|---|
| **`Zaj-CHANGELOG.md`** (internal) | You + your team | ✅ Yes — that's the point | Project SemVer **+** vendor base per release (e.g. `Vendor base: <Vendor> v7.6`), vendor upgrades logged as `### Changed` |
| **`docs/public-changelog.md`** (or release-notes page) | Customers / public | ❌ **Never** | Project name + your own SemVer + user-facing changes only |

Two version lines stay distinct in BOTH:

- **Project version** (`v1.0.0`, `v1.1.0`, …) — your own SemVer, tagged `vX.Y.Z`. First release is `v1.0.0` even if the vendor is at v7.6.
- **Vendor (author) version** (`author-v7.6`, …) — the CodeCanyon base, tracked by `author-vX.X.X` git tags. **Internal only** — never in the public document.

Each release records, **internally**, the vendor base it was built on so any project release is traceable to the exact CodeCanyon version underneath it. The public document carries only the project SemVer and the user-facing change.

**Internal `Zaj-CHANGELOG.md` (vendor base recorded):**

```markdown
## [Unreleased]

> **Vendor base:** <Vendor> v7.6 (`author-v7.6`)

### Added
- Subscription export.

### Changed
- Upgraded vendor base v7.6 → v7.8.
```

**Public `docs/public-changelog.md` (same release, sanitized):**

```markdown
## v1.1.0 — <YYYY-MM-DD>

### Added
- Export your subscriptions to CSV.

### Changed
- Performance and reliability improvements.
```

**Scrub gate — the public document must not leak the vendor.** Run this before publishing any public release notes; it must print `✅ clean`:

```bash
PUBLIC=docs/public-changelog.md
if grep -iE 'workdo|codecanyon|envato|author-v|dash[- ]?saas' "$PUBLIC" >/dev/null 2>&1; then
  echo "❌ vendor reference leaked into $PUBLIC — sanitize before publishing:"
  grep -inE 'workdo|codecanyon|envato|author-v|dash[- ]?saas' "$PUBLIC"
else
  echo "✅ clean — no vendor references in $PUBLIC"
fi
# Expected: ✅ clean — add YOUR vendor's product name to the pattern too
```

Replace `dash[- ]?saas` with your own vendor's product name(s) so the grep catches the specific script you're built on, not just the generic terms.

:::caution[Public release notes never name the vendor]
"Upgraded vendor base v7.6 → v7.8" belongs in the **internal** `Zaj-CHANGELOG.md` only. The public note for the same release says "Performance and reliability improvements" — the customer never learns which CodeCanyon script powers the product. Treat the scrub gate above as a hard gate on the public document.
:::

:::note[Your first release is v1.0.0 — even if the vendor is v7.6]
The `author-vX.X.X` tag tracks the *vendor's* version. *Your* project's first public release is always `v1.0.0`, created later (release finalization), not here. Annotated tags (`git tag -a v1.0.0 -m "…"`) are recommended for releases.
:::

## Checklist

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

- [ ] **👤 Topics surfaced** — each recommended topic was presented and the operator's choice recorded.
- [ ] **🤖 Scaffold (if adopted)** — `Admin-Local/` + gitignored vault exist; per-project templates seeded in `Admin-Local/1-Project/3-Templates/`; `4-Audit-Reports/` and `6-Schema/` exist; `5-Scripts/README.md` exists without pre-created script folders; `90-DevLog/` exists with README, STATUS, lanes, and prompt JSONL ignored by default.
- [ ] **🔀 Standards (if adopted)** — commit format + Zaj customization strategy understood.
- [ ] **🔀 Versioning (if adopted)** — internal `Zaj-CHANGELOG.md` (records vendor base) started, package metadata set, and the public-changelog **scrub gate prints `✅ clean`** before any public release notes ship.

:::next[Next step]
[Phase 3 · Local development](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/)
:::

# 7 · Project standards (recommended)

> Source: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/02-code-repo/07-project-standards/

## TL;DR

**Objective** — surface three **SHOULD-not-skip** topics (project structure, commit + doc standards with the Zaj customization strategy, and SemVer + Zaj-CHANGELOG version management) and capture the operator's decision on each — never silently drop them.

**Steps at a glance:**
1. **Decide which topics to adopt** — Present all three to the operator and record each choice in the project
   log before scaffolding anything.
2. **Scaffold the project structure** — A consistent `Admin-Local/` layout gives every later phase a known home
   for credentials, docs, version snapshots, schema baselines, and the `90-DevLog` build journal.
3. **Adopt commit & documentation standards** — Consistent commit hygiene prevents secrets leaking and makes
   history searchable. Never commit (already in `.gitignore`): `.env` / `.env.*` (except `.env.example`),
   `vendor/`, `node_modules/`, IDE settings.
4. **Adopt version management — SemVer + Zaj-CHANGELOG** — If you'll ship updates (almost everyone), adopt
   semantic versioning and a `Zaj-CHANGELOG.md` now so your versions stay distinct from the vendor's
   `author-vX.X.X` line.

:::note[User part + done-when]
**👤 User part** — these are **decisions**: the operator chooses which to adopt and records the call. The agent must present all three, never assume yes or no, and scaffold only what's chosen.

**Done when** each topic was surfaced and its decision recorded — and, for anything adopted, the scaffold / standards / `Zaj-CHANGELOG.md` actually exist. &nbsp;·&nbsp; **⏱ ~20–40 min if adopted** &nbsp;·&nbsp; 🔀 (👤 decisions, 🤖 scaffolding).
:::

## Background

These three topics are **SHOULD**, not skip-by-default. The agent must **surface** them and capture the operator's decision — never silently drop them.

| Topic | What it gives you | Adopt when |
|---|---|---|
| Project structure | A predictable `Admin-Local/` home for the vault, docs, and versions | You want the full scaffold from day one (recommended) |
| Commit & doc standards | Searchable history + an auditable vendor seam | Team work, or you want disciplined history |
| Version management | SemVer + `Zaj-CHANGELOG.md` distinct from the vendor's line | You'll ship updates over time (almost everyone) |

## Steps

### 1. Decide which topics to adopt

Present all three to the operator and record each choice in `Zaj-PROJECT.md` before scaffolding anything.

:::note[Who does this]
👤 **User** (the operator) decides adopt-or-not for each topic — this is a workflow preference, so the agent surfaces and records rather than assuming.
:::

<Steps>

1. **Surface the three topics and record the decisions.**

   - ✅ Each of the three topics was presented, and its adopt/skip decision is written in `Zaj-PROJECT.md`.

</Steps>

### 2. Scaffold the project structure (if adopted)

A consistent `Admin-Local/` layout gives every later phase a known home for credentials, docs, and version snapshots.

:::note[Where templates live — per-project, not a host-side pack]
Per-project templates live at **`Admin-Local/1-Project/3-Templates/`** (created by the scaffold step below). This page does **not** depend on any host-side `Guides-v2/Templates/` pack — that path is legacy and is **not** guaranteed to exist in a per-project tree. Everything this step needs is either inlined below or seeded into `3-Templates/` here.

```bash
TPL=Admin-Local/1-Project/3-Templates
if [ -d "$TPL" ]; then
  echo "✅ Per-project templates at $TPL/ ($(find "$TPL" -type f | wc -l | tr -d ' ') files)"
else
  echo "ℹ️  $TPL/ not created yet — the scaffold step below creates it"
fi
# Expected: the scaffold step (next) creates $TPL/ and seeds it
```

If you have your org's handbook pack available, you **may** copy its `_Docs` templates into `3-Templates/` instead of the inline stubs below — but the playbook never requires it. Never create empty stand-ins for deploy or env templates; if a real template is missing, use the minimal inline version here.
:::

<Steps>

1. **Create the `Admin-Local/` scaffold**.

   ```bash
   mkdir -p Admin-Local/{0-SuperAdmin,1-Project,2-Docs,3-Versions,4-Backups,5-Archive}
   mkdir -p Admin-Local/1-Project/{1-Info,2-Vault,3-Templates,4-Audit-Reports,5-Scripts,6-Schema,90-DevLog}
   mkdir -p Admin-Local/1-Project/90-DevLog/{Plans,Sessions,Decisions,Prompts,Handoffs,_Archive}
   mkdir -p Admin-Local/3-Versions/1-v${VERSION}/{1-Originals,2-Modifications}
   # Expected: the Admin-Local tree is created
   ```

   - ✅ Phases 3–12 now have a known home for credentials, docs, audit reports, replay-script records, schema baselines, the build journal, and versions.

2. **Lock the vault** so credentials can never be committed.

   ```bash
   printf '*\n!.gitignore\n!README.md\n' > Admin-Local/1-Project/2-Vault/.gitignore
   # Expected: the vault ignores everything except its .gitignore + README
   ```

   - ✅ `Admin-Local/1-Project/2-Vault/.gitignore` ignores all but itself + README.

3. **Create the replay-script index only.** Do not pre-create empty payment/email/content folders. Scripts are generated later from the guide step + rules + boilerplate, so the project starts with only the taxonomy and provider inventory matrix.

   ```bash
   cat > Admin-Local/1-Project/5-Scripts/README.md <<'EOF'
   # 5-Scripts — <PROJECT>

   Persist replay scripts here when a setup, operations, migration, or growth step needs repeatable writes to the vendor database or a third-party API.

   ## Taxonomy

   - `1-Setup/` — initial configuration during Phases 6-8.
   - `2-Operations/` — future re-syncs, cleanups, and health checks.
   - `3-Migrations/` — future data migrations and vendor-update data fixes.
   - `4-Growth/` — future promos, new tiers, and experiments.
   - `archive/` — retired scripts moved for audit, never deleted.

   ## Provider inventory

   | Function | Provider/service | Status | Script path | Notes |
   |---|---|---|---|---|
   | Payments | Stripe | 🟡 placeholder |  | Use if this app has Stripe billing. |
   | Payments | PayPal | ⬜ not used |  |  |
   | Email | SMTP | 🟡 placeholder |  |  |
   | Email | SendGrid | ⬜ not used |  |  |
   | Content | DemoContentCleanup | 🟡 placeholder |  | Use only if demo rows need scripted cleanup. |
   | Auth | Roles | 🟡 placeholder |  |  |
   | Branding | Assets | 🟡 placeholder |  |  |
   | Database | SchemaInspection | 🟡 placeholder |  |  |

   Status: `✅ configured` = script exists, `🟡 placeholder` = expected but no script yet, `⬜ not used` = intentionally out of scope.
   EOF
   # Expected: only 5-Scripts/README.md exists; lane/function/provider folders are lazy-created later
   ```

   - ✅ `Admin-Local/1-Project/5-Scripts/README.md` records the taxonomy and provider inventory without empty script folders.

4. **Seed the build journal.** `90-DevLog/` is the working journal for plans, session logs, decisions, prompt capture, and handoffs. It is a high-band meta lane: `1-9` lanes hold project content; `90-99` lanes hold process/meta artifacts that should sort last.

   ```bash
   DEVLOG=Admin-Local/1-Project/90-DevLog
   mkdir -p "$DEVLOG"/{Plans,Sessions,Decisions,Prompts,Handoffs,_Archive}
   touch "$DEVLOG"/{Plans,Sessions,Decisions,Handoffs,_Archive}/.gitkeep
   printf '# keep\n' > "$DEVLOG/Prompts/.gitkeep"
   cat > "$DEVLOG/Prompts/.gitignore" <<'EOF'
   *.jsonl
   distilled/
   !.gitignore
   !.gitkeep
   !README.md
   EOF
   cat > "$DEVLOG/README.md" <<'EOF'
   # 90-DevLog — the build journal

   Single home for dev-process artifacts: plans, session logs, decisions, prompts, and handoffs.
   Numbered `90-` as a reserved high band so it sorts last and never forces a renumber of the
   `1-9` content lanes (`1-Info`, `2-Vault`, `5-Scripts`, `6-Schema`, etc.).

   Boundary: root `Zaj-*` files are the canonical record of what shipped. `90-DevLog/` is the
   working journal for how the work happened.

   ## Lanes

   | Path | Holds | Naming |
   |---|---|---|
   | `STATUS.md` | Active plan, in-flight agents, hot-file locks, blockers | fixed name |
   | `Plans/` | Phase or feature plans | `NNN-type-slug.md` |
   | `Sessions/` | Per-session logs | `YYYY-MM-DD-HHMM-agent-slug.md` |
   | `Decisions/` | ADR-lite decisions | `NNN-type-slug.md` |
   | `Prompts/` | Local prompt JSONL from `UserPromptSubmit` | `YYYY-Www.jsonl` |
   | `Handoffs/` | Agent-switch handoffs | `YYYY-MM-DD-HHMM-from-to.md` |
   | `_Archive/` | Completed/stale journal artifacts | mirror source name |

   ## Rules

   - `1-9` = project content lanes; `90-99` = sorts-last/meta lanes.
   - Plans and Decisions use monotonic IDs; never reset, reuse, or reorder them.
   - Sessions, Handoffs, and Prompts use timestamps so parallel agents do not race a shared counter.
   - Agent identity belongs in frontmatter and slug, never as the sort key.
   - `STATUS.md` is the coordination surface; claim hot files before editing.
   EOF
   cat > "$DEVLOG/STATUS.md" <<'EOF'
   # DevLog STATUS — <PROJECT>

   Last updated: <YYYY-MM-DD> (<AGENT>)

   ## Where we are
   - Current phase: Phase 2 — Code & repository setup

   ## Active plan
   - None yet.

   ## In-flight agents
   | Agent | Working on | Hot files claimed |
   |---|---|---|
   | <agent> | <task> | `<path>` |

   > Hot-file locks: one agent per hot file. Do not edit, move, overwrite, or archive another live agent's claimed file without coordinating first.

   ## Blockers
   - None.
   EOF
   # Expected: 90-DevLog has README, STATUS, lanes, and prompt JSONL is ignored by default
   ```

   - ✅ `Admin-Local/1-Project/90-DevLog/` exists with `README.md`, `STATUS.md`, lane stubs, and local prompt JSONL ignored by default.

5. **Seed the per-project templates** into `3-Templates/`. These are minimal, self-contained, and require no external pack. (If your org's handbook `_Docs` pack is available, you may copy its richer versions over these instead.)

   ```bash
   TPL=Admin-Local/1-Project/3-Templates

   # Zaj-PROJECT template — current truth for non-secret project facts
   cat > "$TPL/T01-Zaj-PROJECT.md" <<'EOF'
   # Zaj-PROJECT — <PROJECT>

   Last updated: <YYYY-MM-DD>
   Current phase: Phase 2 — Code & repository setup

   > Non-secret project bible. Current truth for project identity, toolchain versions, paths, environments, SSH aliases, and tracker links.
   > Boundary: this file records current facts; `Zaj-CUSTOMIZATIONS.md` records vendor deviations and why they exist.

   ## Project Identity

   | Field | Value |
   |---|---|
   | Project name | <PROJECT> |
   | CodeCanyon item | <url> |
   | Vendor / author | <vendor> |
   | Vendor version | <author-vX.Y.Z> |
   | Product type | <SaaS / marketplace / directory / other> |

   ## Repository And Branch Model

   | Field | Value |
   |---|---|
   | Repo URL | <git@host:org/repo.git> |
   | Default branch | develop |
   | Release branch | main |

   ## Environment Matrix

   Use one row per real environment. `staging-primary` is only the common example; use the actual keys this project has, such as `qa`, `uat`, `client-demo`, `sandbox`, or multiple staging rows.

   | Env key | Role | URL / domain | Hosting account | SSH alias | Host | User | Port | Deploy target | Source branch | Web PHP | CLI PHP binary | DB name | Noindex / robots | Credential pointer | Last verified |
   |---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
   | local | Local dev | https://<project>.test | N/A | N/A | 127.0.0.1 | <local user> | N/A | local | develop | Herd <x.y> | <path> | <project>_local | N/A | op://<vault>/Local | <date> |
   | staging-primary | Non-production | https://nonprod.example.com | <account/order> | <alias> | <host/IP> | <user> | <port> | staging | staging | <pending Phase 4> | <pending Phase 4> | <project>_staging | noindex + Disallow | op://<vault>/Staging | <date> |
   | production | Production | https://<domain> | <account/order> | <alias> | <host/IP> | <user> | <port> | production | main | <pending Phase 12> | <pending Phase 4> | <project>_production | index allowed | op://<vault>/Production | <date> |

   ## Toolchain Parity

   | Surface | Local | Non-production target(s) | Production | Target / rule |
   |---|---|---|---|---|
   | PHP | <x.y.z> | <pending> | <pending> | strictest root `composer.json` + production package requirement in `composer.lock` |
   | Composer | <2.x> | <pending> | <pending> | same major/minor where practical |
   | Node | <x.y.z> | build-local only | build-local only | `.tool-versions` / package lock |
   | DB engine | <MySQL/MariaDB x.y> | <x.y> | <x.y> | same engine family when possible |
   | DB charset/collation | utf8mb4 / utf8mb4_unicode_ci | utf8mb4 / utf8mb4_unicode_ci | utf8mb4 / utf8mb4_unicode_ci | must match before deploy |

   ## Canonical Paths

   | Purpose | Path |
   |---|---|
   | Project profile | `Zaj-PROJECT.md` |
   | Progress tracker | `Zaj-PROGRESS.md` |
   | Deferred work | `Zaj-BACKLOG.md` |
   | Internal changelog | `Zaj-CHANGELOG.md` |
   | Vendor-deviation ledger | `Zaj-CUSTOMIZATIONS.md` |
   | Project info lane | `Admin-Local/1-Project/1-Info/` |
   | Research reports | `Admin-Local/1-Project/1-Info/Research/` |
   | Build journal | `Admin-Local/1-Project/90-DevLog/` |
   | Playbook feedback | `Admin-Local/1-Project/playbook-feedback.md` |

   ## 1Password Pointers

   | Item | Pointer | Expected fields |
   |---|---|---|
   | Local credential item | `op://<vault>/Local` | `DB_CONNECTION`, `DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`, `APP_KEY`, `env_file` |
   | Staging credential item | `op://<vault>/Staging` | Same flat field set; use the real non-production item name if this row is `qa`, `uat`, `client-demo`, etc. |
   | Production credential item | `op://<vault>/Production` | Same flat field set; `DB_PASSWORD`, `APP_KEY`, and `env_file` are concealed. |
   EOF

   cat > "$TPL/tool-versions.template" <<'EOF'
   php <PHP_VERSION>
   nodejs <NODE_VERSION>
   composer <COMPOSER_VERSION>
   EOF

   # Expected: T01-Zaj-PROJECT.md + tool-versions.template exist in 3-Templates/
   ```

6. **Instantiate the project records** from those templates:

   ```bash
   TPL=Admin-Local/1-Project/3-Templates
   cp "$TPL/T01-Zaj-PROJECT.md" Zaj-PROJECT.md
   cp "$TPL/tool-versions.template" .tool-versions
   printf '# Project vault\n\nGitignored credentials and env templates.\n' \
     > Admin-Local/1-Project/2-Vault/README.md
   # Expected: Zaj-PROJECT.md + .tool-versions + vault README exist
   ```

   Fill **Zaj-PROJECT** from infrastructure created in [Prerequisites](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/02-code-repo/01-prerequisites/) — domains, IPs, SSH aliases, repo URL, DB names, current local PHP/Composer/Node, and placeholder deploy PHP rows that Phase 4 will confirm. Keep `.tool-versions` aligned with the chosen PHP / Node / Composer targets. (`Zaj-CHANGELOG.md` is created in §4 below — keep it out of this step so the public/internal split is set up correctly.)

   **AI agent wiring:** if Phase 1 did not already seed rules, drop Cursor/Gemini/AntiGravity rule files into the project's own AI config (e.g. `.cursor/rules/`, `GEMINI.md`) and ensure `.cursorignore` / `.geminiignore` exclude `vendor/`, `node_modules/`, and `Admin-Local/1-Project/2-Vault/`. Do **not** assume a host-side `Guides-v2/Templates/` pack — author them in-project or copy from your handbook if you have one.

   - ✅ `Zaj-PROJECT.md` exists with real domains, IPs, SSH aliases, repo URL, DB names, local toolchain facts, and the `90-DevLog` canonical path; `.tool-versions` exists; per-project templates are seeded in `3-Templates/`; vault README explains the gitignored area.

</Steps>

### 3. Adopt commit & documentation standards (if adopted)

Consistent commit hygiene prevents secrets leaking and makes history searchable. **Never commit** (already in `.gitignore`): `.env` / `.env.*` (except `.env.example`), `vendor/`, `node_modules/`, IDE settings. **Always commit**: `composer.json` + `composer.lock`, `package.json` + `package-lock.json`, `config/*.php`, `database/migrations/*.php`, project docs.

A conventional commit format keeps the log self-documenting — emoji + type tag + verb-thing + description:

| Type | Format | Example |
|---|---|---|
| Author import | `📦 ⬜ T1 Setup-Author: …` | `📦 ⬜ T1 Setup-Author: Import v10.4` |
| Setup/config | `🔧 🟦 T2 Setup-Config: …` | `🔧 🟦 T2 Setup-Config: Add GA tracking` |
| App feature | `🔨 🟪 T3 Add-Feature: …` | `🔨 🟪 T3 Add-Feature: Arabic support` |
| Deploy | `🚀 🟩 T4 Deploy-App: …` | `🚀 🟩 T4 Deploy-App: Deploy v1.5.1` |
| ServerSync | `🔄 ⬛ T5 ServerSync-Setup: …` | `🔄 ⬛ T5 ServerSync-Setup: Capture SMTP config` |

**Documentation update schedule** — refresh when the trigger fires, not "whenever you remember":

| File | Update when |
| --- | --- |
| `Zaj-PROJECT.md` | Every current-truth change: repo, toolchain, DB names, SSH aliases, deploy paths, server/runtime versions |
| `Zaj-PROGRESS.md` | During active phase/step work and after each verified gate |
| `Zaj-BACKLOG.md` | Deferred work, phase-entry blockers, human-only follow-ups, and future work |
| `Zaj-CHANGELOG.md` | Each phase completion and release-worthy internal change |
| `Zaj-CUSTOMIZATIONS.md` | Any vendor/config deviation or operational decision that affects future upgrades |
| `Admin-Local/1-Project/90-DevLog/Decisions/` | Material "why" decisions that need an audit trail |
| `Admin-Local/1-Project/4-Audit-Reports/` | Security, compliance, audit, and QA evidence |
| `CLAUDE.md` / `AGENTS.md` | AI rules, vendor doc extracts, tooling changes |

Before any customization in this or later phases, know **which mechanism** to use — this is what prevents "modified vendor file" sprawl that blocks future updates:

| Mechanism | Use when | Lives in |
|---|---|---|
| **Vendor Customizations** | Patching an *existing* vendor file | `resources/vendor-customizations/` |
| **ZajModules** | Adding *new* functionality (route, view, service) | `packages/ZajModules/{Type}/{Cat}/{Name}/` |
| **`_zaj` migrations** | Extending a vendor *table schema* | `database/migrations/*_zaj.php` |

The decision is three questions: editing an existing vendor file → Vendor Customization; adding something new → ZajModule; adding columns to a vendor table → `_zaj` migration.

### 4. Adopt version management — SemVer + Zaj-CHANGELOG (if adopted)

If you'll ship updates (almost everyone), adopt semantic versioning and a `Zaj-CHANGELOG.md` now so your versions stay distinct from the vendor's `author-vX.X.X` line. `vMAJOR.MINOR.PATCH` — bump by the nature of the change:

| Change | Bump | Example |
|---|---|---|
| Bug fix / security patch | PATCH (`1.0.0 → 1.0.1`) | Fixed login error |
| New feature, backward compatible | MINOR (`1.0.0 → 1.1.0`) | Added export |
| Breaking change | MAJOR (`1.0.0 → 2.0.0`) | Changed API responses |

**Git tags:**

| Type | Command | Use for |
| --- | --- | --- |
| Annotated (recommended) | `git tag -a v1.0.0 -m "First stable release"` | Production releases |
| Lightweight | `git tag v1.0.0` | Quick local markers only |

**Release workflow:**

1. **Develop work** — `develop` branch; `Zaj-CHANGELOG.md` `[Unreleased]` section grows.
2. **Prepare release** — promote to staging, test, bump version in `composer.json` / `package.json`.
3. **Release** — deploy production, create annotated tag `vX.Y.Z`.
4. **Sync branches** — mirror production to `main` when your pipeline uses it.

**Decision journal** — the current version fields live in `Zaj-PROJECT.md`; the release history lives in `Zaj-CHANGELOG.md`; material "why" decisions live in `90-DevLog/Decisions/`. If this project needs an audit trail for the version-management choice, add one decision note there:

```bash
mkdir -p Admin-Local/1-Project/90-DevLog/Decisions
DECISION="Admin-Local/1-Project/90-DevLog/Decisions/001-decision-version-management.md"
if [ ! -f "$DECISION" ]; then
  cat > "$DECISION" <<'EOF'
# Decision 001 — Version management

Date: <YYYY-MM-DD>
Decision: Use project SemVer with root Zaj-CHANGELOG.md and internal Vendor base markers.
Rationale: Keep our release line separate from the CodeCanyon author snapshot line.
Evidence: composer.json/package.json version fields, author-vX.X.X tag, Zaj-CHANGELOG.md.
EOF
fi
# Expected: optional decision note lives under 90-DevLog/Decisions/; no separate 1-Info work-log file is created
```

Keep changelogs in [Keep a Changelog](https://keepachangelog.com) form (Added / Changed / Deprecated / Removed / Fixed / Security), and align package metadata: set `composer.json` and `package.json` `name`/`version`/`description`, change `license` to `proprietary`, and keep `package.json` `private: true`.

```bash
echo "composer.json:" && grep '"version"' composer.json | head -1
echo "package.json:" && grep '"version"' package.json | head -1
# Expected: both show "1.0.0" (your project line, not the vendor's author tag)
```

#### Two changelogs: INTERNAL (vendor-aware) vs PUBLIC (sanitized)

A public-facing CHANGELOG or release-notes page **must never name the CodeCanyon vendor** — not "WorkDo", "CodeCanyon", "Envato", the vendor product name, nor an `author-vX` tag. That's both a product-naming rule (customers see *your* brand, not the underlying script) and basic operational hygiene. So keep **two** documents:

| Document | Audience | May mention vendor? | Records |
|---|---|---|---|
| **`Zaj-CHANGELOG.md`** (internal) | You + your team | ✅ Yes — that's the point | Project SemVer **+** vendor base per release (e.g. `Vendor base: <Vendor> v7.6`), vendor upgrades logged as `### Changed` |
| **`docs/public-changelog.md`** (or release-notes page) | Customers / public | ❌ **Never** | Project name + your own SemVer + user-facing changes only |

Two version lines stay distinct in BOTH:

- **Project version** (`v1.0.0`, `v1.1.0`, …) — your own SemVer, tagged `vX.Y.Z`. First release is `v1.0.0` even if the vendor is at v7.6.
- **Vendor (author) version** (`author-v7.6`, …) — the CodeCanyon base, tracked by `author-vX.X.X` git tags. **Internal only** — never in the public document.

Each release records, **internally**, the vendor base it was built on so any project release is traceable to the exact CodeCanyon version underneath it. The public document carries only the project SemVer and the user-facing change.

**Internal `Zaj-CHANGELOG.md` (vendor base recorded):**

```markdown
## [Unreleased]

> **Vendor base:** <Vendor> v7.6 (`author-v7.6`)

### Added
- Subscription export.

### Changed
- Upgraded vendor base v7.6 → v7.8.
```

**Public `docs/public-changelog.md` (same release, sanitized):**

```markdown
## v1.1.0 — <YYYY-MM-DD>

### Added
- Export your subscriptions to CSV.

### Changed
- Performance and reliability improvements.
```

**Scrub gate — the public document must not leak the vendor.** Run this before publishing any public release notes; it must print `✅ clean`:

```bash
PUBLIC=docs/public-changelog.md
if grep -iE 'workdo|codecanyon|envato|author-v|dash[- ]?saas' "$PUBLIC" >/dev/null 2>&1; then
  echo "❌ vendor reference leaked into $PUBLIC — sanitize before publishing:"
  grep -inE 'workdo|codecanyon|envato|author-v|dash[- ]?saas' "$PUBLIC"
else
  echo "✅ clean — no vendor references in $PUBLIC"
fi
# Expected: ✅ clean — add YOUR vendor's product name to the pattern too
```

Replace `dash[- ]?saas` with your own vendor's product name(s) so the grep catches the specific script you're built on, not just the generic terms.

:::caution[Public release notes never name the vendor]
"Upgraded vendor base v7.6 → v7.8" belongs in the **internal** `Zaj-CHANGELOG.md` only. The public note for the same release says "Performance and reliability improvements" — the customer never learns which CodeCanyon script powers the product. Treat the scrub gate above as a hard gate on the public document.
:::

:::note[Your first release is v1.0.0 — even if the vendor is v7.6]
The `author-vX.X.X` tag tracks the *vendor's* version. *Your* project's first public release is always `v1.0.0`, created later (release finalization), not here. Annotated tags (`git tag -a v1.0.0 -m "…"`) are recommended for releases.
:::

## Checklist

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

- [ ] **👤 Topics surfaced** — each recommended topic was presented and the operator's choice recorded.
- [ ] **🤖 Scaffold (if adopted)** — `Admin-Local/` + gitignored vault exist; per-project templates seeded in `Admin-Local/1-Project/3-Templates/`; `4-Audit-Reports/` and `6-Schema/` exist; `5-Scripts/README.md` exists without pre-created script folders; `90-DevLog/` exists with README, STATUS, lanes, and prompt JSONL ignored by default.
- [ ] **🔀 Standards (if adopted)** — commit format + Zaj customization strategy understood.
- [ ] **🔀 Versioning (if adopted)** — internal `Zaj-CHANGELOG.md` (records vendor base) started, package metadata set, and the public-changelog **scrub gate prints `✅ clean`** before any public release notes ship.

:::next[Next step]
[Phase 3 · Local development](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/)
:::

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 — surface three SHOULD-not-skip topics (project structure, commit + doc standards with the Zaj customization strategy, and SemVer + Zaj-CHANGELOG version management) and capture the operator’s decision on each — never silently drop them.

Steps at a glance:

Decide which topics to adopt — Present all three to the operator and record each choice in the project log before scaffolding anything.
Scaffold the project structure — A consistent Admin-Local/ layout gives every later phase a known home for credentials, docs, version snapshots, schema baselines, and the 90-DevLog build journal.
Adopt commit & documentation standards — Consistent commit hygiene prevents secrets leaking and makes history searchable. Never commit (already in .gitignore): .env / .env.* (except .env.example), vendor/, node_modules/, IDE settings.
Adopt version management — SemVer + Zaj-CHANGELOG — If you’ll ship updates (almost everyone), adopt semantic versioning and a Zaj-CHANGELOG.md now so your versions stay distinct from the vendor’s author-vX.X.X line.

Background

These three topics are SHOULD, not skip-by-default. The agent must surface them and capture the operator’s decision — never silently drop them.

Topic	What it gives you	Adopt when
Project structure	A predictable `Admin-Local/` home for the vault, docs, and versions	You want the full scaffold from day one (recommended)
Commit & doc standards	Searchable history + an auditable vendor seam	Team work, or you want disciplined history
Version management	SemVer + `Zaj-CHANGELOG.md` distinct from the vendor’s line	You’ll ship updates over time (almost everyone)

Steps

1. Decide which topics to adopt

Present all three to the operator and record each choice in Zaj-PROJECT.md before scaffolding anything.

Surface the three topics and record the decisions.
- ✅ Each of the three topics was presented, and its adopt/skip decision is written in Zaj-PROJECT.md.

2. Scaffold the project structure (if adopted)

A consistent Admin-Local/ layout gives every later phase a known home for credentials, docs, and version snapshots.

Per-project templates live at Admin-Local/1-Project/3-Templates/ (created by the scaffold step below). This page does not depend on any host-side Guides-v2/Templates/ pack — that path is legacy and is not guaranteed to exist in a per-project tree. Everything this step needs is either inlined below or seeded into 3-Templates/ here.

TPL=Admin-Local/1-Project/3-Templates
if [ -d "$TPL" ]; then
  echo "✅ Per-project templates at $TPL/ ($(find "$TPL" -type f | wc -l | tr -d ' ') files)"
else
  echo "ℹ️  $TPL/ not created yet — the scaffold step below creates it"
fi
# Expected: the scaffold step (next) creates $TPL/ and seeds it

If you have your org’s handbook pack available, you may copy its _Docs templates into 3-Templates/ instead of the inline stubs below — but the playbook never requires it. Never create empty stand-ins for deploy or env templates; if a real template is missing, use the minimal inline version here.

Create the Admin-Local/ scaffold.

mkdir -p Admin-Local/{0-SuperAdmin,1-Project,2-Docs,3-Versions,4-Backups,5-Archive}
mkdir -p Admin-Local/1-Project/{1-Info,2-Vault,3-Templates,4-Audit-Reports,5-Scripts,6-Schema,90-DevLog}
mkdir -p Admin-Local/1-Project/90-DevLog/{Plans,Sessions,Decisions,Prompts,Handoffs,_Archive}
mkdir -p Admin-Local/3-Versions/1-v${VERSION}/{1-Originals,2-Modifications}
# Expected: the Admin-Local tree is created

✅ Phases 3–12 now have a known home for credentials, docs, audit reports, replay-script records, schema baselines, the build journal, and versions.

Lock the vault so credentials can never be committed.

printf '*\n!.gitignore\n!README.md\n' > Admin-Local/1-Project/2-Vault/.gitignore
# Expected: the vault ignores everything except its .gitignore + README

✅ Admin-Local/1-Project/2-Vault/.gitignore ignores all but itself + README.

Create the replay-script index only. Do not pre-create empty payment/email/content folders. Scripts are generated later from the guide step + rules + boilerplate, so the project starts with only the taxonomy and provider inventory matrix.

cat > Admin-Local/1-Project/5-Scripts/README.md <<'EOF'
# 5-Scripts — <PROJECT>

Persist replay scripts here when a setup, operations, migration, or growth step needs repeatable writes to the vendor database or a third-party API.

## Taxonomy

- `1-Setup/` — initial configuration during Phases 6-8.
- `2-Operations/` — future re-syncs, cleanups, and health checks.
- `3-Migrations/` — future data migrations and vendor-update data fixes.
- `4-Growth/` — future promos, new tiers, and experiments.
- `archive/` — retired scripts moved for audit, never deleted.

## Provider inventory

| Function | Provider/service | Status | Script path | Notes |
|---|---|---|---|---|
| Payments | Stripe | 🟡 placeholder |  | Use if this app has Stripe billing. |
| Payments | PayPal | ⬜ not used |  |  |
| Email | SMTP | 🟡 placeholder |  |  |
| Email | SendGrid | ⬜ not used |  |  |
| Content | DemoContentCleanup | 🟡 placeholder |  | Use only if demo rows need scripted cleanup. |
| Auth | Roles | 🟡 placeholder |  |  |
| Branding | Assets | 🟡 placeholder |  |  |
| Database | SchemaInspection | 🟡 placeholder |  |  |

Status: `✅ configured` = script exists, `🟡 placeholder` = expected but no script yet, `⬜ not used` = intentionally out of scope.
EOF
# Expected: only 5-Scripts/README.md exists; lane/function/provider folders are lazy-created later

✅ Admin-Local/1-Project/5-Scripts/README.md records the taxonomy and provider inventory without empty script folders.

Seed the build journal. 90-DevLog/ is the working journal for plans, session logs, decisions, prompt capture, and handoffs. It is a high-band meta lane: 1-9 lanes hold project content; 90-99 lanes hold process/meta artifacts that should sort last.

DEVLOG=Admin-Local/1-Project/90-DevLog
mkdir -p "$DEVLOG"/{Plans,Sessions,Decisions,Prompts,Handoffs,_Archive}
touch "$DEVLOG"/{Plans,Sessions,Decisions,Handoffs,_Archive}/.gitkeep
printf '# keep\n' > "$DEVLOG/Prompts/.gitkeep"
cat > "$DEVLOG/Prompts/.gitignore" <<'EOF'
*.jsonl
distilled/
!.gitignore
!.gitkeep
!README.md
EOF
cat > "$DEVLOG/README.md" <<'EOF'
# 90-DevLog — the build journal

Single home for dev-process artifacts: plans, session logs, decisions, prompts, and handoffs.
Numbered `90-` as a reserved high band so it sorts last and never forces a renumber of the
`1-9` content lanes (`1-Info`, `2-Vault`, `5-Scripts`, `6-Schema`, etc.).

Boundary: root `Zaj-*` files are the canonical record of what shipped. `90-DevLog/` is the
working journal for how the work happened.

## Lanes

| Path | Holds | Naming |
|---|---|---|
| `STATUS.md` | Active plan, in-flight agents, hot-file locks, blockers | fixed name |
| `Plans/` | Phase or feature plans | `NNN-type-slug.md` |
| `Sessions/` | Per-session logs | `YYYY-MM-DD-HHMM-agent-slug.md` |
| `Decisions/` | ADR-lite decisions | `NNN-type-slug.md` |
| `Prompts/` | Local prompt JSONL from `UserPromptSubmit` | `YYYY-Www.jsonl` |
| `Handoffs/` | Agent-switch handoffs | `YYYY-MM-DD-HHMM-from-to.md` |
| `_Archive/` | Completed/stale journal artifacts | mirror source name |

## Rules

- `1-9` = project content lanes; `90-99` = sorts-last/meta lanes.
- Plans and Decisions use monotonic IDs; never reset, reuse, or reorder them.
- Sessions, Handoffs, and Prompts use timestamps so parallel agents do not race a shared counter.
- Agent identity belongs in frontmatter and slug, never as the sort key.
- `STATUS.md` is the coordination surface; claim hot files before editing.
EOF
cat > "$DEVLOG/STATUS.md" <<'EOF'
# DevLog STATUS — <PROJECT>

Last updated: <YYYY-MM-DD> (<AGENT>)

## Where we are
- Current phase: Phase 2 — Code & repository setup

## Active plan
- None yet.

## In-flight agents
| Agent | Working on | Hot files claimed |
|---|---|---|
| <agent> | <task> | `<path>` |

> Hot-file locks: one agent per hot file. Do not edit, move, overwrite, or archive another live agent's claimed file without coordinating first.

## Blockers
- None.
EOF
# Expected: 90-DevLog has README, STATUS, lanes, and prompt JSONL is ignored by default

✅ Admin-Local/1-Project/90-DevLog/ exists with README.md, STATUS.md, lane stubs, and local prompt JSONL ignored by default.

Seed the per-project templates into 3-Templates/. These are minimal, self-contained, and require no external pack. (If your org’s handbook _Docs pack is available, you may copy its richer versions over these instead.)

TPL=Admin-Local/1-Project/3-Templates

# Zaj-PROJECT template — current truth for non-secret project facts
cat > "$TPL/T01-Zaj-PROJECT.md" <<'EOF'
# Zaj-PROJECT — <PROJECT>

Last updated: <YYYY-MM-DD>
Current phase: Phase 2 — Code & repository setup

> Non-secret project bible. Current truth for project identity, toolchain versions, paths, environments, SSH aliases, and tracker links.
> Boundary: this file records current facts; `Zaj-CUSTOMIZATIONS.md` records vendor deviations and why they exist.

## Project Identity

| Field | Value |
|---|---|
| Project name | <PROJECT> |
| CodeCanyon item | <url> |
| Vendor / author | <vendor> |
| Vendor version | <author-vX.Y.Z> |
| Product type | <SaaS / marketplace / directory / other> |

## Repository And Branch Model

| Field | Value |
|---|---|
| Repo URL | <git@host:org/repo.git> |
| Default branch | develop |
| Release branch | main |

## Environment Matrix

Use one row per real environment. `staging-primary` is only the common example; use the actual keys this project has, such as `qa`, `uat`, `client-demo`, `sandbox`, or multiple staging rows.

| Env key | Role | URL / domain | Hosting account | SSH alias | Host | User | Port | Deploy target | Source branch | Web PHP | CLI PHP binary | DB name | Noindex / robots | Credential pointer | Last verified |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| local | Local dev | https://<project>.test | N/A | N/A | 127.0.0.1 | <local user> | N/A | local | develop | Herd <x.y> | <path> | <project>_local | N/A | op://<vault>/Local | <date> |
| staging-primary | Non-production | https://nonprod.example.com | <account/order> | <alias> | <host/IP> | <user> | <port> | staging | staging | <pending Phase 4> | <pending Phase 4> | <project>_staging | noindex + Disallow | op://<vault>/Staging | <date> |
| production | Production | https://<domain> | <account/order> | <alias> | <host/IP> | <user> | <port> | production | main | <pending Phase 12> | <pending Phase 4> | <project>_production | index allowed | op://<vault>/Production | <date> |

## Toolchain Parity

| Surface | Local | Non-production target(s) | Production | Target / rule |
|---|---|---|---|---|
| PHP | <x.y.z> | <pending> | <pending> | strictest root `composer.json` + production package requirement in `composer.lock` |
| Composer | <2.x> | <pending> | <pending> | same major/minor where practical |
| Node | <x.y.z> | build-local only | build-local only | `.tool-versions` / package lock |
| DB engine | <MySQL/MariaDB x.y> | <x.y> | <x.y> | same engine family when possible |
| DB charset/collation | utf8mb4 / utf8mb4_unicode_ci | utf8mb4 / utf8mb4_unicode_ci | utf8mb4 / utf8mb4_unicode_ci | must match before deploy |

## Canonical Paths

| Purpose | Path |
|---|---|
| Project profile | `Zaj-PROJECT.md` |
| Progress tracker | `Zaj-PROGRESS.md` |
| Deferred work | `Zaj-BACKLOG.md` |
| Internal changelog | `Zaj-CHANGELOG.md` |
| Vendor-deviation ledger | `Zaj-CUSTOMIZATIONS.md` |
| Project info lane | `Admin-Local/1-Project/1-Info/` |
| Research reports | `Admin-Local/1-Project/1-Info/Research/` |
| Build journal | `Admin-Local/1-Project/90-DevLog/` |
| Playbook feedback | `Admin-Local/1-Project/playbook-feedback.md` |

## 1Password Pointers

| Item | Pointer | Expected fields |
|---|---|---|
| Local credential item | `op://<vault>/Local` | `DB_CONNECTION`, `DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`, `APP_KEY`, `env_file` |
| Staging credential item | `op://<vault>/Staging` | Same flat field set; use the real non-production item name if this row is `qa`, `uat`, `client-demo`, etc. |
| Production credential item | `op://<vault>/Production` | Same flat field set; `DB_PASSWORD`, `APP_KEY`, and `env_file` are concealed. |
EOF

cat > "$TPL/tool-versions.template" <<'EOF'
php <PHP_VERSION>
nodejs <NODE_VERSION>
composer <COMPOSER_VERSION>
EOF

# Expected: T01-Zaj-PROJECT.md + tool-versions.template exist in 3-Templates/

Instantiate the project records from those templates:
Terminal window
```
TPL=Admin-Local/1-Project/3-Templates
cp "$TPL/T01-Zaj-PROJECT.md" Zaj-PROJECT.md
cp "$TPL/tool-versions.template" .tool-versions
printf '# Project vault\n\nGitignored credentials and env templates.\n' \
  > Admin-Local/1-Project/2-Vault/README.md
# Expected: Zaj-PROJECT.md + .tool-versions + vault README exist
```
Fill Zaj-PROJECT from infrastructure created in Prerequisites — domains, IPs, SSH aliases, repo URL, DB names, current local PHP/Composer/Node, and placeholder deploy PHP rows that Phase 4 will confirm. Keep .tool-versions aligned with the chosen PHP / Node / Composer targets. (Zaj-CHANGELOG.md is created in §4 below — keep it out of this step so the public/internal split is set up correctly.)

AI agent wiring: if Phase 1 did not already seed rules, drop Cursor/Gemini/AntiGravity rule files into the project’s own AI config (e.g. .cursor/rules/, GEMINI.md) and ensure .cursorignore / .geminiignore exclude vendor/, node_modules/, and Admin-Local/1-Project/2-Vault/. Do not assume a host-side Guides-v2/Templates/ pack — author them in-project or copy from your handbook if you have one.
- ✅ Zaj-PROJECT.md exists with real domains, IPs, SSH aliases, repo URL, DB names, local toolchain facts, and the 90-DevLog canonical path; .tool-versions exists; per-project templates are seeded in 3-Templates/; vault README explains the gitignored area.

3. Adopt commit & documentation standards (if adopted)

Consistent commit hygiene prevents secrets leaking and makes history searchable. Never commit (already in .gitignore): .env / .env.* (except .env.example), vendor/, node_modules/, IDE settings. Always commit: composer.json + composer.lock, package.json + package-lock.json, config/*.php, database/migrations/*.php, project docs.

A conventional commit format keeps the log self-documenting — emoji + type tag + verb-thing + description:

Type	Format	Example
Author import	`📦 ⬜ T1 Setup-Author: …`	`📦 ⬜ T1 Setup-Author: Import v10.4`
Setup/config	`🔧 🟦 T2 Setup-Config: …`	`🔧 🟦 T2 Setup-Config: Add GA tracking`
App feature	`🔨 🟪 T3 Add-Feature: …`	`🔨 🟪 T3 Add-Feature: Arabic support`
Deploy	`🚀 🟩 T4 Deploy-App: …`	`🚀 🟩 T4 Deploy-App: Deploy v1.5.1`
ServerSync	`🔄 ⬛ T5 ServerSync-Setup: …`	`🔄 ⬛ T5 ServerSync-Setup: Capture SMTP config`

Documentation update schedule — refresh when the trigger fires, not “whenever you remember”:

File	Update when
`Zaj-PROJECT.md`	Every current-truth change: repo, toolchain, DB names, SSH aliases, deploy paths, server/runtime versions
`Zaj-PROGRESS.md`	During active phase/step work and after each verified gate
`Zaj-BACKLOG.md`	Deferred work, phase-entry blockers, human-only follow-ups, and future work
`Zaj-CHANGELOG.md`	Each phase completion and release-worthy internal change
`Zaj-CUSTOMIZATIONS.md`	Any vendor/config deviation or operational decision that affects future upgrades
`Admin-Local/1-Project/90-DevLog/Decisions/`	Material “why” decisions that need an audit trail
`Admin-Local/1-Project/4-Audit-Reports/`	Security, compliance, audit, and QA evidence
`CLAUDE.md` / `AGENTS.md`	AI rules, vendor doc extracts, tooling changes

Before any customization in this or later phases, know which mechanism to use — this is what prevents “modified vendor file” sprawl that blocks future updates:

Mechanism	Use when	Lives in
Vendor Customizations	Patching an existing vendor file	`resources/vendor-customizations/`
ZajModules	Adding new functionality (route, view, service)	`packages/ZajModules/{Type}/{Cat}/{Name}/`
`_zaj` migrations	Extending a vendor table schema	`database/migrations/*_zaj.php`

The decision is three questions: editing an existing vendor file → Vendor Customization; adding something new → ZajModule; adding columns to a vendor table → _zaj migration.

4. Adopt version management — SemVer + Zaj-CHANGELOG (if adopted)

If you’ll ship updates (almost everyone), adopt semantic versioning and a Zaj-CHANGELOG.md now so your versions stay distinct from the vendor’s author-vX.X.X line. vMAJOR.MINOR.PATCH — bump by the nature of the change:

Change	Bump	Example
Bug fix / security patch	PATCH (`1.0.0 → 1.0.1`)	Fixed login error
New feature, backward compatible	MINOR (`1.0.0 → 1.1.0`)	Added export
Breaking change	MAJOR (`1.0.0 → 2.0.0`)	Changed API responses

Git tags:

Type	Command	Use for
Annotated (recommended)	`git tag -a v1.0.0 -m "First stable release"`	Production releases
Lightweight	`git tag v1.0.0`	Quick local markers only

Release workflow:

Develop work — develop branch; Zaj-CHANGELOG.md [Unreleased] section grows.
Prepare release — promote to staging, test, bump version in composer.json / package.json.
Release — deploy production, create annotated tag vX.Y.Z.
Sync branches — mirror production to main when your pipeline uses it.

Decision journal — the current version fields live in Zaj-PROJECT.md; the release history lives in Zaj-CHANGELOG.md; material “why” decisions live in 90-DevLog/Decisions/. If this project needs an audit trail for the version-management choice, add one decision note there:

mkdir -p Admin-Local/1-Project/90-DevLog/Decisions
DECISION="Admin-Local/1-Project/90-DevLog/Decisions/001-decision-version-management.md"
if [ ! -f "$DECISION" ]; then
  cat > "$DECISION" <<'EOF'
# Decision 001 — Version management

Date: <YYYY-MM-DD>
Decision: Use project SemVer with root Zaj-CHANGELOG.md and internal Vendor base markers.
Rationale: Keep our release line separate from the CodeCanyon author snapshot line.
Evidence: composer.json/package.json version fields, author-vX.X.X tag, Zaj-CHANGELOG.md.
EOF
fi
# Expected: optional decision note lives under 90-DevLog/Decisions/; no separate 1-Info work-log file is created

Keep changelogs in Keep a Changelog form (Added / Changed / Deprecated / Removed / Fixed / Security), and align package metadata: set composer.json and package.json name/version/description, change license to proprietary, and keep package.json private: true.

echo "composer.json:" && grep '"version"' composer.json | head -1
echo "package.json:" && grep '"version"' package.json | head -1
# Expected: both show "1.0.0" (your project line, not the vendor's author tag)

Two changelogs: INTERNAL (vendor-aware) vs PUBLIC (sanitized)

A public-facing CHANGELOG or release-notes page must never name the CodeCanyon vendor — not “WorkDo”, “CodeCanyon”, “Envato”, the vendor product name, nor an author-vX tag. That’s both a product-naming rule (customers see your brand, not the underlying script) and basic operational hygiene. So keep two documents:

Document	Audience	May mention vendor?	Records
`Zaj-CHANGELOG.md` (internal)	You + your team	✅ Yes — that’s the point	Project SemVer + vendor base per release (e.g. `Vendor base: <Vendor> v7.6`), vendor upgrades logged as `### Changed`
`docs/public-changelog.md` (or release-notes page)	Customers / public	❌ Never	Project name + your own SemVer + user-facing changes only

Two version lines stay distinct in BOTH:

Project version (v1.0.0, v1.1.0, …) — your own SemVer, tagged vX.Y.Z. First release is v1.0.0 even if the vendor is at v7.6.
Vendor (author) version (author-v7.6, …) — the CodeCanyon base, tracked by author-vX.X.X git tags. Internal only — never in the public document.

Each release records, internally, the vendor base it was built on so any project release is traceable to the exact CodeCanyon version underneath it. The public document carries only the project SemVer and the user-facing change.

Internal Zaj-CHANGELOG.md (vendor base recorded):

## [Unreleased]

> **Vendor base:** <Vendor> v7.6 (`author-v7.6`)

### Added
- Subscription export.

### Changed
- Upgraded vendor base v7.6 → v7.8.

Public docs/public-changelog.md (same release, sanitized):

## v1.1.0 — <YYYY-MM-DD>

### Added
- Export your subscriptions to CSV.

### Changed
- Performance and reliability improvements.

Scrub gate — the public document must not leak the vendor. Run this before publishing any public release notes; it must print ✅ clean:

PUBLIC=docs/public-changelog.md
if grep -iE 'workdo|codecanyon|envato|author-v|dash[- ]?saas' "$PUBLIC" >/dev/null 2>&1; then
  echo "❌ vendor reference leaked into $PUBLIC — sanitize before publishing:"
  grep -inE 'workdo|codecanyon|envato|author-v|dash[- ]?saas' "$PUBLIC"
else
  echo "✅ clean — no vendor references in $PUBLIC"
fi
# Expected: ✅ clean — add YOUR vendor's product name to the pattern too

Replace dash[- ]?saas with your own vendor’s product name(s) so the grep catches the specific script you’re built on, not just the generic terms.

Checklist

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

👤 Topics surfaced — each recommended topic was presented and the operator’s choice recorded.
🤖 Scaffold (if adopted) — Admin-Local/ + gitignored vault exist; per-project templates seeded in Admin-Local/1-Project/3-Templates/; 4-Audit-Reports/ and 6-Schema/ exist; 5-Scripts/README.md exists without pre-created script folders; 90-DevLog/ exists with README, STATUS, lanes, and prompt JSONL ignored by default.
🔀 Standards (if adopted) — commit format + Zaj customization strategy understood.
🔀 Versioning (if adopted) — internal Zaj-CHANGELOG.md (records vendor base) started, package metadata set, and the public-changelog scrub gate prints ✅ clean before any public release notes ship.

Phase 3 · Local development

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 · Project standards (recommended)
- url: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/02-code-repo/07-project-standards/
- shelf: Build & Create
- doc_type: implementation playbook
- status: current
- kind: playbook
- category: tech-stack
- subcategory: laravel
- topic: codecanyon
- phase: 2
- part_number: 7 (legacy stepNumber frontmatter)
- legacy_step_number: 7
- est_time: ~20–40 min if adopted
- description: Project-structure scaffolding (Admin-Local vault + docs), commit & documentation standards with the Zaj customization strategy, and version management (SemVer + Zaj-CHANGELOG) — SHOULD, not skip-by-default.
- tags: codecanyon, laravel, project-standards, versioning

## Execution rules (binding)
- This is Part 7 of phase 2 (~20–40 min if adopted) — 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 · Project standards (recommended)

## TL;DR

**Objective** — surface three **SHOULD-not-skip** topics (project structure, commit + doc standards with the Zaj customization strategy, and SemVer + Zaj-CHANGELOG version management) and capture the operator's decision on each — never silently drop them.

**Steps at a glance:**
1. **Decide which topics to adopt** — Present all three to the operator and record each choice in the project
   log before scaffolding anything.
2. **Scaffold the project structure** — A consistent `Admin-Local/` layout gives every later phase a known home
   for credentials, docs, version snapshots, schema baselines, and the `90-DevLog` build journal.
3. **Adopt commit & documentation standards** — Consistent commit hygiene prevents secrets leaking and makes
   history searchable. Never commit (already in `.gitignore`): `.env` / `.env.*` (except `.env.example`),
   `vendor/`, `node_modules/`, IDE settings.
4. **Adopt version management — SemVer + Zaj-CHANGELOG** — If you'll ship updates (almost everyone), adopt
   semantic versioning and a `Zaj-CHANGELOG.md` now so your versions stay distinct from the vendor's
   `author-vX.X.X` line.

:::note[User part + done-when]
**👤 User part** — these are **decisions**: the operator chooses which to adopt and records the call. The agent must present all three, never assume yes or no, and scaffold only what's chosen.

**Done when** each topic was surfaced and its decision recorded — and, for anything adopted, the scaffold / standards / `Zaj-CHANGELOG.md` actually exist. &nbsp;·&nbsp; **⏱ ~20–40 min if adopted** &nbsp;·&nbsp; 🔀 (👤 decisions, 🤖 scaffolding).
:::

## Background

These three topics are **SHOULD**, not skip-by-default. The agent must **surface** them and capture the operator's decision — never silently drop them.

| Topic | What it gives you | Adopt when |
|---|---|---|
| Project structure | A predictable `Admin-Local/` home for the vault, docs, and versions | You want the full scaffold from day one (recommended) |
| Commit & doc standards | Searchable history + an auditable vendor seam | Team work, or you want disciplined history |
| Version management | SemVer + `Zaj-CHANGELOG.md` distinct from the vendor's line | You'll ship updates over time (almost everyone) |

## Steps

### 1. Decide which topics to adopt

Present all three to the operator and record each choice in `Zaj-PROJECT.md` before scaffolding anything.

:::note[Who does this]
👤 **User** (the operator) decides adopt-or-not for each topic — this is a workflow preference, so the agent surfaces and records rather than assuming.
:::

<Steps>

1. **Surface the three topics and record the decisions.**

   - ✅ Each of the three topics was presented, and its adopt/skip decision is written in `Zaj-PROJECT.md`.

</Steps>

### 2. Scaffold the project structure (if adopted)

A consistent `Admin-Local/` layout gives every later phase a known home for credentials, docs, and version snapshots.

:::note[Where templates live — per-project, not a host-side pack]
Per-project templates live at **`Admin-Local/1-Project/3-Templates/`** (created by the scaffold step below). This page does **not** depend on any host-side `Guides-v2/Templates/` pack — that path is legacy and is **not** guaranteed to exist in a per-project tree. Everything this step needs is either inlined below or seeded into `3-Templates/` here.

```bash
TPL=Admin-Local/1-Project/3-Templates
if [ -d "$TPL" ]; then
  echo "✅ Per-project templates at $TPL/ ($(find "$TPL" -type f | wc -l | tr -d ' ') files)"
else
  echo "ℹ️  $TPL/ not created yet — the scaffold step below creates it"
fi
# Expected: the scaffold step (next) creates $TPL/ and seeds it
```

If you have your org's handbook pack available, you **may** copy its `_Docs` templates into `3-Templates/` instead of the inline stubs below — but the playbook never requires it. Never create empty stand-ins for deploy or env templates; if a real template is missing, use the minimal inline version here.
:::

<Steps>

1. **Create the `Admin-Local/` scaffold**.

   ```bash
   mkdir -p Admin-Local/{0-SuperAdmin,1-Project,2-Docs,3-Versions,4-Backups,5-Archive}
   mkdir -p Admin-Local/1-Project/{1-Info,2-Vault,3-Templates,4-Audit-Reports,5-Scripts,6-Schema,90-DevLog}
   mkdir -p Admin-Local/1-Project/90-DevLog/{Plans,Sessions,Decisions,Prompts,Handoffs,_Archive}
   mkdir -p Admin-Local/3-Versions/1-v${VERSION}/{1-Originals,2-Modifications}
   # Expected: the Admin-Local tree is created
   ```

   - ✅ Phases 3–12 now have a known home for credentials, docs, audit reports, replay-script records, schema baselines, the build journal, and versions.

2. **Lock the vault** so credentials can never be committed.

   ```bash
   printf '*\n!.gitignore\n!README.md\n' > Admin-Local/1-Project/2-Vault/.gitignore
   # Expected: the vault ignores everything except its .gitignore + README
   ```

   - ✅ `Admin-Local/1-Project/2-Vault/.gitignore` ignores all but itself + README.

3. **Create the replay-script index only.** Do not pre-create empty payment/email/content folders. Scripts are generated later from the guide step + rules + boilerplate, so the project starts with only the taxonomy and provider inventory matrix.

   ```bash
   cat > Admin-Local/1-Project/5-Scripts/README.md <<'EOF'
   # 5-Scripts — <PROJECT>

   Persist replay scripts here when a setup, operations, migration, or growth step needs repeatable writes to the vendor database or a third-party API.

   ## Taxonomy

   - `1-Setup/` — initial configuration during Phases 6-8.
   - `2-Operations/` — future re-syncs, cleanups, and health checks.
   - `3-Migrations/` — future data migrations and vendor-update data fixes.
   - `4-Growth/` — future promos, new tiers, and experiments.
   - `archive/` — retired scripts moved for audit, never deleted.

   ## Provider inventory

   | Function | Provider/service | Status | Script path | Notes |
   |---|---|---|---|---|
   | Payments | Stripe | 🟡 placeholder |  | Use if this app has Stripe billing. |
   | Payments | PayPal | ⬜ not used |  |  |
   | Email | SMTP | 🟡 placeholder |  |  |
   | Email | SendGrid | ⬜ not used |  |  |
   | Content | DemoContentCleanup | 🟡 placeholder |  | Use only if demo rows need scripted cleanup. |
   | Auth | Roles | 🟡 placeholder |  |  |
   | Branding | Assets | 🟡 placeholder |  |  |
   | Database | SchemaInspection | 🟡 placeholder |  |  |

   Status: `✅ configured` = script exists, `🟡 placeholder` = expected but no script yet, `⬜ not used` = intentionally out of scope.
   EOF
   # Expected: only 5-Scripts/README.md exists; lane/function/provider folders are lazy-created later
   ```

   - ✅ `Admin-Local/1-Project/5-Scripts/README.md` records the taxonomy and provider inventory without empty script folders.

4. **Seed the build journal.** `90-DevLog/` is the working journal for plans, session logs, decisions, prompt capture, and handoffs. It is a high-band meta lane: `1-9` lanes hold project content; `90-99` lanes hold process/meta artifacts that should sort last.

   ```bash
   DEVLOG=Admin-Local/1-Project/90-DevLog
   mkdir -p "$DEVLOG"/{Plans,Sessions,Decisions,Prompts,Handoffs,_Archive}
   touch "$DEVLOG"/{Plans,Sessions,Decisions,Handoffs,_Archive}/.gitkeep
   printf '# keep\n' > "$DEVLOG/Prompts/.gitkeep"
   cat > "$DEVLOG/Prompts/.gitignore" <<'EOF'
   *.jsonl
   distilled/
   !.gitignore
   !.gitkeep
   !README.md
   EOF
   cat > "$DEVLOG/README.md" <<'EOF'
   # 90-DevLog — the build journal

   Single home for dev-process artifacts: plans, session logs, decisions, prompts, and handoffs.
   Numbered `90-` as a reserved high band so it sorts last and never forces a renumber of the
   `1-9` content lanes (`1-Info`, `2-Vault`, `5-Scripts`, `6-Schema`, etc.).

   Boundary: root `Zaj-*` files are the canonical record of what shipped. `90-DevLog/` is the
   working journal for how the work happened.

   ## Lanes

   | Path | Holds | Naming |
   |---|---|---|
   | `STATUS.md` | Active plan, in-flight agents, hot-file locks, blockers | fixed name |
   | `Plans/` | Phase or feature plans | `NNN-type-slug.md` |
   | `Sessions/` | Per-session logs | `YYYY-MM-DD-HHMM-agent-slug.md` |
   | `Decisions/` | ADR-lite decisions | `NNN-type-slug.md` |
   | `Prompts/` | Local prompt JSONL from `UserPromptSubmit` | `YYYY-Www.jsonl` |
   | `Handoffs/` | Agent-switch handoffs | `YYYY-MM-DD-HHMM-from-to.md` |
   | `_Archive/` | Completed/stale journal artifacts | mirror source name |

   ## Rules

   - `1-9` = project content lanes; `90-99` = sorts-last/meta lanes.
   - Plans and Decisions use monotonic IDs; never reset, reuse, or reorder them.
   - Sessions, Handoffs, and Prompts use timestamps so parallel agents do not race a shared counter.
   - Agent identity belongs in frontmatter and slug, never as the sort key.
   - `STATUS.md` is the coordination surface; claim hot files before editing.
   EOF
   cat > "$DEVLOG/STATUS.md" <<'EOF'
   # DevLog STATUS — <PROJECT>

   Last updated: <YYYY-MM-DD> (<AGENT>)

   ## Where we are
   - Current phase: Phase 2 — Code & repository setup

   ## Active plan
   - None yet.

   ## In-flight agents
   | Agent | Working on | Hot files claimed |
   |---|---|---|
   | <agent> | <task> | `<path>` |

   > Hot-file locks: one agent per hot file. Do not edit, move, overwrite, or archive another live agent's claimed file without coordinating first.

   ## Blockers
   - None.
   EOF
   # Expected: 90-DevLog has README, STATUS, lanes, and prompt JSONL is ignored by default
   ```

   - ✅ `Admin-Local/1-Project/90-DevLog/` exists with `README.md`, `STATUS.md`, lane stubs, and local prompt JSONL ignored by default.

5. **Seed the per-project templates** into `3-Templates/`. These are minimal, self-contained, and require no external pack. (If your org's handbook `_Docs` pack is available, you may copy its richer versions over these instead.)

   ```bash
   TPL=Admin-Local/1-Project/3-Templates

   # Zaj-PROJECT template — current truth for non-secret project facts
   cat > "$TPL/T01-Zaj-PROJECT.md" <<'EOF'
   # Zaj-PROJECT — <PROJECT>

   Last updated: <YYYY-MM-DD>
   Current phase: Phase 2 — Code & repository setup

   > Non-secret project bible. Current truth for project identity, toolchain versions, paths, environments, SSH aliases, and tracker links.
   > Boundary: this file records current facts; `Zaj-CUSTOMIZATIONS.md` records vendor deviations and why they exist.

   ## Project Identity

   | Field | Value |
   |---|---|
   | Project name | <PROJECT> |
   | CodeCanyon item | <url> |
   | Vendor / author | <vendor> |
   | Vendor version | <author-vX.Y.Z> |
   | Product type | <SaaS / marketplace / directory / other> |

   ## Repository And Branch Model

   | Field | Value |
   |---|---|
   | Repo URL | <git@host:org/repo.git> |
   | Default branch | develop |
   | Release branch | main |

   ## Environment Matrix

   Use one row per real environment. `staging-primary` is only the common example; use the actual keys this project has, such as `qa`, `uat`, `client-demo`, `sandbox`, or multiple staging rows.

   | Env key | Role | URL / domain | Hosting account | SSH alias | Host | User | Port | Deploy target | Source branch | Web PHP | CLI PHP binary | DB name | Noindex / robots | Credential pointer | Last verified |
   |---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
   | local | Local dev | https://<project>.test | N/A | N/A | 127.0.0.1 | <local user> | N/A | local | develop | Herd <x.y> | <path> | <project>_local | N/A | op://<vault>/Local | <date> |
   | staging-primary | Non-production | https://nonprod.example.com | <account/order> | <alias> | <host/IP> | <user> | <port> | staging | staging | <pending Phase 4> | <pending Phase 4> | <project>_staging | noindex + Disallow | op://<vault>/Staging | <date> |
   | production | Production | https://<domain> | <account/order> | <alias> | <host/IP> | <user> | <port> | production | main | <pending Phase 12> | <pending Phase 4> | <project>_production | index allowed | op://<vault>/Production | <date> |

   ## Toolchain Parity

   | Surface | Local | Non-production target(s) | Production | Target / rule |
   |---|---|---|---|---|
   | PHP | <x.y.z> | <pending> | <pending> | strictest root `composer.json` + production package requirement in `composer.lock` |
   | Composer | <2.x> | <pending> | <pending> | same major/minor where practical |
   | Node | <x.y.z> | build-local only | build-local only | `.tool-versions` / package lock |
   | DB engine | <MySQL/MariaDB x.y> | <x.y> | <x.y> | same engine family when possible |
   | DB charset/collation | utf8mb4 / utf8mb4_unicode_ci | utf8mb4 / utf8mb4_unicode_ci | utf8mb4 / utf8mb4_unicode_ci | must match before deploy |

   ## Canonical Paths

   | Purpose | Path |
   |---|---|
   | Project profile | `Zaj-PROJECT.md` |
   | Progress tracker | `Zaj-PROGRESS.md` |
   | Deferred work | `Zaj-BACKLOG.md` |
   | Internal changelog | `Zaj-CHANGELOG.md` |
   | Vendor-deviation ledger | `Zaj-CUSTOMIZATIONS.md` |
   | Project info lane | `Admin-Local/1-Project/1-Info/` |
   | Research reports | `Admin-Local/1-Project/1-Info/Research/` |
   | Build journal | `Admin-Local/1-Project/90-DevLog/` |
   | Playbook feedback | `Admin-Local/1-Project/playbook-feedback.md` |

   ## 1Password Pointers

   | Item | Pointer | Expected fields |
   |---|---|---|
   | Local credential item | `op://<vault>/Local` | `DB_CONNECTION`, `DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`, `APP_KEY`, `env_file` |
   | Staging credential item | `op://<vault>/Staging` | Same flat field set; use the real non-production item name if this row is `qa`, `uat`, `client-demo`, etc. |
   | Production credential item | `op://<vault>/Production` | Same flat field set; `DB_PASSWORD`, `APP_KEY`, and `env_file` are concealed. |
   EOF

   cat > "$TPL/tool-versions.template" <<'EOF'
   php <PHP_VERSION>
   nodejs <NODE_VERSION>
   composer <COMPOSER_VERSION>
   EOF

   # Expected: T01-Zaj-PROJECT.md + tool-versions.template exist in 3-Templates/
   ```

6. **Instantiate the project records** from those templates:

   ```bash
   TPL=Admin-Local/1-Project/3-Templates
   cp "$TPL/T01-Zaj-PROJECT.md" Zaj-PROJECT.md
   cp "$TPL/tool-versions.template" .tool-versions
   printf '# Project vault\n\nGitignored credentials and env templates.\n' \
     > Admin-Local/1-Project/2-Vault/README.md
   # Expected: Zaj-PROJECT.md + .tool-versions + vault README exist
   ```

   Fill **Zaj-PROJECT** from infrastructure created in [Prerequisites](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/02-code-repo/01-prerequisites/) — domains, IPs, SSH aliases, repo URL, DB names, current local PHP/Composer/Node, and placeholder deploy PHP rows that Phase 4 will confirm. Keep `.tool-versions` aligned with the chosen PHP / Node / Composer targets. (`Zaj-CHANGELOG.md` is created in §4 below — keep it out of this step so the public/internal split is set up correctly.)

   **AI agent wiring:** if Phase 1 did not already seed rules, drop Cursor/Gemini/AntiGravity rule files into the project's own AI config (e.g. `.cursor/rules/`, `GEMINI.md`) and ensure `.cursorignore` / `.geminiignore` exclude `vendor/`, `node_modules/`, and `Admin-Local/1-Project/2-Vault/`. Do **not** assume a host-side `Guides-v2/Templates/` pack — author them in-project or copy from your handbook if you have one.

   - ✅ `Zaj-PROJECT.md` exists with real domains, IPs, SSH aliases, repo URL, DB names, local toolchain facts, and the `90-DevLog` canonical path; `.tool-versions` exists; per-project templates are seeded in `3-Templates/`; vault README explains the gitignored area.

</Steps>

### 3. Adopt commit & documentation standards (if adopted)

Consistent commit hygiene prevents secrets leaking and makes history searchable. **Never commit** (already in `.gitignore`): `.env` / `.env.*` (except `.env.example`), `vendor/`, `node_modules/`, IDE settings. **Always commit**: `composer.json` + `composer.lock`, `package.json` + `package-lock.json`, `config/*.php`, `database/migrations/*.php`, project docs.

A conventional commit format keeps the log self-documenting — emoji + type tag + verb-thing + description:

| Type | Format | Example |
|---|---|---|
| Author import | `📦 ⬜ T1 Setup-Author: …` | `📦 ⬜ T1 Setup-Author: Import v10.4` |
| Setup/config | `🔧 🟦 T2 Setup-Config: …` | `🔧 🟦 T2 Setup-Config: Add GA tracking` |
| App feature | `🔨 🟪 T3 Add-Feature: …` | `🔨 🟪 T3 Add-Feature: Arabic support` |
| Deploy | `🚀 🟩 T4 Deploy-App: …` | `🚀 🟩 T4 Deploy-App: Deploy v1.5.1` |
| ServerSync | `🔄 ⬛ T5 ServerSync-Setup: …` | `🔄 ⬛ T5 ServerSync-Setup: Capture SMTP config` |

**Documentation update schedule** — refresh when the trigger fires, not "whenever you remember":

| File | Update when |
| --- | --- |
| `Zaj-PROJECT.md` | Every current-truth change: repo, toolchain, DB names, SSH aliases, deploy paths, server/runtime versions |
| `Zaj-PROGRESS.md` | During active phase/step work and after each verified gate |
| `Zaj-BACKLOG.md` | Deferred work, phase-entry blockers, human-only follow-ups, and future work |
| `Zaj-CHANGELOG.md` | Each phase completion and release-worthy internal change |
| `Zaj-CUSTOMIZATIONS.md` | Any vendor/config deviation or operational decision that affects future upgrades |
| `Admin-Local/1-Project/90-DevLog/Decisions/` | Material "why" decisions that need an audit trail |
| `Admin-Local/1-Project/4-Audit-Reports/` | Security, compliance, audit, and QA evidence |
| `CLAUDE.md` / `AGENTS.md` | AI rules, vendor doc extracts, tooling changes |

Before any customization in this or later phases, know **which mechanism** to use — this is what prevents "modified vendor file" sprawl that blocks future updates:

| Mechanism | Use when | Lives in |
|---|---|---|
| **Vendor Customizations** | Patching an *existing* vendor file | `resources/vendor-customizations/` |
| **ZajModules** | Adding *new* functionality (route, view, service) | `packages/ZajModules/{Type}/{Cat}/{Name}/` |
| **`_zaj` migrations** | Extending a vendor *table schema* | `database/migrations/*_zaj.php` |

The decision is three questions: editing an existing vendor file → Vendor Customization; adding something new → ZajModule; adding columns to a vendor table → `_zaj` migration.

### 4. Adopt version management — SemVer + Zaj-CHANGELOG (if adopted)

If you'll ship updates (almost everyone), adopt semantic versioning and a `Zaj-CHANGELOG.md` now so your versions stay distinct from the vendor's `author-vX.X.X` line. `vMAJOR.MINOR.PATCH` — bump by the nature of the change:

| Change | Bump | Example |
|---|---|---|
| Bug fix / security patch | PATCH (`1.0.0 → 1.0.1`) | Fixed login error |
| New feature, backward compatible | MINOR (`1.0.0 → 1.1.0`) | Added export |
| Breaking change | MAJOR (`1.0.0 → 2.0.0`) | Changed API responses |

**Git tags:**

| Type | Command | Use for |
| --- | --- | --- |
| Annotated (recommended) | `git tag -a v1.0.0 -m "First stable release"` | Production releases |
| Lightweight | `git tag v1.0.0` | Quick local markers only |

**Release workflow:**

1. **Develop work** — `develop` branch; `Zaj-CHANGELOG.md` `[Unreleased]` section grows.
2. **Prepare release** — promote to staging, test, bump version in `composer.json` / `package.json`.
3. **Release** — deploy production, create annotated tag `vX.Y.Z`.
4. **Sync branches** — mirror production to `main` when your pipeline uses it.

**Decision journal** — the current version fields live in `Zaj-PROJECT.md`; the release history lives in `Zaj-CHANGELOG.md`; material "why" decisions live in `90-DevLog/Decisions/`. If this project needs an audit trail for the version-management choice, add one decision note there:

```bash
mkdir -p Admin-Local/1-Project/90-DevLog/Decisions
DECISION="Admin-Local/1-Project/90-DevLog/Decisions/001-decision-version-management.md"
if [ ! -f "$DECISION" ]; then
  cat > "$DECISION" <<'EOF'
# Decision 001 — Version management

Date: <YYYY-MM-DD>
Decision: Use project SemVer with root Zaj-CHANGELOG.md and internal Vendor base markers.
Rationale: Keep our release line separate from the CodeCanyon author snapshot line.
Evidence: composer.json/package.json version fields, author-vX.X.X tag, Zaj-CHANGELOG.md.
EOF
fi
# Expected: optional decision note lives under 90-DevLog/Decisions/; no separate 1-Info work-log file is created
```

Keep changelogs in [Keep a Changelog](https://keepachangelog.com) form (Added / Changed / Deprecated / Removed / Fixed / Security), and align package metadata: set `composer.json` and `package.json` `name`/`version`/`description`, change `license` to `proprietary`, and keep `package.json` `private: true`.

```bash
echo "composer.json:" && grep '"version"' composer.json | head -1
echo "package.json:" && grep '"version"' package.json | head -1
# Expected: both show "1.0.0" (your project line, not the vendor's author tag)
```

#### Two changelogs: INTERNAL (vendor-aware) vs PUBLIC (sanitized)

A public-facing CHANGELOG or release-notes page **must never name the CodeCanyon vendor** — not "WorkDo", "CodeCanyon", "Envato", the vendor product name, nor an `author-vX` tag. That's both a product-naming rule (customers see *your* brand, not the underlying script) and basic operational hygiene. So keep **two** documents:

| Document | Audience | May mention vendor? | Records |
|---|---|---|---|
| **`Zaj-CHANGELOG.md`** (internal) | You + your team | ✅ Yes — that's the point | Project SemVer **+** vendor base per release (e.g. `Vendor base: <Vendor> v7.6`), vendor upgrades logged as `### Changed` |
| **`docs/public-changelog.md`** (or release-notes page) | Customers / public | ❌ **Never** | Project name + your own SemVer + user-facing changes only |

Two version lines stay distinct in BOTH:

- **Project version** (`v1.0.0`, `v1.1.0`, …) — your own SemVer, tagged `vX.Y.Z`. First release is `v1.0.0` even if the vendor is at v7.6.
- **Vendor (author) version** (`author-v7.6`, …) — the CodeCanyon base, tracked by `author-vX.X.X` git tags. **Internal only** — never in the public document.

Each release records, **internally**, the vendor base it was built on so any project release is traceable to the exact CodeCanyon version underneath it. The public document carries only the project SemVer and the user-facing change.

**Internal `Zaj-CHANGELOG.md` (vendor base recorded):**

```markdown
## [Unreleased]

> **Vendor base:** <Vendor> v7.6 (`author-v7.6`)

### Added
- Subscription export.

### Changed
- Upgraded vendor base v7.6 → v7.8.
```

**Public `docs/public-changelog.md` (same release, sanitized):**

```markdown
## v1.1.0 — <YYYY-MM-DD>

### Added
- Export your subscriptions to CSV.

### Changed
- Performance and reliability improvements.
```

**Scrub gate — the public document must not leak the vendor.** Run this before publishing any public release notes; it must print `✅ clean`:

```bash
PUBLIC=docs/public-changelog.md
if grep -iE 'workdo|codecanyon|envato|author-v|dash[- ]?saas' "$PUBLIC" >/dev/null 2>&1; then
  echo "❌ vendor reference leaked into $PUBLIC — sanitize before publishing:"
  grep -inE 'workdo|codecanyon|envato|author-v|dash[- ]?saas' "$PUBLIC"
else
  echo "✅ clean — no vendor references in $PUBLIC"
fi
# Expected: ✅ clean — add YOUR vendor's product name to the pattern too
```

Replace `dash[- ]?saas` with your own vendor's product name(s) so the grep catches the specific script you're built on, not just the generic terms.

:::caution[Public release notes never name the vendor]
"Upgraded vendor base v7.6 → v7.8" belongs in the **internal** `Zaj-CHANGELOG.md` only. The public note for the same release says "Performance and reliability improvements" — the customer never learns which CodeCanyon script powers the product. Treat the scrub gate above as a hard gate on the public document.
:::

:::note[Your first release is v1.0.0 — even if the vendor is v7.6]
The `author-vX.X.X` tag tracks the *vendor's* version. *Your* project's first public release is always `v1.0.0`, created later (release finalization), not here. Annotated tags (`git tag -a v1.0.0 -m "…"`) are recommended for releases.
:::

## Checklist

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

- [ ] **👤 Topics surfaced** — each recommended topic was presented and the operator's choice recorded.
- [ ] **🤖 Scaffold (if adopted)** — `Admin-Local/` + gitignored vault exist; per-project templates seeded in `Admin-Local/1-Project/3-Templates/`; `4-Audit-Reports/` and `6-Schema/` exist; `5-Scripts/README.md` exists without pre-created script folders; `90-DevLog/` exists with README, STATUS, lanes, and prompt JSONL ignored by default.
- [ ] **🔀 Standards (if adopted)** — commit format + Zaj customization strategy understood.
- [ ] **🔀 Versioning (if adopted)** — internal `Zaj-CHANGELOG.md` (records vendor base) started, package metadata set, and the public-changelog **scrub gate prints `✅ clean`** before any public release notes ship.

:::next[Next step]
[Phase 3 · Local development](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/)
:::

# 7 · Project standards (recommended)

> Source: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/02-code-repo/07-project-standards/

## TL;DR

**Objective** — surface three **SHOULD-not-skip** topics (project structure, commit + doc standards with the Zaj customization strategy, and SemVer + Zaj-CHANGELOG version management) and capture the operator's decision on each — never silently drop them.

**Steps at a glance:**
1. **Decide which topics to adopt** — Present all three to the operator and record each choice in the project
   log before scaffolding anything.
2. **Scaffold the project structure** — A consistent `Admin-Local/` layout gives every later phase a known home
   for credentials, docs, version snapshots, schema baselines, and the `90-DevLog` build journal.
3. **Adopt commit & documentation standards** — Consistent commit hygiene prevents secrets leaking and makes
   history searchable. Never commit (already in `.gitignore`): `.env` / `.env.*` (except `.env.example`),
   `vendor/`, `node_modules/`, IDE settings.
4. **Adopt version management — SemVer + Zaj-CHANGELOG** — If you'll ship updates (almost everyone), adopt
   semantic versioning and a `Zaj-CHANGELOG.md` now so your versions stay distinct from the vendor's
   `author-vX.X.X` line.

:::note[User part + done-when]
**👤 User part** — these are **decisions**: the operator chooses which to adopt and records the call. The agent must present all three, never assume yes or no, and scaffold only what's chosen.

**Done when** each topic was surfaced and its decision recorded — and, for anything adopted, the scaffold / standards / `Zaj-CHANGELOG.md` actually exist. &nbsp;·&nbsp; **⏱ ~20–40 min if adopted** &nbsp;·&nbsp; 🔀 (👤 decisions, 🤖 scaffolding).
:::

## Background

These three topics are **SHOULD**, not skip-by-default. The agent must **surface** them and capture the operator's decision — never silently drop them.

| Topic | What it gives you | Adopt when |
|---|---|---|
| Project structure | A predictable `Admin-Local/` home for the vault, docs, and versions | You want the full scaffold from day one (recommended) |
| Commit & doc standards | Searchable history + an auditable vendor seam | Team work, or you want disciplined history |
| Version management | SemVer + `Zaj-CHANGELOG.md` distinct from the vendor's line | You'll ship updates over time (almost everyone) |

## Steps

### 1. Decide which topics to adopt

Present all three to the operator and record each choice in `Zaj-PROJECT.md` before scaffolding anything.

:::note[Who does this]
👤 **User** (the operator) decides adopt-or-not for each topic — this is a workflow preference, so the agent surfaces and records rather than assuming.
:::

<Steps>

1. **Surface the three topics and record the decisions.**

   - ✅ Each of the three topics was presented, and its adopt/skip decision is written in `Zaj-PROJECT.md`.

</Steps>

### 2. Scaffold the project structure (if adopted)

A consistent `Admin-Local/` layout gives every later phase a known home for credentials, docs, and version snapshots.

:::note[Where templates live — per-project, not a host-side pack]
Per-project templates live at **`Admin-Local/1-Project/3-Templates/`** (created by the scaffold step below). This page does **not** depend on any host-side `Guides-v2/Templates/` pack — that path is legacy and is **not** guaranteed to exist in a per-project tree. Everything this step needs is either inlined below or seeded into `3-Templates/` here.

```bash
TPL=Admin-Local/1-Project/3-Templates
if [ -d "$TPL" ]; then
  echo "✅ Per-project templates at $TPL/ ($(find "$TPL" -type f | wc -l | tr -d ' ') files)"
else
  echo "ℹ️  $TPL/ not created yet — the scaffold step below creates it"
fi
# Expected: the scaffold step (next) creates $TPL/ and seeds it
```

If you have your org's handbook pack available, you **may** copy its `_Docs` templates into `3-Templates/` instead of the inline stubs below — but the playbook never requires it. Never create empty stand-ins for deploy or env templates; if a real template is missing, use the minimal inline version here.
:::

<Steps>

1. **Create the `Admin-Local/` scaffold**.

   ```bash
   mkdir -p Admin-Local/{0-SuperAdmin,1-Project,2-Docs,3-Versions,4-Backups,5-Archive}
   mkdir -p Admin-Local/1-Project/{1-Info,2-Vault,3-Templates,4-Audit-Reports,5-Scripts,6-Schema,90-DevLog}
   mkdir -p Admin-Local/1-Project/90-DevLog/{Plans,Sessions,Decisions,Prompts,Handoffs,_Archive}
   mkdir -p Admin-Local/3-Versions/1-v${VERSION}/{1-Originals,2-Modifications}
   # Expected: the Admin-Local tree is created
   ```

   - ✅ Phases 3–12 now have a known home for credentials, docs, audit reports, replay-script records, schema baselines, the build journal, and versions.

2. **Lock the vault** so credentials can never be committed.

   ```bash
   printf '*\n!.gitignore\n!README.md\n' > Admin-Local/1-Project/2-Vault/.gitignore
   # Expected: the vault ignores everything except its .gitignore + README
   ```

   - ✅ `Admin-Local/1-Project/2-Vault/.gitignore` ignores all but itself + README.

3. **Create the replay-script index only.** Do not pre-create empty payment/email/content folders. Scripts are generated later from the guide step + rules + boilerplate, so the project starts with only the taxonomy and provider inventory matrix.

   ```bash
   cat > Admin-Local/1-Project/5-Scripts/README.md <<'EOF'
   # 5-Scripts — <PROJECT>

   Persist replay scripts here when a setup, operations, migration, or growth step needs repeatable writes to the vendor database or a third-party API.

   ## Taxonomy

   - `1-Setup/` — initial configuration during Phases 6-8.
   - `2-Operations/` — future re-syncs, cleanups, and health checks.
   - `3-Migrations/` — future data migrations and vendor-update data fixes.
   - `4-Growth/` — future promos, new tiers, and experiments.
   - `archive/` — retired scripts moved for audit, never deleted.

   ## Provider inventory

   | Function | Provider/service | Status | Script path | Notes |
   |---|---|---|---|---|
   | Payments | Stripe | 🟡 placeholder |  | Use if this app has Stripe billing. |
   | Payments | PayPal | ⬜ not used |  |  |
   | Email | SMTP | 🟡 placeholder |  |  |
   | Email | SendGrid | ⬜ not used |  |  |
   | Content | DemoContentCleanup | 🟡 placeholder |  | Use only if demo rows need scripted cleanup. |
   | Auth | Roles | 🟡 placeholder |  |  |
   | Branding | Assets | 🟡 placeholder |  |  |
   | Database | SchemaInspection | 🟡 placeholder |  |  |

   Status: `✅ configured` = script exists, `🟡 placeholder` = expected but no script yet, `⬜ not used` = intentionally out of scope.
   EOF
   # Expected: only 5-Scripts/README.md exists; lane/function/provider folders are lazy-created later
   ```

   - ✅ `Admin-Local/1-Project/5-Scripts/README.md` records the taxonomy and provider inventory without empty script folders.

4. **Seed the build journal.** `90-DevLog/` is the working journal for plans, session logs, decisions, prompt capture, and handoffs. It is a high-band meta lane: `1-9` lanes hold project content; `90-99` lanes hold process/meta artifacts that should sort last.

   ```bash
   DEVLOG=Admin-Local/1-Project/90-DevLog
   mkdir -p "$DEVLOG"/{Plans,Sessions,Decisions,Prompts,Handoffs,_Archive}
   touch "$DEVLOG"/{Plans,Sessions,Decisions,Handoffs,_Archive}/.gitkeep
   printf '# keep\n' > "$DEVLOG/Prompts/.gitkeep"
   cat > "$DEVLOG/Prompts/.gitignore" <<'EOF'
   *.jsonl
   distilled/
   !.gitignore
   !.gitkeep
   !README.md
   EOF
   cat > "$DEVLOG/README.md" <<'EOF'
   # 90-DevLog — the build journal

   Single home for dev-process artifacts: plans, session logs, decisions, prompts, and handoffs.
   Numbered `90-` as a reserved high band so it sorts last and never forces a renumber of the
   `1-9` content lanes (`1-Info`, `2-Vault`, `5-Scripts`, `6-Schema`, etc.).

   Boundary: root `Zaj-*` files are the canonical record of what shipped. `90-DevLog/` is the
   working journal for how the work happened.

   ## Lanes

   | Path | Holds | Naming |
   |---|---|---|
   | `STATUS.md` | Active plan, in-flight agents, hot-file locks, blockers | fixed name |
   | `Plans/` | Phase or feature plans | `NNN-type-slug.md` |
   | `Sessions/` | Per-session logs | `YYYY-MM-DD-HHMM-agent-slug.md` |
   | `Decisions/` | ADR-lite decisions | `NNN-type-slug.md` |
   | `Prompts/` | Local prompt JSONL from `UserPromptSubmit` | `YYYY-Www.jsonl` |
   | `Handoffs/` | Agent-switch handoffs | `YYYY-MM-DD-HHMM-from-to.md` |
   | `_Archive/` | Completed/stale journal artifacts | mirror source name |

   ## Rules

   - `1-9` = project content lanes; `90-99` = sorts-last/meta lanes.
   - Plans and Decisions use monotonic IDs; never reset, reuse, or reorder them.
   - Sessions, Handoffs, and Prompts use timestamps so parallel agents do not race a shared counter.
   - Agent identity belongs in frontmatter and slug, never as the sort key.
   - `STATUS.md` is the coordination surface; claim hot files before editing.
   EOF
   cat > "$DEVLOG/STATUS.md" <<'EOF'
   # DevLog STATUS — <PROJECT>

   Last updated: <YYYY-MM-DD> (<AGENT>)

   ## Where we are
   - Current phase: Phase 2 — Code & repository setup

   ## Active plan
   - None yet.

   ## In-flight agents
   | Agent | Working on | Hot files claimed |
   |---|---|---|
   | <agent> | <task> | `<path>` |

   > Hot-file locks: one agent per hot file. Do not edit, move, overwrite, or archive another live agent's claimed file without coordinating first.

   ## Blockers
   - None.
   EOF
   # Expected: 90-DevLog has README, STATUS, lanes, and prompt JSONL is ignored by default
   ```

   - ✅ `Admin-Local/1-Project/90-DevLog/` exists with `README.md`, `STATUS.md`, lane stubs, and local prompt JSONL ignored by default.

5. **Seed the per-project templates** into `3-Templates/`. These are minimal, self-contained, and require no external pack. (If your org's handbook `_Docs` pack is available, you may copy its richer versions over these instead.)

   ```bash
   TPL=Admin-Local/1-Project/3-Templates

   # Zaj-PROJECT template — current truth for non-secret project facts
   cat > "$TPL/T01-Zaj-PROJECT.md" <<'EOF'
   # Zaj-PROJECT — <PROJECT>

   Last updated: <YYYY-MM-DD>
   Current phase: Phase 2 — Code & repository setup

   > Non-secret project bible. Current truth for project identity, toolchain versions, paths, environments, SSH aliases, and tracker links.
   > Boundary: this file records current facts; `Zaj-CUSTOMIZATIONS.md` records vendor deviations and why they exist.

   ## Project Identity

   | Field | Value |
   |---|---|
   | Project name | <PROJECT> |
   | CodeCanyon item | <url> |
   | Vendor / author | <vendor> |
   | Vendor version | <author-vX.Y.Z> |
   | Product type | <SaaS / marketplace / directory / other> |

   ## Repository And Branch Model

   | Field | Value |
   |---|---|
   | Repo URL | <git@host:org/repo.git> |
   | Default branch | develop |
   | Release branch | main |

   ## Environment Matrix

   Use one row per real environment. `staging-primary` is only the common example; use the actual keys this project has, such as `qa`, `uat`, `client-demo`, `sandbox`, or multiple staging rows.

   | Env key | Role | URL / domain | Hosting account | SSH alias | Host | User | Port | Deploy target | Source branch | Web PHP | CLI PHP binary | DB name | Noindex / robots | Credential pointer | Last verified |
   |---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
   | local | Local dev | https://<project>.test | N/A | N/A | 127.0.0.1 | <local user> | N/A | local | develop | Herd <x.y> | <path> | <project>_local | N/A | op://<vault>/Local | <date> |
   | staging-primary | Non-production | https://nonprod.example.com | <account/order> | <alias> | <host/IP> | <user> | <port> | staging | staging | <pending Phase 4> | <pending Phase 4> | <project>_staging | noindex + Disallow | op://<vault>/Staging | <date> |
   | production | Production | https://<domain> | <account/order> | <alias> | <host/IP> | <user> | <port> | production | main | <pending Phase 12> | <pending Phase 4> | <project>_production | index allowed | op://<vault>/Production | <date> |

   ## Toolchain Parity

   | Surface | Local | Non-production target(s) | Production | Target / rule |
   |---|---|---|---|---|
   | PHP | <x.y.z> | <pending> | <pending> | strictest root `composer.json` + production package requirement in `composer.lock` |
   | Composer | <2.x> | <pending> | <pending> | same major/minor where practical |
   | Node | <x.y.z> | build-local only | build-local only | `.tool-versions` / package lock |
   | DB engine | <MySQL/MariaDB x.y> | <x.y> | <x.y> | same engine family when possible |
   | DB charset/collation | utf8mb4 / utf8mb4_unicode_ci | utf8mb4 / utf8mb4_unicode_ci | utf8mb4 / utf8mb4_unicode_ci | must match before deploy |

   ## Canonical Paths

   | Purpose | Path |
   |---|---|
   | Project profile | `Zaj-PROJECT.md` |
   | Progress tracker | `Zaj-PROGRESS.md` |
   | Deferred work | `Zaj-BACKLOG.md` |
   | Internal changelog | `Zaj-CHANGELOG.md` |
   | Vendor-deviation ledger | `Zaj-CUSTOMIZATIONS.md` |
   | Project info lane | `Admin-Local/1-Project/1-Info/` |
   | Research reports | `Admin-Local/1-Project/1-Info/Research/` |
   | Build journal | `Admin-Local/1-Project/90-DevLog/` |
   | Playbook feedback | `Admin-Local/1-Project/playbook-feedback.md` |

   ## 1Password Pointers

   | Item | Pointer | Expected fields |
   |---|---|---|
   | Local credential item | `op://<vault>/Local` | `DB_CONNECTION`, `DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`, `APP_KEY`, `env_file` |
   | Staging credential item | `op://<vault>/Staging` | Same flat field set; use the real non-production item name if this row is `qa`, `uat`, `client-demo`, etc. |
   | Production credential item | `op://<vault>/Production` | Same flat field set; `DB_PASSWORD`, `APP_KEY`, and `env_file` are concealed. |
   EOF

   cat > "$TPL/tool-versions.template" <<'EOF'
   php <PHP_VERSION>
   nodejs <NODE_VERSION>
   composer <COMPOSER_VERSION>
   EOF

   # Expected: T01-Zaj-PROJECT.md + tool-versions.template exist in 3-Templates/
   ```

6. **Instantiate the project records** from those templates:

   ```bash
   TPL=Admin-Local/1-Project/3-Templates
   cp "$TPL/T01-Zaj-PROJECT.md" Zaj-PROJECT.md
   cp "$TPL/tool-versions.template" .tool-versions
   printf '# Project vault\n\nGitignored credentials and env templates.\n' \
     > Admin-Local/1-Project/2-Vault/README.md
   # Expected: Zaj-PROJECT.md + .tool-versions + vault README exist
   ```

   Fill **Zaj-PROJECT** from infrastructure created in [Prerequisites](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/02-code-repo/01-prerequisites/) — domains, IPs, SSH aliases, repo URL, DB names, current local PHP/Composer/Node, and placeholder deploy PHP rows that Phase 4 will confirm. Keep `.tool-versions` aligned with the chosen PHP / Node / Composer targets. (`Zaj-CHANGELOG.md` is created in §4 below — keep it out of this step so the public/internal split is set up correctly.)

   **AI agent wiring:** if Phase 1 did not already seed rules, drop Cursor/Gemini/AntiGravity rule files into the project's own AI config (e.g. `.cursor/rules/`, `GEMINI.md`) and ensure `.cursorignore` / `.geminiignore` exclude `vendor/`, `node_modules/`, and `Admin-Local/1-Project/2-Vault/`. Do **not** assume a host-side `Guides-v2/Templates/` pack — author them in-project or copy from your handbook if you have one.

   - ✅ `Zaj-PROJECT.md` exists with real domains, IPs, SSH aliases, repo URL, DB names, local toolchain facts, and the `90-DevLog` canonical path; `.tool-versions` exists; per-project templates are seeded in `3-Templates/`; vault README explains the gitignored area.

</Steps>

### 3. Adopt commit & documentation standards (if adopted)

Consistent commit hygiene prevents secrets leaking and makes history searchable. **Never commit** (already in `.gitignore`): `.env` / `.env.*` (except `.env.example`), `vendor/`, `node_modules/`, IDE settings. **Always commit**: `composer.json` + `composer.lock`, `package.json` + `package-lock.json`, `config/*.php`, `database/migrations/*.php`, project docs.

A conventional commit format keeps the log self-documenting — emoji + type tag + verb-thing + description:

| Type | Format | Example |
|---|---|---|
| Author import | `📦 ⬜ T1 Setup-Author: …` | `📦 ⬜ T1 Setup-Author: Import v10.4` |
| Setup/config | `🔧 🟦 T2 Setup-Config: …` | `🔧 🟦 T2 Setup-Config: Add GA tracking` |
| App feature | `🔨 🟪 T3 Add-Feature: …` | `🔨 🟪 T3 Add-Feature: Arabic support` |
| Deploy | `🚀 🟩 T4 Deploy-App: …` | `🚀 🟩 T4 Deploy-App: Deploy v1.5.1` |
| ServerSync | `🔄 ⬛ T5 ServerSync-Setup: …` | `🔄 ⬛ T5 ServerSync-Setup: Capture SMTP config` |

**Documentation update schedule** — refresh when the trigger fires, not "whenever you remember":

| File | Update when |
| --- | --- |
| `Zaj-PROJECT.md` | Every current-truth change: repo, toolchain, DB names, SSH aliases, deploy paths, server/runtime versions |
| `Zaj-PROGRESS.md` | During active phase/step work and after each verified gate |
| `Zaj-BACKLOG.md` | Deferred work, phase-entry blockers, human-only follow-ups, and future work |
| `Zaj-CHANGELOG.md` | Each phase completion and release-worthy internal change |
| `Zaj-CUSTOMIZATIONS.md` | Any vendor/config deviation or operational decision that affects future upgrades |
| `Admin-Local/1-Project/90-DevLog/Decisions/` | Material "why" decisions that need an audit trail |
| `Admin-Local/1-Project/4-Audit-Reports/` | Security, compliance, audit, and QA evidence |
| `CLAUDE.md` / `AGENTS.md` | AI rules, vendor doc extracts, tooling changes |

Before any customization in this or later phases, know **which mechanism** to use — this is what prevents "modified vendor file" sprawl that blocks future updates:

| Mechanism | Use when | Lives in |
|---|---|---|
| **Vendor Customizations** | Patching an *existing* vendor file | `resources/vendor-customizations/` |
| **ZajModules** | Adding *new* functionality (route, view, service) | `packages/ZajModules/{Type}/{Cat}/{Name}/` |
| **`_zaj` migrations** | Extending a vendor *table schema* | `database/migrations/*_zaj.php` |

The decision is three questions: editing an existing vendor file → Vendor Customization; adding something new → ZajModule; adding columns to a vendor table → `_zaj` migration.

### 4. Adopt version management — SemVer + Zaj-CHANGELOG (if adopted)

If you'll ship updates (almost everyone), adopt semantic versioning and a `Zaj-CHANGELOG.md` now so your versions stay distinct from the vendor's `author-vX.X.X` line. `vMAJOR.MINOR.PATCH` — bump by the nature of the change:

| Change | Bump | Example |
|---|---|---|
| Bug fix / security patch | PATCH (`1.0.0 → 1.0.1`) | Fixed login error |
| New feature, backward compatible | MINOR (`1.0.0 → 1.1.0`) | Added export |
| Breaking change | MAJOR (`1.0.0 → 2.0.0`) | Changed API responses |

**Git tags:**

| Type | Command | Use for |
| --- | --- | --- |
| Annotated (recommended) | `git tag -a v1.0.0 -m "First stable release"` | Production releases |
| Lightweight | `git tag v1.0.0` | Quick local markers only |

**Release workflow:**

1. **Develop work** — `develop` branch; `Zaj-CHANGELOG.md` `[Unreleased]` section grows.
2. **Prepare release** — promote to staging, test, bump version in `composer.json` / `package.json`.
3. **Release** — deploy production, create annotated tag `vX.Y.Z`.
4. **Sync branches** — mirror production to `main` when your pipeline uses it.

**Decision journal** — the current version fields live in `Zaj-PROJECT.md`; the release history lives in `Zaj-CHANGELOG.md`; material "why" decisions live in `90-DevLog/Decisions/`. If this project needs an audit trail for the version-management choice, add one decision note there:

```bash
mkdir -p Admin-Local/1-Project/90-DevLog/Decisions
DECISION="Admin-Local/1-Project/90-DevLog/Decisions/001-decision-version-management.md"
if [ ! -f "$DECISION" ]; then
  cat > "$DECISION" <<'EOF'
# Decision 001 — Version management

Date: <YYYY-MM-DD>
Decision: Use project SemVer with root Zaj-CHANGELOG.md and internal Vendor base markers.
Rationale: Keep our release line separate from the CodeCanyon author snapshot line.
Evidence: composer.json/package.json version fields, author-vX.X.X tag, Zaj-CHANGELOG.md.
EOF
fi
# Expected: optional decision note lives under 90-DevLog/Decisions/; no separate 1-Info work-log file is created
```

Keep changelogs in [Keep a Changelog](https://keepachangelog.com) form (Added / Changed / Deprecated / Removed / Fixed / Security), and align package metadata: set `composer.json` and `package.json` `name`/`version`/`description`, change `license` to `proprietary`, and keep `package.json` `private: true`.

```bash
echo "composer.json:" && grep '"version"' composer.json | head -1
echo "package.json:" && grep '"version"' package.json | head -1
# Expected: both show "1.0.0" (your project line, not the vendor's author tag)
```

#### Two changelogs: INTERNAL (vendor-aware) vs PUBLIC (sanitized)

A public-facing CHANGELOG or release-notes page **must never name the CodeCanyon vendor** — not "WorkDo", "CodeCanyon", "Envato", the vendor product name, nor an `author-vX` tag. That's both a product-naming rule (customers see *your* brand, not the underlying script) and basic operational hygiene. So keep **two** documents:

| Document | Audience | May mention vendor? | Records |
|---|---|---|---|
| **`Zaj-CHANGELOG.md`** (internal) | You + your team | ✅ Yes — that's the point | Project SemVer **+** vendor base per release (e.g. `Vendor base: <Vendor> v7.6`), vendor upgrades logged as `### Changed` |
| **`docs/public-changelog.md`** (or release-notes page) | Customers / public | ❌ **Never** | Project name + your own SemVer + user-facing changes only |

Two version lines stay distinct in BOTH:

- **Project version** (`v1.0.0`, `v1.1.0`, …) — your own SemVer, tagged `vX.Y.Z`. First release is `v1.0.0` even if the vendor is at v7.6.
- **Vendor (author) version** (`author-v7.6`, …) — the CodeCanyon base, tracked by `author-vX.X.X` git tags. **Internal only** — never in the public document.

Each release records, **internally**, the vendor base it was built on so any project release is traceable to the exact CodeCanyon version underneath it. The public document carries only the project SemVer and the user-facing change.

**Internal `Zaj-CHANGELOG.md` (vendor base recorded):**

```markdown
## [Unreleased]

> **Vendor base:** <Vendor> v7.6 (`author-v7.6`)

### Added
- Subscription export.

### Changed
- Upgraded vendor base v7.6 → v7.8.
```

**Public `docs/public-changelog.md` (same release, sanitized):**

```markdown
## v1.1.0 — <YYYY-MM-DD>

### Added
- Export your subscriptions to CSV.

### Changed
- Performance and reliability improvements.
```

**Scrub gate — the public document must not leak the vendor.** Run this before publishing any public release notes; it must print `✅ clean`:

```bash
PUBLIC=docs/public-changelog.md
if grep -iE 'workdo|codecanyon|envato|author-v|dash[- ]?saas' "$PUBLIC" >/dev/null 2>&1; then
  echo "❌ vendor reference leaked into $PUBLIC — sanitize before publishing:"
  grep -inE 'workdo|codecanyon|envato|author-v|dash[- ]?saas' "$PUBLIC"
else
  echo "✅ clean — no vendor references in $PUBLIC"
fi
# Expected: ✅ clean — add YOUR vendor's product name to the pattern too
```

Replace `dash[- ]?saas` with your own vendor's product name(s) so the grep catches the specific script you're built on, not just the generic terms.

:::caution[Public release notes never name the vendor]
"Upgraded vendor base v7.6 → v7.8" belongs in the **internal** `Zaj-CHANGELOG.md` only. The public note for the same release says "Performance and reliability improvements" — the customer never learns which CodeCanyon script powers the product. Treat the scrub gate above as a hard gate on the public document.
:::

:::note[Your first release is v1.0.0 — even if the vendor is v7.6]
The `author-vX.X.X` tag tracks the *vendor's* version. *Your* project's first public release is always `v1.0.0`, created later (release finalization), not here. Annotated tags (`git tag -a v1.0.0 -m "…"`) are recommended for releases.
:::

## Checklist

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

- [ ] **👤 Topics surfaced** — each recommended topic was presented and the operator's choice recorded.
- [ ] **🤖 Scaffold (if adopted)** — `Admin-Local/` + gitignored vault exist; per-project templates seeded in `Admin-Local/1-Project/3-Templates/`; `4-Audit-Reports/` and `6-Schema/` exist; `5-Scripts/README.md` exists without pre-created script folders; `90-DevLog/` exists with README, STATUS, lanes, and prompt JSONL ignored by default.
- [ ] **🔀 Standards (if adopted)** — commit format + Zaj customization strategy understood.
- [ ] **🔀 Versioning (if adopted)** — internal `Zaj-CHANGELOG.md` (records vendor base) started, package metadata set, and the public-changelog **scrub gate prints `✅ clean`** before any public release notes ship.

:::next[Next step]
[Phase 3 · Local development](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/)
:::