1 · Concepts & admin model

TL;DR

Objective — set the vocabulary and the two failure modes (wrong tier, wrong Livewire form) before touching a form, so every later page in this phase can assume them.

User part + done-when

👤 User part — none on this page: it’s a read. Internalize the two meanings of “admin”, the three ops tiers, the check-first pattern, and the Livewire pre-flight before configuring anything live.

Done when both meanings of “admin” are clear, the three ops tiers are nameable, and the Livewire 30-second pre-flight is understood.  ·  ⏱ ~15 min read  ·  🤖 agent-runnable (concept page).

Background

This phase configures the vendor’s existing admin panel — branding, payments, email, plans, legal pages — as the logged-in superadmin. You write almost no code; you inspect what the panel exposes and fill it in. Read this page once: it sets the vocabulary and the two failure modes (wrong tier, wrong Livewire form) that every later page assumes you’ve internalized.

Steps

1. Separate the two meanings of “admin”

The word admin refers to two different things in this playbook — different places, different lifecycles. Internalize which one this phase operates in before going further.

1. Distinguish the in-app superadmin from the ops admin tiers.

   • The in-app superadmin is the account you log into the running app with to set branding, payments, email, and pages. That is this phase. Its config persists into the app’s database and .env.

   • The ops admin tiers are the on-disk folders where project guides, secrets, deploy logs, and shared monitoring scripts live. They surround the app but are never edited from the panel.

   • ✅ You can state which sense each task in this phase operates in (the panel), and why the second sense still matters (the secrets you paste — SMTP, Stripe — and the deploy webhooks resolve through those tiers).

2. Learn the three-tier ops model

The ops side follows a three-tier model. You don’t change it in Phase 6 — but knowing which tier a path belongs to is what keeps “rotate a webhook” from meaning “edit N projects.”

flowchart TD
    subgraph LOCAL["Admin-Local · in git (vault gitignored)"]
        direction LR
        L1["Phase guides + ProjectCard"]
        L2["Project vault — secrets"]
        L3["Customizations registry"]
    end

    subgraph SERVER["Admin-Server · own repo · server-wide"]
        direction LR
        S1["server.env — shared webhooks"]
        S2["Monitoring + MD5 baselines"]
    end

    subgraph DOMAIN["Admin-Domain · never in git · per-domain runtime"]
        direction LR
        D1["Deploy history log"]
        D2["Per-domain backups + crons"]
    end

    LOCAL -->|"authoring → deploy"| DOMAIN
    SERVER -->|"shared config inherited by every domain"| DOMAIN

1. Map each path to its tier.

   Tier	Lives at	Scope	In git?
   Admin-Local	the project repo (Admin-Local/)	this one codebase	Yes — except the secrets vault (2-ProjectVault/)
   Admin-Domain	the server, per domain (~/domains/<domain>/Admin-Domain/)	one staging/prod domain	No — pure runtime state
   Admin-Server	the server, once per account (~/Admin-Server/)	every domain on the host	Yes — its own repo

   Mnemonic: Local → your laptop’s project folder. Domain → on the server, scoped to one domain. Server → on the server, scoped to the whole hosting account.

   • ✅ Given any ops path, you can name its tier without guessing.

Why this matters in Phase 6

Ops webhooks resolve cascading, highest priority first: a per-project shared/.env override wins, otherwise the server-wide Admin-Server/config/server.env is used, otherwise the task no-ops with a “skipped” log line (never blocks the deploy). Rotate a Discord/Slack webhook once at the server tier and every domain inherits it — you don’t re-paste it per project.

One naming detail trips up agents reading older guides — fix it on sight:

Naming convention

The prefix is always Admin- (Admin-Local, Admin-Domain, Admin-Server) — never the inverted Domain-Admin/. If you find Domain-Admin/ in older guides or server folders, it’s pre-2026-04 legacy; migrate it and leave a compat symlink until deploy.php and cron entries use the new name.

3. Adopt the check-first pattern

The admin panel differs per app, so don’t follow a fixed checklist — inspect, then configure what exists. Every task in this phase is the same shape: CHECK the panel → configure if present → defer to a later phase’s full guide if absent. Never assume a label.

flowchart TD
    Start["Generic task<br/>(e.g. 'configure SMTP')"] --> Check{"Does the panel<br/>expose it?"}
    Check -->|Yes| Conf["Configure in-panel now<br/>(≈5-min task)"]
    Check -->|No| Defer["Defer to the linked<br/>full guide (later phase)"]
    Conf --> Verify["Verify it persisted<br/>(hard reload / curl)"]
    Defer --> Log["Log the decision<br/>in _CUSTOMIZATIONS.md"]
    Verify --> Log

1. Map the panel read-only first. Log in and walk every nav item, settings tab, and profile menu without changing anything. Record the structure (URL + label of each setting) in _CUSTOMIZATIONS.md. This map makes a later re-run — e.g. on a fresh production DB — dramatically faster.

   • ✅ _CUSTOMIZATIONS.md holds a URL + label for each setting, with nothing changed.

2. For each task: CHECK → configure or defer. If the app exposes the setting, configure it now. If it doesn’t, defer to the linked full guide in a later phase.

   • ✅ Each task is resolved as configured-now or deferred-with-link, never silently skipped.

3. Capture capabilities once. A single up-front survey (the next page) of what’s admin-editable vs hardcoded, which modules ship, and which features are tier-gated keeps every later step from deciding in ignorance.

   • ✅ The survey from the next page is treated as the input to every later “CHECK”.

Where this phase runs — and when you redo it

Run this phase on staging first. If you later deploy production with a fresh database (not a copy of staging), the panel config doesn’t travel — you repeat this phase on production (Phase 12). The panel map and capabilities survey you save here make the second pass quick.

4. Plan an AI-assisted inspection pass (Playwright)

If the Playwright MCP is available, the agent can inspect the panel automatically instead of you browsing manually. The map is the input to every later “CHECK” — it converts “where is this setting?” from manual hunting into automated discovery.

1. Run a read-only mapping pass first. Have the agent log in, then walk every sidebar item, settings tab, and profile menu — taking snapshots and extracting the URL + label of each. No configuration changes during this pass.

   • ✅ A snapshot + URL + label is captured for every nav surface, with nothing changed.

2. Summarize the structure. Sidebar items, settings tabs, profile menu, and any dashboard-level nags (an “SMTP not configured” banner is a validation signal that the email page needs work).

   • ✅ The summary names every settings tab and any dashboard nag.

3. Save the map to _CUSTOMIZATIONS.md as an “Admin panel structure” section, and screenshot the key config pages.

   • ✅ The map and screenshots are persisted to _CUSTOMIZATIONS.md.

4. Propose an ordered plan from what’s actually present — skip tasks for features the app lacks, promote any dashboard nags to the top.

   • ✅ The plan reflects only present features, with nags promoted.

This is optional — every task can be done by browsing manually. But on a typical Froiden/WorkDo/SocietyPro-style app, a 5-minute map pass saves ~30 minutes of back-and-forth later.

5. Read the Livewire component before you click “Save”

CodeCanyon admin pages often host 3–6 independent Livewire forms on a single page (a Disable-Landing toggle, an FAQ editor, a Contact form, a Footer editor, an SEO editor). Driving them blindly — by Playwright or by hand — is the single most common Phase 6 time-sink. Three traps stack:

Trap	What goes wrong
Multiple forms per page	A generic wire:target="submitForm" button hits whichever form matches the selector — not the one whose fields you just filled.
Non-convention method names	Vendors use saveContact, updateBranding, uploadLogo instead of submitForm/save. Grepping for submitForm misses them all.
Scoped records	Records filtered by language_setting_id, society_id/tenant_id, user_id, or guard. Save without the scope value and Livewire writes an orphan row or updates a different record than the one on screen.

The 30-second pre-flight below — run it BEFORE every form interaction — spends 30 seconds reading the component source to prevent a 15-minute “why didn’t the save work?” loop.

1. Find the Livewire component(s) the page renders.

   grep -rn "Livewire::" resources/views/ --include="*.blade.php" 2>/dev/null \
     | grep -iE "landing|contact|setting|branding|payment" | head -10
   # Expected: the blade lines that mount the page's Livewire components

   • ✅ You have the component name(s) the page mounts.

2. Find every submit method (not just submitForm).

   grep -rnE "public function (save|submit|update|store|upload)[A-Za-z]*\s*\(" \
     app/Livewire/ --include="*.php" 2>/dev/null | head -20
   # Expected: the real save-method names (e.g. saveContact, updateBranding)

   • ✅ The actual save method for your page is identified — not assumed to be submitForm.

3. Read the component class for YOUR page, noting the save method, the $rules (conditional validation), the scope fields, and mount(). Then find the table it writes to.

   grep -n "protected \$table\|Model::" app/Models/[ModelName].php 2>/dev/null
   # Expected: the $table name (or Model:: usage) the component persists to

   • ✅ Save method, conditional rules, scope fields, and target table are all known before any save.

Real bug — one form, all three traps

Configuring a landing “Contact Us” section via Playwright, an agent clicked a submitForm button after filling company name/email/address. A hard reload showed the fields reverted to the vendor’s seed data. The component source revealed: the save method was saveContact() (not submitForm), the clicked button belonged to a different form on the same page, saveContact() validates contactImage as required unless an image already exists, and records are scoped by language_setting_id — so the agent was editing the wrong language’s record. The fix: target wire:click="saveContact", pass the right language_setting_id, and satisfy the conditional image rule.

Rule of thumb: when a Playwright save doesn’t persist, don’t troubleshoot Livewire sync or caching first — grep the component source. 80% of the time the bug is the guide’s assumption about method name, form identity, or scope, not Livewire itself.

Checklist

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

• 🤖 Two meanings clear — both senses of “admin” are clear; the three ops tiers are understood (you can name which tier a path belongs to).
• 🤖 Check-first internalized — CHECK → configure-or-defer → verify → log.
• 🤖 Map pass planned — if using Playwright, a read-only map pass is planned before any change.
• 🤖 Livewire pre-flight understood — the 30-second component check is understood before touching any form.

→Next step

2 · Survey & brand profile