6 · Integrations

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: 6 · Integrations
- url: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/08-configure-app/06-integrations/
- shelf: Build & Create
- doc_type: implementation playbook
- status: current
- kind: playbook
- category: tech-stack
- subcategory: laravel
- topic: codecanyon
- phase: 8
- part_number: 6 (legacy stepNumber frontmatter)
- legacy_step_number: 6
- est_time: ~2–3 hr (all three)
- description: Surface the integration choices — Slack notifications for errors/deploys/backups, GitHub project management (labels, issue forms, project board, PR template), and privacy-first Rybbit analytics.
- tags: codecanyon, laravel, slack, analytics, project-management

## Execution rules (binding)
- This is Part 6 of phase 8 (~2–3 hr (all three)) — 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.

---

# 6 · Integrations

## TL;DR

**Objective** — surface the integration choices — Slack notifications for errors/deploys/backups, GitHub project management (labels, issue forms, project board, PR template), and privacy-first Rybbit analytics — so operations and feedback loops are wired before users arrive.

**Steps at a glance:**
1. **Wire Slack notifications** — Automated Slack alerts for Sentry errors, deployments, and backup status.
2. **Set up project management** — Set up GitHub Issues, typed labels, YAML issue forms, a project board, and a
   PR template.
3. **Set up Rybbit analytics** — Privacy-first, cookieless analytics — session replay, funnels, goals, web
   vitals, and error tracking with no consent banner.

:::note[User part + done-when]
**🔀 User part** — humans own account creation, paid/provider authorization, OAuth/login, and secret copy. With an authorized browser/API session, the agent drives non-secret provider-console work: Slack channel/webhook setup, GitHub labels/forms/project wiring, Rybbit site configuration, Deployer tasks, env placeholders, and analytics script wiring.

**Done when** the Slack webhook posts to its channel and Deployer notifies on deploy, GitHub labels/forms/board/PR-template are in place, and Rybbit records hits in real time with admin paths skipped — or each skipped item has a `Zaj-BACKLOG.md` row with owner, trigger, and acceptance criterion. &nbsp;·&nbsp; **⏱ ~2–3 hr** &nbsp;·&nbsp; 🔀 mixed (👤 dashboards, 🤖 code/config wiring).
:::

## Background

These are valuable integrations, not mystery work to silently skip. Treat each row as **adopt or evidence-backed N/A**: configure it now when `Zaj-PROJECT.md` shows the account/tool is adopted or the setup is free and routine; mark N/A only when the project has no license, no account, no token scope, or an explicit operator decision not to adopt it. Every N/A or blocked integration gets a `Zaj-BACKLOG.md` row with owner, trigger, and acceptance criterion.

```mermaid
flowchart LR
  Sentry["Sentry errors"] --> Alerts["#app-alerts"]
  Deployer["Deployer"] --> Deploys["#app-deploys"]
  Backup["Backups"] --> Backups["#app-backups"]
  Alerts --> Slack(["Slack workspace"])
  Deploys --> Slack
  Backups --> Slack
```

## Steps

### 1. Wire Slack notifications

Automated Slack alerts for Sentry errors, deployments, and backup status.

:::note[Who does this]
🔀 **User + Agent** — 👤 **User** creates or authorizes the Slack workspace/app session and owns the webhook URL as a secret. 🤖 **Agent** drives non-secret channel/webhook navigation when browser automation is available, stores only the 1Password pointer in docs/config, wires the Deployer tasks and env vars, and runs the test `curl`.
:::

<Steps>

1. **Set up the workspace** (first project only). If you don't have a workspace, create one at [slack.com/create](https://slack.com/create). Create an incoming-webhook app: [api.slack.com/apps](https://api.slack.com/apps) → **Create New App → From scratch** → name `<Org> Notifications` → **Incoming Webhooks → Activate ON** → **Add New Webhook to Workspace** → pick a channel → copy the URL into 1Password. Store the webhook URL, workspace, app name, and creation date in your password manager; never paste the live URL into docs, commits, screenshots, or chat.

   :::note[Account-wide infra creds → shared vault, not the project vault]
   A Slack **workspace** (and its app/webhooks) typically spans **every** project on that account — the same is true for analytics, hosting, and DNS account tokens. Storing them per-project duplicates the secret and the rotation point. Use a **two-vault** layout: a per-project vault for app secrets (`APP_KEY`, DB creds, gateway keys) and a shared infra vault for account-wide infra (`op://<SharedInfraVault>/<account>/<key>`). `General-Dev` is the default example name; record the actual vault in `Zaj-PROJECT.md`. If you use a 1Password service account for agents, grant it **both** vaults — otherwise the agent can read the project secrets but not the shared infra creds it needs.
   :::

   - ✅ The workspace + incoming-webhook app exist, URL stored in the shared infra vault for this account-wide credential.

2. **Create the project channels & webhooks** — one channel per concern, then a channel-specific webhook for each.

   | Channel | Purpose |
   |---|---|
   | `#<app>-alerts` | Sentry errors and critical alerts |
   | `#<app>-deploys` | Deployment notifications |
   | `#<app>-backups` | Backup success/failure (optional) |

	   Add deploy webhook URLs to `~/Admin-Server/config/server.env` by default. Use project `shared/.env` only when this one app needs its own override:

   ```bash
	   ## === SLACK NOTIFICATIONS ===
	   SLACK_ALERTS_WEBHOOK=<your-slack-alerts-webhook-url>
	   SLACK_WEBHOOK_DEPLOYS=<your-slack-deploys-webhook-url>
	   SLACK_BACKUPS_WEBHOOK=<your-slack-backups-webhook-url>
	   # Expected: real deploy webhook in server.env; project override only when needed
   ```

	   - ✅ Per-concern channels exist with webhook URLs wired into `server.env` or a deliberate project override.

3. **Wire the integrations.**
   - **Sentry → Slack** (requires Sentry Team plan) — Settings → Integrations → Slack → authorize, then Alerts → Create Alert Rule (`> 0 errors in 1 min`, filter `production`, action: send to `#<app>-alerts`). On the free plan, capture the paid-plan trigger and acceptance criterion in `Zaj-BACKLOG.md`.
   - **Deployer → Slack** — add success/failure tasks to `deploy.php`:

     ```php
     use Deployer\Utility\Httpie;

     task('slack:notify:success', function () {
	        $webhookUrl = getenv('SLACK_WEBHOOK_DEPLOYS');
	        if (!$webhookUrl) { writeln('<comment>SLACK_WEBHOOK_DEPLOYS not set - skipping</comment>'); return; }
         $app = get('application', 'App');
         $stage = get('labels')['stage'] ?? 'unknown';
         $branch = run('git rev-parse --abbrev-ref HEAD', ['timeout' => 5])->toString();
         $commit = run('git log -1 --oneline', ['timeout' => 5])->toString();
         Httpie::post($webhookUrl)->body([
             'text' => "*{$app}* deployed to *{$stage}*\nBranch: `{$branch}`\nCommit: {$commit}",
             'username' => 'Deployer', 'icon_emoji' => ':rocket:',
         ])->send();
     })->desc('Send deploy success notification to Slack');

     task('slack:notify:failure', function () {
	        $webhookUrl = getenv('SLACK_WEBHOOK_DEPLOYS');
         if (!$webhookUrl) { return; }
         $app = get('application', 'App');
         $stage = get('labels')['stage'] ?? 'unknown';
         Httpie::post($webhookUrl)->body([
             'text' => "*{$app}* deployment to *{$stage}* failed\nCheck logs for details.",
             'username' => 'Deployer', 'icon_emoji' => ':x:',
         ])->send();
     })->desc('Send deploy failure notification to Slack');

     after('deploy:success', 'slack:notify:success');
     after('deploy:failed', 'slack:notify:failure');
     ```

   - **Backups → Slack** — easiest is to rely on Sentry Cron Monitors (no extra config). Otherwise add a `slack` block to `config/backup.php`'s `notifications` with `'webhook_url' => env('SLACK_BACKUPS_WEBHOOK')`.

   - ✅ The Sentry, Deployer, and backup notification paths are wired, or each unavailable paid/provider path has a `Zaj-BACKLOG.md` row with owner, trigger, and acceptance criterion.

4. **Test the webhook.**

   ```bash
   set -a && source .env && set +a   # or export each SLACK_*_WEBHOOK you test
   curl -X POST -H 'Content-type: application/json' \
     --data '{"text":"Slack webhook test successful!"}' \
     "$SLACK_ALERTS_WEBHOOK"
   # Expected: "ok" and the message appears in the channel
   ```

   Then run `dep deploy "$DEPLOY_TARGET"` for the selected non-production target from `Zaj-PROJECT.md` and confirm the notification lands in `#<app>-deploys`. Record the production webhook `op://` pointers in the production env template/vault entry now; Phase 12 renders/uploads production `.env` and clears the production config cache during the production deploy.

   - ✅ The test `curl` returns `ok` and a real deploy notifies `#<app>-deploys`.

</Steps>

### 2. Set up project management

Set up GitHub Issues, typed labels, YAML issue forms, a project board, and a PR template.

:::note[Who does this]
🤖 **Agent by default** — use `gh`/GitHub API for labels, issue forms, PR template, and project-board setup when the token has scope. 👤 **User** is fallback only for GitHub UI authorization or token-scope gaps; record any unavailable paid/scope-gated setup in `Zaj-BACKLOG.md`.
:::

<Steps>

1. **Create the typed labels.** At `github.com/<org>/<repo>/labels`: delete the redundant defaults (`bug`, `documentation`, `enhancement`, `question` — replaced by typed labels), keep `duplicate`/`good first issue`/`help wanted`/`invalid`/`wontfix`, then create four typed families (~25 labels total).

   | Family | Labels (color) |
   |---|---|
   | Priority | `priority: critical` `#b60205`, `high` `#d93f0b`, `medium` `#fbca04`, `low` `#0e8a16` |
   | Type | `type: bug` `#d73a4a`, `feature` `#a2eeef`, `enhancement` `#7057ff`, `docs` `#0075ca`, `refactor` `#f9d0c4`, `security` `#ee0701`, `question` `#d876e3` |
   | Status | `status: triage` `#cfd3d7`, `confirmed` `#1d76db`, `in-progress` `#5319e7`, `blocked` `#e99695`, `needs-info` `#d876e3` |
   | Area | `area: frontend` `#bfd4f2`, `backend` `#b4a7d6`, `database` `#c5def5`, `devops` `#d4c5f9` (+ optional `auth`/`payments`/`api`) |

   - ✅ The four typed label families exist.

2. **Create the issue forms** under `.github/ISSUE_TEMPLATE/`. Example `bug_report.yml`:

   ```yaml
   name: Bug Report
   description: Report a bug or unexpected behavior
   title: "[BUG] "
   labels: ["type: bug", "status: triage"]
   body:
     - type: textarea
       id: description
       attributes: { label: Bug Description }
       validations: { required: true }
     - type: textarea
       id: steps
       attributes: { label: Steps to Reproduce }
       validations: { required: true }
     - type: textarea
       id: expected
       attributes: { label: Expected Behavior }
       validations: { required: true }
     - type: dropdown
       id: severity
       attributes:
         label: Severity
         options:
           - Critical (app unusable, data loss)
           - High (major feature broken)
           - Medium (workaround exists)
           - Low (minor inconvenience)
       validations: { required: true }
     - type: checkboxes
       id: checklist
       attributes:
         label: Pre-submission Checklist
         options:
           - label: I searched existing issues to ensure this is not a duplicate
             required: true
   ```

   Add `feature_request.yml` (problem statement, proposed solution, importance dropdown) and `task.yml` (description, acceptance criteria, area dropdown) on the same pattern, plus `config.yml` to disable blank issues and route security reports privately:

   ```yaml
   blank_issues_enabled: false
   contact_links:
     - name: Documentation
       url: https://docs.<domain>
       about: Check the docs before opening an issue
     - name: Security Vulnerability
       url: https://github.com/<org>/<repo>/security/advisories/new
       about: Report security vulnerabilities privately
   ```

   - ✅ Bug/feature/task issue forms + `config.yml` exist under `.github/ISSUE_TEMPLATE/`.

3. **Create the project board.** Organization → Projects → New project → **Kanban** → name `<App> Development`; Status field: Backlog, Triage, Todo, In Progress, In Review, Done; custom fields `Priority` (Critical/High/Medium/Low), optional `Estimate` (XS–XL); workflows item added → Backlog, reopened → Todo, closed / PR merged → Done, Enable **Auto-add** with filter `is:issue is:open`; link it: `gh project link <number> --owner <owner> --repo <owner>/<repo>`.

   - ✅ The Kanban board exists, is linked, and auto-adds open issues.

4. **Create the PR template & discussions.** Create `.github/PULL_REQUEST_TEMPLATE.md` with sections: Description, Type of Change, Related Issues, Changes Made, Screenshots, Testing Instructions, Checklist, Deployment Notes. Optionally enable Discussions (Settings → General → Features). Commit `.github/` once done.

   - ✅ The PR template is committed and Discussions are enabled if wanted.

</Steps>

### 3. Set up Rybbit analytics

Privacy-first, cookieless analytics — session replay, funnels, goals, web vitals, and error tracking with no consent banner. A complement to (not replacement for) Google Analytics.

:::note[Who does this]
🔀 **User + Agent** — 👤 **User** redeems the license and authorizes the provider account. 🤖 **Agent** drives non-secret site creation/toggles when an authorized browser/API path exists, then installs the tracking script and wires env/config.
:::

<Steps>

1. **Activate & add the site.** [app.rybbit.io/redeem](https://app.rybbit.io/redeem) → redeem license → Dashboard → Sites → Add Website (domain, no `https://`) → set Public Analytics **Off**, User ID Salting **On** → copy the Site ID.

   - ✅ The site is added and its Site ID is copied.

2. **Configure the site settings** — Block Bot Traffic On, Track IP Address Off, Web Vitals On, Error Tracking On, Track Outbound Links On, Track SPA Navigation On; connect Google Search Console.

   - ✅ The site settings match the privacy-first profile.

3. **Install the tracking script** — find layout files with a `<head>` and add the tracking script (ideally a shared `partials/analytics.blade.php`).

   ```bash
   grep -r "<!DOCTYPE html" resources/views/ packages/ --include="*.blade.php" -l
   # Expected: the layout files with a <head> to inject the script
   ```

   ```bash
   # .env
   RYBBIT_SITE_ID=<your-site-id>
   ```

   ```php
   // config/services.php
   'rybbit' => ['site_id' => env('RYBBIT_SITE_ID')],
   ```

   - ✅ The tracking script is wired via a shared partial and the Site ID is in env/config.

4. **Set skip & mask patterns** — Dashboard → Settings → Tracking Script: skip `/admin/**`, `/setting/**`; mask `/users/*/profile`.

   - ✅ Admin paths are skipped and sensitive paths masked.

5. **Enable the dashboard features** — Performance (Web Vitals); Session Replay On with Masking + Mask All Inputs On; Error Tracking On.

   - ✅ Performance, masked session replay, and error tracking are on.

6. **Wire custom events & identity.**

   ```html
   <button data-rybbit-event="signup_clicked">Sign Up</button>
   ```

   ```javascript
   window.rybbit.event("plan_purchased", { plan: "pro", interval: "yearly" });
   // inside an @auth block:
   window.rybbit.identify("{{ auth()->id() }}");
   ```

   - ✅ Custom events and authenticated-user identity are wired.

7. **Create goals & funnels** — goals (Signup Completed, Pricing Page Viewed, Trial Started) and a funnel (`/` → `/pricing` → `/register` → event).

   - ✅ Goals and a conversion funnel exist.

8. **Deploy & verify.** Deploy, set `RYBBIT_SITE_ID` in production, `php artisan config:clear && php artisan view:clear`, then visit the site in incognito and confirm hits in the Rybbit real-time dashboard. Store the Site ID, account email, dashboard URL, tier, and any API key in your password manager.

   - ✅ Real-time hits appear in the Rybbit dashboard after deploy.

</Steps>

## Checklist

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

- [ ] **🔀 Slack webhook test posts** — Deployer notifies `#<app>-deploys`, or the unavailable/waived integration has a `Zaj-BACKLOG.md` row with owner, trigger, and acceptance criterion.
- [ ] **🤖 GitHub labels, issue forms, project board, PR template** — in place; only token-scope or policy blockers may move this to `Zaj-BACKLOG.md`.
- [ ] **🔀 Rybbit live and recording hits** — admin paths skipped and inputs masked, or a no-license/no-adoption row is tracked in `Zaj-BACKLOG.md`.
- [ ] **🔀 Every N/A or blocker was accounted for** — with evidence in `Zaj-BACKLOG.md`, not a silent skip.

:::next[Next step]
[Post-launch identity & changelog](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/08-configure-app/07-post-launch/)
:::

# 6 · Integrations

> Source: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/08-configure-app/06-integrations/

## TL;DR

**Objective** — surface the integration choices — Slack notifications for errors/deploys/backups, GitHub project management (labels, issue forms, project board, PR template), and privacy-first Rybbit analytics — so operations and feedback loops are wired before users arrive.

**Steps at a glance:**
1. **Wire Slack notifications** — Automated Slack alerts for Sentry errors, deployments, and backup status.
2. **Set up project management** — Set up GitHub Issues, typed labels, YAML issue forms, a project board, and a
   PR template.
3. **Set up Rybbit analytics** — Privacy-first, cookieless analytics — session replay, funnels, goals, web
   vitals, and error tracking with no consent banner.

:::note[User part + done-when]
**🔀 User part** — humans own account creation, paid/provider authorization, OAuth/login, and secret copy. With an authorized browser/API session, the agent drives non-secret provider-console work: Slack channel/webhook setup, GitHub labels/forms/project wiring, Rybbit site configuration, Deployer tasks, env placeholders, and analytics script wiring.

**Done when** the Slack webhook posts to its channel and Deployer notifies on deploy, GitHub labels/forms/board/PR-template are in place, and Rybbit records hits in real time with admin paths skipped — or each skipped item has a `Zaj-BACKLOG.md` row with owner, trigger, and acceptance criterion. &nbsp;·&nbsp; **⏱ ~2–3 hr** &nbsp;·&nbsp; 🔀 mixed (👤 dashboards, 🤖 code/config wiring).
:::

## Background

These are valuable integrations, not mystery work to silently skip. Treat each row as **adopt or evidence-backed N/A**: configure it now when `Zaj-PROJECT.md` shows the account/tool is adopted or the setup is free and routine; mark N/A only when the project has no license, no account, no token scope, or an explicit operator decision not to adopt it. Every N/A or blocked integration gets a `Zaj-BACKLOG.md` row with owner, trigger, and acceptance criterion.

```mermaid
flowchart LR
  Sentry["Sentry errors"] --> Alerts["#app-alerts"]
  Deployer["Deployer"] --> Deploys["#app-deploys"]
  Backup["Backups"] --> Backups["#app-backups"]
  Alerts --> Slack(["Slack workspace"])
  Deploys --> Slack
  Backups --> Slack
```

## Steps

### 1. Wire Slack notifications

Automated Slack alerts for Sentry errors, deployments, and backup status.

:::note[Who does this]
🔀 **User + Agent** — 👤 **User** creates or authorizes the Slack workspace/app session and owns the webhook URL as a secret. 🤖 **Agent** drives non-secret channel/webhook navigation when browser automation is available, stores only the 1Password pointer in docs/config, wires the Deployer tasks and env vars, and runs the test `curl`.
:::

<Steps>

1. **Set up the workspace** (first project only). If you don't have a workspace, create one at [slack.com/create](https://slack.com/create). Create an incoming-webhook app: [api.slack.com/apps](https://api.slack.com/apps) → **Create New App → From scratch** → name `<Org> Notifications` → **Incoming Webhooks → Activate ON** → **Add New Webhook to Workspace** → pick a channel → copy the URL into 1Password. Store the webhook URL, workspace, app name, and creation date in your password manager; never paste the live URL into docs, commits, screenshots, or chat.

   :::note[Account-wide infra creds → shared vault, not the project vault]
   A Slack **workspace** (and its app/webhooks) typically spans **every** project on that account — the same is true for analytics, hosting, and DNS account tokens. Storing them per-project duplicates the secret and the rotation point. Use a **two-vault** layout: a per-project vault for app secrets (`APP_KEY`, DB creds, gateway keys) and a shared infra vault for account-wide infra (`op://<SharedInfraVault>/<account>/<key>`). `General-Dev` is the default example name; record the actual vault in `Zaj-PROJECT.md`. If you use a 1Password service account for agents, grant it **both** vaults — otherwise the agent can read the project secrets but not the shared infra creds it needs.
   :::

   - ✅ The workspace + incoming-webhook app exist, URL stored in the shared infra vault for this account-wide credential.

2. **Create the project channels & webhooks** — one channel per concern, then a channel-specific webhook for each.

   | Channel | Purpose |
   |---|---|
   | `#<app>-alerts` | Sentry errors and critical alerts |
   | `#<app>-deploys` | Deployment notifications |
   | `#<app>-backups` | Backup success/failure (optional) |

	   Add deploy webhook URLs to `~/Admin-Server/config/server.env` by default. Use project `shared/.env` only when this one app needs its own override:

   ```bash
	   ## === SLACK NOTIFICATIONS ===
	   SLACK_ALERTS_WEBHOOK=<your-slack-alerts-webhook-url>
	   SLACK_WEBHOOK_DEPLOYS=<your-slack-deploys-webhook-url>
	   SLACK_BACKUPS_WEBHOOK=<your-slack-backups-webhook-url>
	   # Expected: real deploy webhook in server.env; project override only when needed
   ```

	   - ✅ Per-concern channels exist with webhook URLs wired into `server.env` or a deliberate project override.

3. **Wire the integrations.**
   - **Sentry → Slack** (requires Sentry Team plan) — Settings → Integrations → Slack → authorize, then Alerts → Create Alert Rule (`> 0 errors in 1 min`, filter `production`, action: send to `#<app>-alerts`). On the free plan, capture the paid-plan trigger and acceptance criterion in `Zaj-BACKLOG.md`.
   - **Deployer → Slack** — add success/failure tasks to `deploy.php`:

     ```php
     use Deployer\Utility\Httpie;

     task('slack:notify:success', function () {
	        $webhookUrl = getenv('SLACK_WEBHOOK_DEPLOYS');
	        if (!$webhookUrl) { writeln('<comment>SLACK_WEBHOOK_DEPLOYS not set - skipping</comment>'); return; }
         $app = get('application', 'App');
         $stage = get('labels')['stage'] ?? 'unknown';
         $branch = run('git rev-parse --abbrev-ref HEAD', ['timeout' => 5])->toString();
         $commit = run('git log -1 --oneline', ['timeout' => 5])->toString();
         Httpie::post($webhookUrl)->body([
             'text' => "*{$app}* deployed to *{$stage}*\nBranch: `{$branch}`\nCommit: {$commit}",
             'username' => 'Deployer', 'icon_emoji' => ':rocket:',
         ])->send();
     })->desc('Send deploy success notification to Slack');

     task('slack:notify:failure', function () {
	        $webhookUrl = getenv('SLACK_WEBHOOK_DEPLOYS');
         if (!$webhookUrl) { return; }
         $app = get('application', 'App');
         $stage = get('labels')['stage'] ?? 'unknown';
         Httpie::post($webhookUrl)->body([
             'text' => "*{$app}* deployment to *{$stage}* failed\nCheck logs for details.",
             'username' => 'Deployer', 'icon_emoji' => ':x:',
         ])->send();
     })->desc('Send deploy failure notification to Slack');

     after('deploy:success', 'slack:notify:success');
     after('deploy:failed', 'slack:notify:failure');
     ```

   - **Backups → Slack** — easiest is to rely on Sentry Cron Monitors (no extra config). Otherwise add a `slack` block to `config/backup.php`'s `notifications` with `'webhook_url' => env('SLACK_BACKUPS_WEBHOOK')`.

   - ✅ The Sentry, Deployer, and backup notification paths are wired, or each unavailable paid/provider path has a `Zaj-BACKLOG.md` row with owner, trigger, and acceptance criterion.

4. **Test the webhook.**

   ```bash
   set -a && source .env && set +a   # or export each SLACK_*_WEBHOOK you test
   curl -X POST -H 'Content-type: application/json' \
     --data '{"text":"Slack webhook test successful!"}' \
     "$SLACK_ALERTS_WEBHOOK"
   # Expected: "ok" and the message appears in the channel
   ```

   Then run `dep deploy "$DEPLOY_TARGET"` for the selected non-production target from `Zaj-PROJECT.md` and confirm the notification lands in `#<app>-deploys`. Record the production webhook `op://` pointers in the production env template/vault entry now; Phase 12 renders/uploads production `.env` and clears the production config cache during the production deploy.

   - ✅ The test `curl` returns `ok` and a real deploy notifies `#<app>-deploys`.

</Steps>

### 2. Set up project management

Set up GitHub Issues, typed labels, YAML issue forms, a project board, and a PR template.

:::note[Who does this]
🤖 **Agent by default** — use `gh`/GitHub API for labels, issue forms, PR template, and project-board setup when the token has scope. 👤 **User** is fallback only for GitHub UI authorization or token-scope gaps; record any unavailable paid/scope-gated setup in `Zaj-BACKLOG.md`.
:::

<Steps>

1. **Create the typed labels.** At `github.com/<org>/<repo>/labels`: delete the redundant defaults (`bug`, `documentation`, `enhancement`, `question` — replaced by typed labels), keep `duplicate`/`good first issue`/`help wanted`/`invalid`/`wontfix`, then create four typed families (~25 labels total).

   | Family | Labels (color) |
   |---|---|
   | Priority | `priority: critical` `#b60205`, `high` `#d93f0b`, `medium` `#fbca04`, `low` `#0e8a16` |
   | Type | `type: bug` `#d73a4a`, `feature` `#a2eeef`, `enhancement` `#7057ff`, `docs` `#0075ca`, `refactor` `#f9d0c4`, `security` `#ee0701`, `question` `#d876e3` |
   | Status | `status: triage` `#cfd3d7`, `confirmed` `#1d76db`, `in-progress` `#5319e7`, `blocked` `#e99695`, `needs-info` `#d876e3` |
   | Area | `area: frontend` `#bfd4f2`, `backend` `#b4a7d6`, `database` `#c5def5`, `devops` `#d4c5f9` (+ optional `auth`/`payments`/`api`) |

   - ✅ The four typed label families exist.

2. **Create the issue forms** under `.github/ISSUE_TEMPLATE/`. Example `bug_report.yml`:

   ```yaml
   name: Bug Report
   description: Report a bug or unexpected behavior
   title: "[BUG] "
   labels: ["type: bug", "status: triage"]
   body:
     - type: textarea
       id: description
       attributes: { label: Bug Description }
       validations: { required: true }
     - type: textarea
       id: steps
       attributes: { label: Steps to Reproduce }
       validations: { required: true }
     - type: textarea
       id: expected
       attributes: { label: Expected Behavior }
       validations: { required: true }
     - type: dropdown
       id: severity
       attributes:
         label: Severity
         options:
           - Critical (app unusable, data loss)
           - High (major feature broken)
           - Medium (workaround exists)
           - Low (minor inconvenience)
       validations: { required: true }
     - type: checkboxes
       id: checklist
       attributes:
         label: Pre-submission Checklist
         options:
           - label: I searched existing issues to ensure this is not a duplicate
             required: true
   ```

   Add `feature_request.yml` (problem statement, proposed solution, importance dropdown) and `task.yml` (description, acceptance criteria, area dropdown) on the same pattern, plus `config.yml` to disable blank issues and route security reports privately:

   ```yaml
   blank_issues_enabled: false
   contact_links:
     - name: Documentation
       url: https://docs.<domain>
       about: Check the docs before opening an issue
     - name: Security Vulnerability
       url: https://github.com/<org>/<repo>/security/advisories/new
       about: Report security vulnerabilities privately
   ```

   - ✅ Bug/feature/task issue forms + `config.yml` exist under `.github/ISSUE_TEMPLATE/`.

3. **Create the project board.** Organization → Projects → New project → **Kanban** → name `<App> Development`; Status field: Backlog, Triage, Todo, In Progress, In Review, Done; custom fields `Priority` (Critical/High/Medium/Low), optional `Estimate` (XS–XL); workflows item added → Backlog, reopened → Todo, closed / PR merged → Done, Enable **Auto-add** with filter `is:issue is:open`; link it: `gh project link <number> --owner <owner> --repo <owner>/<repo>`.

   - ✅ The Kanban board exists, is linked, and auto-adds open issues.

4. **Create the PR template & discussions.** Create `.github/PULL_REQUEST_TEMPLATE.md` with sections: Description, Type of Change, Related Issues, Changes Made, Screenshots, Testing Instructions, Checklist, Deployment Notes. Optionally enable Discussions (Settings → General → Features). Commit `.github/` once done.

   - ✅ The PR template is committed and Discussions are enabled if wanted.

</Steps>

### 3. Set up Rybbit analytics

Privacy-first, cookieless analytics — session replay, funnels, goals, web vitals, and error tracking with no consent banner. A complement to (not replacement for) Google Analytics.

:::note[Who does this]
🔀 **User + Agent** — 👤 **User** redeems the license and authorizes the provider account. 🤖 **Agent** drives non-secret site creation/toggles when an authorized browser/API path exists, then installs the tracking script and wires env/config.
:::

<Steps>

1. **Activate & add the site.** [app.rybbit.io/redeem](https://app.rybbit.io/redeem) → redeem license → Dashboard → Sites → Add Website (domain, no `https://`) → set Public Analytics **Off**, User ID Salting **On** → copy the Site ID.

   - ✅ The site is added and its Site ID is copied.

2. **Configure the site settings** — Block Bot Traffic On, Track IP Address Off, Web Vitals On, Error Tracking On, Track Outbound Links On, Track SPA Navigation On; connect Google Search Console.

   - ✅ The site settings match the privacy-first profile.

3. **Install the tracking script** — find layout files with a `<head>` and add the tracking script (ideally a shared `partials/analytics.blade.php`).

   ```bash
   grep -r "<!DOCTYPE html" resources/views/ packages/ --include="*.blade.php" -l
   # Expected: the layout files with a <head> to inject the script
   ```

   ```bash
   # .env
   RYBBIT_SITE_ID=<your-site-id>
   ```

   ```php
   // config/services.php
   'rybbit' => ['site_id' => env('RYBBIT_SITE_ID')],
   ```

   - ✅ The tracking script is wired via a shared partial and the Site ID is in env/config.

4. **Set skip & mask patterns** — Dashboard → Settings → Tracking Script: skip `/admin/**`, `/setting/**`; mask `/users/*/profile`.

   - ✅ Admin paths are skipped and sensitive paths masked.

5. **Enable the dashboard features** — Performance (Web Vitals); Session Replay On with Masking + Mask All Inputs On; Error Tracking On.

   - ✅ Performance, masked session replay, and error tracking are on.

6. **Wire custom events & identity.**

   ```html
   <button data-rybbit-event="signup_clicked">Sign Up</button>
   ```

   ```javascript
   window.rybbit.event("plan_purchased", { plan: "pro", interval: "yearly" });
   // inside an @auth block:
   window.rybbit.identify("{{ auth()->id() }}");
   ```

   - ✅ Custom events and authenticated-user identity are wired.

7. **Create goals & funnels** — goals (Signup Completed, Pricing Page Viewed, Trial Started) and a funnel (`/` → `/pricing` → `/register` → event).

   - ✅ Goals and a conversion funnel exist.

8. **Deploy & verify.** Deploy, set `RYBBIT_SITE_ID` in production, `php artisan config:clear && php artisan view:clear`, then visit the site in incognito and confirm hits in the Rybbit real-time dashboard. Store the Site ID, account email, dashboard URL, tier, and any API key in your password manager.

   - ✅ Real-time hits appear in the Rybbit dashboard after deploy.

</Steps>

## Checklist

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

- [ ] **🔀 Slack webhook test posts** — Deployer notifies `#<app>-deploys`, or the unavailable/waived integration has a `Zaj-BACKLOG.md` row with owner, trigger, and acceptance criterion.
- [ ] **🤖 GitHub labels, issue forms, project board, PR template** — in place; only token-scope or policy blockers may move this to `Zaj-BACKLOG.md`.
- [ ] **🔀 Rybbit live and recording hits** — admin paths skipped and inputs masked, or a no-license/no-adoption row is tracked in `Zaj-BACKLOG.md`.
- [ ] **🔀 Every N/A or blocker was accounted for** — with evidence in `Zaj-BACKLOG.md`, not a silent skip.

:::next[Next step]
[Post-launch identity & changelog](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/08-configure-app/07-post-launch/)
:::

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 the integration choices — Slack notifications for errors/deploys/backups, GitHub project management (labels, issue forms, project board, PR template), and privacy-first Rybbit analytics — so operations and feedback loops are wired before users arrive.

Steps at a glance:

Wire Slack notifications — Automated Slack alerts for Sentry errors, deployments, and backup status.
Set up project management — Set up GitHub Issues, typed labels, YAML issue forms, a project board, and a PR template.
Set up Rybbit analytics — Privacy-first, cookieless analytics — session replay, funnels, goals, web vitals, and error tracking with no consent banner.

Background

These are valuable integrations, not mystery work to silently skip. Treat each row as adopt or evidence-backed N/A: configure it now when Zaj-PROJECT.md shows the account/tool is adopted or the setup is free and routine; mark N/A only when the project has no license, no account, no token scope, or an explicit operator decision not to adopt it. Every N/A or blocked integration gets a Zaj-BACKLOG.md row with owner, trigger, and acceptance criterion.

flowchart LR
  Sentry["Sentry errors"] --> Alerts["#app-alerts"]
  Deployer["Deployer"] --> Deploys["#app-deploys"]
  Backup["Backups"] --> Backups["#app-backups"]
  Alerts --> Slack(["Slack workspace"])
  Deploys --> Slack
  Backups --> Slack

Steps

1. Wire Slack notifications

Automated Slack alerts for Sentry errors, deployments, and backup status.

Set up the workspace (first project only). If you don’t have a workspace, create one at slack.com/create. Create an incoming-webhook app: api.slack.com/apps → Create New App → From scratch → name <Org> Notifications → Incoming Webhooks → Activate ON → Add New Webhook to Workspace → pick a channel → copy the URL into 1Password. Store the webhook URL, workspace, app name, and creation date in your password manager; never paste the live URL into docs, commits, screenshots, or chat.

A Slack workspace (and its app/webhooks) typically spans every project on that account — the same is true for analytics, hosting, and DNS account tokens. Storing them per-project duplicates the secret and the rotation point. Use a two-vault layout: a per-project vault for app secrets (APP_KEY, DB creds, gateway keys) and a shared infra vault for account-wide infra (op://<SharedInfraVault>/<account>/<key>). General-Dev is the default example name; record the actual vault in Zaj-PROJECT.md. If you use a 1Password service account for agents, grant it both vaults — otherwise the agent can read the project secrets but not the shared infra creds it needs.
- ✅ The workspace + incoming-webhook app exist, URL stored in the shared infra vault for this account-wide credential.
Create the project channels & webhooks — one channel per concern, then a channel-specific webhook for each.

Channel Purpose
#<app>-alerts Sentry errors and critical alerts
#<app>-deploys Deployment notifications
#<app>-backups Backup success/failure (optional)

Add deploy webhook URLs to ~/Admin-Server/config/server.env by default. Use project shared/.env only when this one app needs its own override:
Terminal window
```
    ## === SLACK NOTIFICATIONS ===
    SLACK_ALERTS_WEBHOOK=<your-slack-alerts-webhook-url>
    SLACK_WEBHOOK_DEPLOYS=<your-slack-deploys-webhook-url>
    SLACK_BACKUPS_WEBHOOK=<your-slack-backups-webhook-url>
    # Expected: real deploy webhook in server.env; project override only when needed
```
- ✅ Per-concern channels exist with webhook URLs wired into server.env or a deliberate project override.

Channel	Purpose
`#<app>-alerts`	Sentry errors and critical alerts
`#<app>-deploys`	Deployment notifications
`#<app>-backups`	Backup success/failure (optional)

Wire the integrations.

Sentry → Slack (requires Sentry Team plan) — Settings → Integrations → Slack → authorize, then Alerts → Create Alert Rule (> 0 errors in 1 min, filter production, action: send to #<app>-alerts). On the free plan, capture the paid-plan trigger and acceptance criterion in Zaj-BACKLOG.md.

Deployer → Slack — add success/failure tasks to deploy.php:

use Deployer\Utility\Httpie;

task('slack:notify:success', function () {
       $webhookUrl = getenv('SLACK_WEBHOOK_DEPLOYS');
       if (!$webhookUrl) { writeln('<comment>SLACK_WEBHOOK_DEPLOYS not set - skipping</comment>'); return; }
    $app = get('application', 'App');
    $stage = get('labels')['stage'] ?? 'unknown';
    $branch = run('git rev-parse --abbrev-ref HEAD', ['timeout' => 5])->toString();
    $commit = run('git log -1 --oneline', ['timeout' => 5])->toString();
    Httpie::post($webhookUrl)->body([
        'text' => "*{$app}* deployed to *{$stage}*\nBranch: `{$branch}`\nCommit: {$commit}",
        'username' => 'Deployer', 'icon_emoji' => ':rocket:',
    ])->send();
})->desc('Send deploy success notification to Slack');

task('slack:notify:failure', function () {
       $webhookUrl = getenv('SLACK_WEBHOOK_DEPLOYS');
    if (!$webhookUrl) { return; }
    $app = get('application', 'App');
    $stage = get('labels')['stage'] ?? 'unknown';
    Httpie::post($webhookUrl)->body([
        'text' => "*{$app}* deployment to *{$stage}* failed\nCheck logs for details.",
        'username' => 'Deployer', 'icon_emoji' => ':x:',
    ])->send();
})->desc('Send deploy failure notification to Slack');

after('deploy:success', 'slack:notify:success');
after('deploy:failed', 'slack:notify:failure');

Backups → Slack — easiest is to rely on Sentry Cron Monitors (no extra config). Otherwise add a slack block to config/backup.php’s notifications with 'webhook_url' => env('SLACK_BACKUPS_WEBHOOK').
✅ The Sentry, Deployer, and backup notification paths are wired, or each unavailable paid/provider path has a Zaj-BACKLOG.md row with owner, trigger, and acceptance criterion.

Test the webhook.
Terminal window
```
set -a && source .env && set +a   # or export each SLACK_*_WEBHOOK you test
curl -X POST -H 'Content-type: application/json' \
  --data '{"text":"Slack webhook test successful!"}' \
  "$SLACK_ALERTS_WEBHOOK"
# Expected: "ok" and the message appears in the channel
```
Then run dep deploy "$DEPLOY_TARGET" for the selected non-production target from Zaj-PROJECT.md and confirm the notification lands in #<app>-deploys. Record the production webhook op:// pointers in the production env template/vault entry now; Phase 12 renders/uploads production .env and clears the production config cache during the production deploy.
- ✅ The test curl returns ok and a real deploy notifies #<app>-deploys.

2. Set up project management

Set up GitHub Issues, typed labels, YAML issue forms, a project board, and a PR template.

Create the typed labels. At github.com/<org>/<repo>/labels: delete the redundant defaults (bug, documentation, enhancement, question — replaced by typed labels), keep duplicate/good first issue/help wanted/invalid/wontfix, then create four typed families (~25 labels total).

Family	Labels (color)
Priority	`priority: critical` `#b60205`, `high` `#d93f0b`, `medium` `#fbca04`, `low` `#0e8a16`
Type	`type: bug` `#d73a4a`, `feature` `#a2eeef`, `enhancement` `#7057ff`, `docs` `#0075ca`, `refactor` `#f9d0c4`, `security` `#ee0701`, `question` `#d876e3`
Status	`status: triage` `#cfd3d7`, `confirmed` `#1d76db`, `in-progress` `#5319e7`, `blocked` `#e99695`, `needs-info` `#d876e3`
Area	`area: frontend` `#bfd4f2`, `backend` `#b4a7d6`, `database` `#c5def5`, `devops` `#d4c5f9` (+ optional `auth`/`payments`/`api`)

✅ The four typed label families exist.

Create the issue forms under .github/ISSUE_TEMPLATE/. Example bug_report.yml:

name: Bug Report
description: Report a bug or unexpected behavior
title: "[BUG] "
labels: ["type: bug", "status: triage"]
body:
  - type: textarea
    id: description
    attributes: { label: Bug Description }
    validations: { required: true }
  - type: textarea
    id: steps
    attributes: { label: Steps to Reproduce }
    validations: { required: true }
  - type: textarea
    id: expected
    attributes: { label: Expected Behavior }
    validations: { required: true }
  - type: dropdown
    id: severity
    attributes:
      label: Severity
      options:
        - Critical (app unusable, data loss)
        - High (major feature broken)
        - Medium (workaround exists)
        - Low (minor inconvenience)
    validations: { required: true }
  - type: checkboxes
    id: checklist
    attributes:
      label: Pre-submission Checklist
      options:
        - label: I searched existing issues to ensure this is not a duplicate
          required: true

Add feature_request.yml (problem statement, proposed solution, importance dropdown) and task.yml (description, acceptance criteria, area dropdown) on the same pattern, plus config.yml to disable blank issues and route security reports privately:

blank_issues_enabled: false
contact_links:
  - name: Documentation
    url: https://docs.<domain>
    about: Check the docs before opening an issue
  - name: Security Vulnerability
    url: https://github.com/<org>/<repo>/security/advisories/new
    about: Report security vulnerabilities privately

✅ Bug/feature/task issue forms + config.yml exist under .github/ISSUE_TEMPLATE/.

Create the project board. Organization → Projects → New project → Kanban → name <App> Development; Status field: Backlog, Triage, Todo, In Progress, In Review, Done; custom fields Priority (Critical/High/Medium/Low), optional Estimate (XS–XL); workflows item added → Backlog, reopened → Todo, closed / PR merged → Done, Enable Auto-add with filter is:issue is:open; link it: gh project link <number> --owner <owner> --repo <owner>/<repo>.
- ✅ The Kanban board exists, is linked, and auto-adds open issues.
Create the PR template & discussions. Create .github/PULL_REQUEST_TEMPLATE.md with sections: Description, Type of Change, Related Issues, Changes Made, Screenshots, Testing Instructions, Checklist, Deployment Notes. Optionally enable Discussions (Settings → General → Features). Commit .github/ once done.
- ✅ The PR template is committed and Discussions are enabled if wanted.

3. Set up Rybbit analytics

Privacy-first, cookieless analytics — session replay, funnels, goals, web vitals, and error tracking with no consent banner. A complement to (not replacement for) Google Analytics.

Activate & add the site. app.rybbit.io/redeem → redeem license → Dashboard → Sites → Add Website (domain, no https://) → set Public Analytics Off, User ID Salting On → copy the Site ID.
- ✅ The site is added and its Site ID is copied.
Configure the site settings — Block Bot Traffic On, Track IP Address Off, Web Vitals On, Error Tracking On, Track Outbound Links On, Track SPA Navigation On; connect Google Search Console.
- ✅ The site settings match the privacy-first profile.
Install the tracking script — find layout files with a <head> and add the tracking script (ideally a shared partials/analytics.blade.php).
Terminal window
```
grep -r "<!DOCTYPE html" resources/views/ packages/ --include="*.blade.php" -l
# Expected: the layout files with a <head> to inject the script
```
.env
```
RYBBIT_SITE_ID=<your-site-id>
```
config/services.php
```
'rybbit' => ['site_id' => env('RYBBIT_SITE_ID')],
```
- ✅ The tracking script is wired via a shared partial and the Site ID is in env/config.
Set skip & mask patterns — Dashboard → Settings → Tracking Script: skip /admin/**, /setting/**; mask /users/*/profile.
- ✅ Admin paths are skipped and sensitive paths masked.
Enable the dashboard features — Performance (Web Vitals); Session Replay On with Masking + Mask All Inputs On; Error Tracking On.
- ✅ Performance, masked session replay, and error tracking are on.

Wire custom events & identity.

<button data-rybbit-event="signup_clicked">Sign Up</button>

window.rybbit.event("plan_purchased", { plan: "pro", interval: "yearly" });
// inside an @auth block:
window.rybbit.identify("{{ auth()->id() }}");

✅ Custom events and authenticated-user identity are wired.

Create goals & funnels — goals (Signup Completed, Pricing Page Viewed, Trial Started) and a funnel (/ → /pricing → /register → event).
- ✅ Goals and a conversion funnel exist.
Deploy & verify. Deploy, set RYBBIT_SITE_ID in production, php artisan config:clear && php artisan view:clear, then visit the site in incognito and confirm hits in the Rybbit real-time dashboard. Store the Site ID, account email, dashboard URL, tier, and any API key in your password manager.
- ✅ Real-time hits appear in the Rybbit dashboard after deploy.

Checklist

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

🔀 Slack webhook test posts — Deployer notifies #<app>-deploys, or the unavailable/waived integration has a Zaj-BACKLOG.md row with owner, trigger, and acceptance criterion.
🤖 GitHub labels, issue forms, project board, PR template — in place; only token-scope or policy blockers may move this to Zaj-BACKLOG.md.
🔀 Rybbit live and recording hits — admin paths skipped and inputs masked, or a no-license/no-adoption row is tracked in Zaj-BACKLOG.md.
🔀 Every N/A or blocker was accounted for — with evidence in Zaj-BACKLOG.md, not a silent skip.

Post-launch identity & changelog

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: 6 · Integrations
- url: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/08-configure-app/06-integrations/
- shelf: Build & Create
- doc_type: implementation playbook
- status: current
- kind: playbook
- category: tech-stack
- subcategory: laravel
- topic: codecanyon
- phase: 8
- part_number: 6 (legacy stepNumber frontmatter)
- legacy_step_number: 6
- est_time: ~2–3 hr (all three)
- description: Surface the integration choices — Slack notifications for errors/deploys/backups, GitHub project management (labels, issue forms, project board, PR template), and privacy-first Rybbit analytics.
- tags: codecanyon, laravel, slack, analytics, project-management

## Execution rules (binding)
- This is Part 6 of phase 8 (~2–3 hr (all three)) — 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.

---

# 6 · Integrations

## TL;DR

**Objective** — surface the integration choices — Slack notifications for errors/deploys/backups, GitHub project management (labels, issue forms, project board, PR template), and privacy-first Rybbit analytics — so operations and feedback loops are wired before users arrive.

**Steps at a glance:**
1. **Wire Slack notifications** — Automated Slack alerts for Sentry errors, deployments, and backup status.
2. **Set up project management** — Set up GitHub Issues, typed labels, YAML issue forms, a project board, and a
   PR template.
3. **Set up Rybbit analytics** — Privacy-first, cookieless analytics — session replay, funnels, goals, web
   vitals, and error tracking with no consent banner.

:::note[User part + done-when]
**🔀 User part** — humans own account creation, paid/provider authorization, OAuth/login, and secret copy. With an authorized browser/API session, the agent drives non-secret provider-console work: Slack channel/webhook setup, GitHub labels/forms/project wiring, Rybbit site configuration, Deployer tasks, env placeholders, and analytics script wiring.

**Done when** the Slack webhook posts to its channel and Deployer notifies on deploy, GitHub labels/forms/board/PR-template are in place, and Rybbit records hits in real time with admin paths skipped — or each skipped item has a `Zaj-BACKLOG.md` row with owner, trigger, and acceptance criterion. &nbsp;·&nbsp; **⏱ ~2–3 hr** &nbsp;·&nbsp; 🔀 mixed (👤 dashboards, 🤖 code/config wiring).
:::

## Background

These are valuable integrations, not mystery work to silently skip. Treat each row as **adopt or evidence-backed N/A**: configure it now when `Zaj-PROJECT.md` shows the account/tool is adopted or the setup is free and routine; mark N/A only when the project has no license, no account, no token scope, or an explicit operator decision not to adopt it. Every N/A or blocked integration gets a `Zaj-BACKLOG.md` row with owner, trigger, and acceptance criterion.

```mermaid
flowchart LR
  Sentry["Sentry errors"] --> Alerts["#app-alerts"]
  Deployer["Deployer"] --> Deploys["#app-deploys"]
  Backup["Backups"] --> Backups["#app-backups"]
  Alerts --> Slack(["Slack workspace"])
  Deploys --> Slack
  Backups --> Slack
```

## Steps

### 1. Wire Slack notifications

Automated Slack alerts for Sentry errors, deployments, and backup status.

:::note[Who does this]
🔀 **User + Agent** — 👤 **User** creates or authorizes the Slack workspace/app session and owns the webhook URL as a secret. 🤖 **Agent** drives non-secret channel/webhook navigation when browser automation is available, stores only the 1Password pointer in docs/config, wires the Deployer tasks and env vars, and runs the test `curl`.
:::

<Steps>

1. **Set up the workspace** (first project only). If you don't have a workspace, create one at [slack.com/create](https://slack.com/create). Create an incoming-webhook app: [api.slack.com/apps](https://api.slack.com/apps) → **Create New App → From scratch** → name `<Org> Notifications` → **Incoming Webhooks → Activate ON** → **Add New Webhook to Workspace** → pick a channel → copy the URL into 1Password. Store the webhook URL, workspace, app name, and creation date in your password manager; never paste the live URL into docs, commits, screenshots, or chat.

   :::note[Account-wide infra creds → shared vault, not the project vault]
   A Slack **workspace** (and its app/webhooks) typically spans **every** project on that account — the same is true for analytics, hosting, and DNS account tokens. Storing them per-project duplicates the secret and the rotation point. Use a **two-vault** layout: a per-project vault for app secrets (`APP_KEY`, DB creds, gateway keys) and a shared infra vault for account-wide infra (`op://<SharedInfraVault>/<account>/<key>`). `General-Dev` is the default example name; record the actual vault in `Zaj-PROJECT.md`. If you use a 1Password service account for agents, grant it **both** vaults — otherwise the agent can read the project secrets but not the shared infra creds it needs.
   :::

   - ✅ The workspace + incoming-webhook app exist, URL stored in the shared infra vault for this account-wide credential.

2. **Create the project channels & webhooks** — one channel per concern, then a channel-specific webhook for each.

   | Channel | Purpose |
   |---|---|
   | `#<app>-alerts` | Sentry errors and critical alerts |
   | `#<app>-deploys` | Deployment notifications |
   | `#<app>-backups` | Backup success/failure (optional) |

	   Add deploy webhook URLs to `~/Admin-Server/config/server.env` by default. Use project `shared/.env` only when this one app needs its own override:

   ```bash
	   ## === SLACK NOTIFICATIONS ===
	   SLACK_ALERTS_WEBHOOK=<your-slack-alerts-webhook-url>
	   SLACK_WEBHOOK_DEPLOYS=<your-slack-deploys-webhook-url>
	   SLACK_BACKUPS_WEBHOOK=<your-slack-backups-webhook-url>
	   # Expected: real deploy webhook in server.env; project override only when needed
   ```

	   - ✅ Per-concern channels exist with webhook URLs wired into `server.env` or a deliberate project override.

3. **Wire the integrations.**
   - **Sentry → Slack** (requires Sentry Team plan) — Settings → Integrations → Slack → authorize, then Alerts → Create Alert Rule (`> 0 errors in 1 min`, filter `production`, action: send to `#<app>-alerts`). On the free plan, capture the paid-plan trigger and acceptance criterion in `Zaj-BACKLOG.md`.
   - **Deployer → Slack** — add success/failure tasks to `deploy.php`:

     ```php
     use Deployer\Utility\Httpie;

     task('slack:notify:success', function () {
	        $webhookUrl = getenv('SLACK_WEBHOOK_DEPLOYS');
	        if (!$webhookUrl) { writeln('<comment>SLACK_WEBHOOK_DEPLOYS not set - skipping</comment>'); return; }
         $app = get('application', 'App');
         $stage = get('labels')['stage'] ?? 'unknown';
         $branch = run('git rev-parse --abbrev-ref HEAD', ['timeout' => 5])->toString();
         $commit = run('git log -1 --oneline', ['timeout' => 5])->toString();
         Httpie::post($webhookUrl)->body([
             'text' => "*{$app}* deployed to *{$stage}*\nBranch: `{$branch}`\nCommit: {$commit}",
             'username' => 'Deployer', 'icon_emoji' => ':rocket:',
         ])->send();
     })->desc('Send deploy success notification to Slack');

     task('slack:notify:failure', function () {
	        $webhookUrl = getenv('SLACK_WEBHOOK_DEPLOYS');
         if (!$webhookUrl) { return; }
         $app = get('application', 'App');
         $stage = get('labels')['stage'] ?? 'unknown';
         Httpie::post($webhookUrl)->body([
             'text' => "*{$app}* deployment to *{$stage}* failed\nCheck logs for details.",
             'username' => 'Deployer', 'icon_emoji' => ':x:',
         ])->send();
     })->desc('Send deploy failure notification to Slack');

     after('deploy:success', 'slack:notify:success');
     after('deploy:failed', 'slack:notify:failure');
     ```

   - **Backups → Slack** — easiest is to rely on Sentry Cron Monitors (no extra config). Otherwise add a `slack` block to `config/backup.php`'s `notifications` with `'webhook_url' => env('SLACK_BACKUPS_WEBHOOK')`.

   - ✅ The Sentry, Deployer, and backup notification paths are wired, or each unavailable paid/provider path has a `Zaj-BACKLOG.md` row with owner, trigger, and acceptance criterion.

4. **Test the webhook.**

   ```bash
   set -a && source .env && set +a   # or export each SLACK_*_WEBHOOK you test
   curl -X POST -H 'Content-type: application/json' \
     --data '{"text":"Slack webhook test successful!"}' \
     "$SLACK_ALERTS_WEBHOOK"
   # Expected: "ok" and the message appears in the channel
   ```

   Then run `dep deploy "$DEPLOY_TARGET"` for the selected non-production target from `Zaj-PROJECT.md` and confirm the notification lands in `#<app>-deploys`. Record the production webhook `op://` pointers in the production env template/vault entry now; Phase 12 renders/uploads production `.env` and clears the production config cache during the production deploy.

   - ✅ The test `curl` returns `ok` and a real deploy notifies `#<app>-deploys`.

</Steps>

### 2. Set up project management

Set up GitHub Issues, typed labels, YAML issue forms, a project board, and a PR template.

:::note[Who does this]
🤖 **Agent by default** — use `gh`/GitHub API for labels, issue forms, PR template, and project-board setup when the token has scope. 👤 **User** is fallback only for GitHub UI authorization or token-scope gaps; record any unavailable paid/scope-gated setup in `Zaj-BACKLOG.md`.
:::

<Steps>

1. **Create the typed labels.** At `github.com/<org>/<repo>/labels`: delete the redundant defaults (`bug`, `documentation`, `enhancement`, `question` — replaced by typed labels), keep `duplicate`/`good first issue`/`help wanted`/`invalid`/`wontfix`, then create four typed families (~25 labels total).

   | Family | Labels (color) |
   |---|---|
   | Priority | `priority: critical` `#b60205`, `high` `#d93f0b`, `medium` `#fbca04`, `low` `#0e8a16` |
   | Type | `type: bug` `#d73a4a`, `feature` `#a2eeef`, `enhancement` `#7057ff`, `docs` `#0075ca`, `refactor` `#f9d0c4`, `security` `#ee0701`, `question` `#d876e3` |
   | Status | `status: triage` `#cfd3d7`, `confirmed` `#1d76db`, `in-progress` `#5319e7`, `blocked` `#e99695`, `needs-info` `#d876e3` |
   | Area | `area: frontend` `#bfd4f2`, `backend` `#b4a7d6`, `database` `#c5def5`, `devops` `#d4c5f9` (+ optional `auth`/`payments`/`api`) |

   - ✅ The four typed label families exist.

2. **Create the issue forms** under `.github/ISSUE_TEMPLATE/`. Example `bug_report.yml`:

   ```yaml
   name: Bug Report
   description: Report a bug or unexpected behavior
   title: "[BUG] "
   labels: ["type: bug", "status: triage"]
   body:
     - type: textarea
       id: description
       attributes: { label: Bug Description }
       validations: { required: true }
     - type: textarea
       id: steps
       attributes: { label: Steps to Reproduce }
       validations: { required: true }
     - type: textarea
       id: expected
       attributes: { label: Expected Behavior }
       validations: { required: true }
     - type: dropdown
       id: severity
       attributes:
         label: Severity
         options:
           - Critical (app unusable, data loss)
           - High (major feature broken)
           - Medium (workaround exists)
           - Low (minor inconvenience)
       validations: { required: true }
     - type: checkboxes
       id: checklist
       attributes:
         label: Pre-submission Checklist
         options:
           - label: I searched existing issues to ensure this is not a duplicate
             required: true
   ```

   Add `feature_request.yml` (problem statement, proposed solution, importance dropdown) and `task.yml` (description, acceptance criteria, area dropdown) on the same pattern, plus `config.yml` to disable blank issues and route security reports privately:

   ```yaml
   blank_issues_enabled: false
   contact_links:
     - name: Documentation
       url: https://docs.<domain>
       about: Check the docs before opening an issue
     - name: Security Vulnerability
       url: https://github.com/<org>/<repo>/security/advisories/new
       about: Report security vulnerabilities privately
   ```

   - ✅ Bug/feature/task issue forms + `config.yml` exist under `.github/ISSUE_TEMPLATE/`.

3. **Create the project board.** Organization → Projects → New project → **Kanban** → name `<App> Development`; Status field: Backlog, Triage, Todo, In Progress, In Review, Done; custom fields `Priority` (Critical/High/Medium/Low), optional `Estimate` (XS–XL); workflows item added → Backlog, reopened → Todo, closed / PR merged → Done, Enable **Auto-add** with filter `is:issue is:open`; link it: `gh project link <number> --owner <owner> --repo <owner>/<repo>`.

   - ✅ The Kanban board exists, is linked, and auto-adds open issues.

4. **Create the PR template & discussions.** Create `.github/PULL_REQUEST_TEMPLATE.md` with sections: Description, Type of Change, Related Issues, Changes Made, Screenshots, Testing Instructions, Checklist, Deployment Notes. Optionally enable Discussions (Settings → General → Features). Commit `.github/` once done.

   - ✅ The PR template is committed and Discussions are enabled if wanted.

</Steps>

### 3. Set up Rybbit analytics

Privacy-first, cookieless analytics — session replay, funnels, goals, web vitals, and error tracking with no consent banner. A complement to (not replacement for) Google Analytics.

:::note[Who does this]
🔀 **User + Agent** — 👤 **User** redeems the license and authorizes the provider account. 🤖 **Agent** drives non-secret site creation/toggles when an authorized browser/API path exists, then installs the tracking script and wires env/config.
:::

<Steps>

1. **Activate & add the site.** [app.rybbit.io/redeem](https://app.rybbit.io/redeem) → redeem license → Dashboard → Sites → Add Website (domain, no `https://`) → set Public Analytics **Off**, User ID Salting **On** → copy the Site ID.

   - ✅ The site is added and its Site ID is copied.

2. **Configure the site settings** — Block Bot Traffic On, Track IP Address Off, Web Vitals On, Error Tracking On, Track Outbound Links On, Track SPA Navigation On; connect Google Search Console.

   - ✅ The site settings match the privacy-first profile.

3. **Install the tracking script** — find layout files with a `<head>` and add the tracking script (ideally a shared `partials/analytics.blade.php`).

   ```bash
   grep -r "<!DOCTYPE html" resources/views/ packages/ --include="*.blade.php" -l
   # Expected: the layout files with a <head> to inject the script
   ```

   ```bash
   # .env
   RYBBIT_SITE_ID=<your-site-id>
   ```

   ```php
   // config/services.php
   'rybbit' => ['site_id' => env('RYBBIT_SITE_ID')],
   ```

   - ✅ The tracking script is wired via a shared partial and the Site ID is in env/config.

4. **Set skip & mask patterns** — Dashboard → Settings → Tracking Script: skip `/admin/**`, `/setting/**`; mask `/users/*/profile`.

   - ✅ Admin paths are skipped and sensitive paths masked.

5. **Enable the dashboard features** — Performance (Web Vitals); Session Replay On with Masking + Mask All Inputs On; Error Tracking On.

   - ✅ Performance, masked session replay, and error tracking are on.

6. **Wire custom events & identity.**

   ```html
   <button data-rybbit-event="signup_clicked">Sign Up</button>
   ```

   ```javascript
   window.rybbit.event("plan_purchased", { plan: "pro", interval: "yearly" });
   // inside an @auth block:
   window.rybbit.identify("{{ auth()->id() }}");
   ```

   - ✅ Custom events and authenticated-user identity are wired.

7. **Create goals & funnels** — goals (Signup Completed, Pricing Page Viewed, Trial Started) and a funnel (`/` → `/pricing` → `/register` → event).

   - ✅ Goals and a conversion funnel exist.

8. **Deploy & verify.** Deploy, set `RYBBIT_SITE_ID` in production, `php artisan config:clear && php artisan view:clear`, then visit the site in incognito and confirm hits in the Rybbit real-time dashboard. Store the Site ID, account email, dashboard URL, tier, and any API key in your password manager.

   - ✅ Real-time hits appear in the Rybbit dashboard after deploy.

</Steps>

## Checklist

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

- [ ] **🔀 Slack webhook test posts** — Deployer notifies `#<app>-deploys`, or the unavailable/waived integration has a `Zaj-BACKLOG.md` row with owner, trigger, and acceptance criterion.
- [ ] **🤖 GitHub labels, issue forms, project board, PR template** — in place; only token-scope or policy blockers may move this to `Zaj-BACKLOG.md`.
- [ ] **🔀 Rybbit live and recording hits** — admin paths skipped and inputs masked, or a no-license/no-adoption row is tracked in `Zaj-BACKLOG.md`.
- [ ] **🔀 Every N/A or blocker was accounted for** — with evidence in `Zaj-BACKLOG.md`, not a silent skip.

:::next[Next step]
[Post-launch identity & changelog](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/08-configure-app/07-post-launch/)
:::

# 6 · Integrations

> Source: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/08-configure-app/06-integrations/

## TL;DR

**Objective** — surface the integration choices — Slack notifications for errors/deploys/backups, GitHub project management (labels, issue forms, project board, PR template), and privacy-first Rybbit analytics — so operations and feedback loops are wired before users arrive.

**Steps at a glance:**
1. **Wire Slack notifications** — Automated Slack alerts for Sentry errors, deployments, and backup status.
2. **Set up project management** — Set up GitHub Issues, typed labels, YAML issue forms, a project board, and a
   PR template.
3. **Set up Rybbit analytics** — Privacy-first, cookieless analytics — session replay, funnels, goals, web
   vitals, and error tracking with no consent banner.

:::note[User part + done-when]
**🔀 User part** — humans own account creation, paid/provider authorization, OAuth/login, and secret copy. With an authorized browser/API session, the agent drives non-secret provider-console work: Slack channel/webhook setup, GitHub labels/forms/project wiring, Rybbit site configuration, Deployer tasks, env placeholders, and analytics script wiring.

**Done when** the Slack webhook posts to its channel and Deployer notifies on deploy, GitHub labels/forms/board/PR-template are in place, and Rybbit records hits in real time with admin paths skipped — or each skipped item has a `Zaj-BACKLOG.md` row with owner, trigger, and acceptance criterion. &nbsp;·&nbsp; **⏱ ~2–3 hr** &nbsp;·&nbsp; 🔀 mixed (👤 dashboards, 🤖 code/config wiring).
:::

## Background

These are valuable integrations, not mystery work to silently skip. Treat each row as **adopt or evidence-backed N/A**: configure it now when `Zaj-PROJECT.md` shows the account/tool is adopted or the setup is free and routine; mark N/A only when the project has no license, no account, no token scope, or an explicit operator decision not to adopt it. Every N/A or blocked integration gets a `Zaj-BACKLOG.md` row with owner, trigger, and acceptance criterion.

```mermaid
flowchart LR
  Sentry["Sentry errors"] --> Alerts["#app-alerts"]
  Deployer["Deployer"] --> Deploys["#app-deploys"]
  Backup["Backups"] --> Backups["#app-backups"]
  Alerts --> Slack(["Slack workspace"])
  Deploys --> Slack
  Backups --> Slack
```

## Steps

### 1. Wire Slack notifications

Automated Slack alerts for Sentry errors, deployments, and backup status.

:::note[Who does this]
🔀 **User + Agent** — 👤 **User** creates or authorizes the Slack workspace/app session and owns the webhook URL as a secret. 🤖 **Agent** drives non-secret channel/webhook navigation when browser automation is available, stores only the 1Password pointer in docs/config, wires the Deployer tasks and env vars, and runs the test `curl`.
:::

<Steps>

1. **Set up the workspace** (first project only). If you don't have a workspace, create one at [slack.com/create](https://slack.com/create). Create an incoming-webhook app: [api.slack.com/apps](https://api.slack.com/apps) → **Create New App → From scratch** → name `<Org> Notifications` → **Incoming Webhooks → Activate ON** → **Add New Webhook to Workspace** → pick a channel → copy the URL into 1Password. Store the webhook URL, workspace, app name, and creation date in your password manager; never paste the live URL into docs, commits, screenshots, or chat.

   :::note[Account-wide infra creds → shared vault, not the project vault]
   A Slack **workspace** (and its app/webhooks) typically spans **every** project on that account — the same is true for analytics, hosting, and DNS account tokens. Storing them per-project duplicates the secret and the rotation point. Use a **two-vault** layout: a per-project vault for app secrets (`APP_KEY`, DB creds, gateway keys) and a shared infra vault for account-wide infra (`op://<SharedInfraVault>/<account>/<key>`). `General-Dev` is the default example name; record the actual vault in `Zaj-PROJECT.md`. If you use a 1Password service account for agents, grant it **both** vaults — otherwise the agent can read the project secrets but not the shared infra creds it needs.
   :::

   - ✅ The workspace + incoming-webhook app exist, URL stored in the shared infra vault for this account-wide credential.

2. **Create the project channels & webhooks** — one channel per concern, then a channel-specific webhook for each.

   | Channel | Purpose |
   |---|---|
   | `#<app>-alerts` | Sentry errors and critical alerts |
   | `#<app>-deploys` | Deployment notifications |
   | `#<app>-backups` | Backup success/failure (optional) |

	   Add deploy webhook URLs to `~/Admin-Server/config/server.env` by default. Use project `shared/.env` only when this one app needs its own override:

   ```bash
	   ## === SLACK NOTIFICATIONS ===
	   SLACK_ALERTS_WEBHOOK=<your-slack-alerts-webhook-url>
	   SLACK_WEBHOOK_DEPLOYS=<your-slack-deploys-webhook-url>
	   SLACK_BACKUPS_WEBHOOK=<your-slack-backups-webhook-url>
	   # Expected: real deploy webhook in server.env; project override only when needed
   ```

	   - ✅ Per-concern channels exist with webhook URLs wired into `server.env` or a deliberate project override.

3. **Wire the integrations.**
   - **Sentry → Slack** (requires Sentry Team plan) — Settings → Integrations → Slack → authorize, then Alerts → Create Alert Rule (`> 0 errors in 1 min`, filter `production`, action: send to `#<app>-alerts`). On the free plan, capture the paid-plan trigger and acceptance criterion in `Zaj-BACKLOG.md`.
   - **Deployer → Slack** — add success/failure tasks to `deploy.php`:

     ```php
     use Deployer\Utility\Httpie;

     task('slack:notify:success', function () {
	        $webhookUrl = getenv('SLACK_WEBHOOK_DEPLOYS');
	        if (!$webhookUrl) { writeln('<comment>SLACK_WEBHOOK_DEPLOYS not set - skipping</comment>'); return; }
         $app = get('application', 'App');
         $stage = get('labels')['stage'] ?? 'unknown';
         $branch = run('git rev-parse --abbrev-ref HEAD', ['timeout' => 5])->toString();
         $commit = run('git log -1 --oneline', ['timeout' => 5])->toString();
         Httpie::post($webhookUrl)->body([
             'text' => "*{$app}* deployed to *{$stage}*\nBranch: `{$branch}`\nCommit: {$commit}",
             'username' => 'Deployer', 'icon_emoji' => ':rocket:',
         ])->send();
     })->desc('Send deploy success notification to Slack');

     task('slack:notify:failure', function () {
	        $webhookUrl = getenv('SLACK_WEBHOOK_DEPLOYS');
         if (!$webhookUrl) { return; }
         $app = get('application', 'App');
         $stage = get('labels')['stage'] ?? 'unknown';
         Httpie::post($webhookUrl)->body([
             'text' => "*{$app}* deployment to *{$stage}* failed\nCheck logs for details.",
             'username' => 'Deployer', 'icon_emoji' => ':x:',
         ])->send();
     })->desc('Send deploy failure notification to Slack');

     after('deploy:success', 'slack:notify:success');
     after('deploy:failed', 'slack:notify:failure');
     ```

   - **Backups → Slack** — easiest is to rely on Sentry Cron Monitors (no extra config). Otherwise add a `slack` block to `config/backup.php`'s `notifications` with `'webhook_url' => env('SLACK_BACKUPS_WEBHOOK')`.

   - ✅ The Sentry, Deployer, and backup notification paths are wired, or each unavailable paid/provider path has a `Zaj-BACKLOG.md` row with owner, trigger, and acceptance criterion.

4. **Test the webhook.**

   ```bash
   set -a && source .env && set +a   # or export each SLACK_*_WEBHOOK you test
   curl -X POST -H 'Content-type: application/json' \
     --data '{"text":"Slack webhook test successful!"}' \
     "$SLACK_ALERTS_WEBHOOK"
   # Expected: "ok" and the message appears in the channel
   ```

   Then run `dep deploy "$DEPLOY_TARGET"` for the selected non-production target from `Zaj-PROJECT.md` and confirm the notification lands in `#<app>-deploys`. Record the production webhook `op://` pointers in the production env template/vault entry now; Phase 12 renders/uploads production `.env` and clears the production config cache during the production deploy.

   - ✅ The test `curl` returns `ok` and a real deploy notifies `#<app>-deploys`.

</Steps>

### 2. Set up project management

Set up GitHub Issues, typed labels, YAML issue forms, a project board, and a PR template.

:::note[Who does this]
🤖 **Agent by default** — use `gh`/GitHub API for labels, issue forms, PR template, and project-board setup when the token has scope. 👤 **User** is fallback only for GitHub UI authorization or token-scope gaps; record any unavailable paid/scope-gated setup in `Zaj-BACKLOG.md`.
:::

<Steps>

1. **Create the typed labels.** At `github.com/<org>/<repo>/labels`: delete the redundant defaults (`bug`, `documentation`, `enhancement`, `question` — replaced by typed labels), keep `duplicate`/`good first issue`/`help wanted`/`invalid`/`wontfix`, then create four typed families (~25 labels total).

   | Family | Labels (color) |
   |---|---|
   | Priority | `priority: critical` `#b60205`, `high` `#d93f0b`, `medium` `#fbca04`, `low` `#0e8a16` |
   | Type | `type: bug` `#d73a4a`, `feature` `#a2eeef`, `enhancement` `#7057ff`, `docs` `#0075ca`, `refactor` `#f9d0c4`, `security` `#ee0701`, `question` `#d876e3` |
   | Status | `status: triage` `#cfd3d7`, `confirmed` `#1d76db`, `in-progress` `#5319e7`, `blocked` `#e99695`, `needs-info` `#d876e3` |
   | Area | `area: frontend` `#bfd4f2`, `backend` `#b4a7d6`, `database` `#c5def5`, `devops` `#d4c5f9` (+ optional `auth`/`payments`/`api`) |

   - ✅ The four typed label families exist.

2. **Create the issue forms** under `.github/ISSUE_TEMPLATE/`. Example `bug_report.yml`:

   ```yaml
   name: Bug Report
   description: Report a bug or unexpected behavior
   title: "[BUG] "
   labels: ["type: bug", "status: triage"]
   body:
     - type: textarea
       id: description
       attributes: { label: Bug Description }
       validations: { required: true }
     - type: textarea
       id: steps
       attributes: { label: Steps to Reproduce }
       validations: { required: true }
     - type: textarea
       id: expected
       attributes: { label: Expected Behavior }
       validations: { required: true }
     - type: dropdown
       id: severity
       attributes:
         label: Severity
         options:
           - Critical (app unusable, data loss)
           - High (major feature broken)
           - Medium (workaround exists)
           - Low (minor inconvenience)
       validations: { required: true }
     - type: checkboxes
       id: checklist
       attributes:
         label: Pre-submission Checklist
         options:
           - label: I searched existing issues to ensure this is not a duplicate
             required: true
   ```

   Add `feature_request.yml` (problem statement, proposed solution, importance dropdown) and `task.yml` (description, acceptance criteria, area dropdown) on the same pattern, plus `config.yml` to disable blank issues and route security reports privately:

   ```yaml
   blank_issues_enabled: false
   contact_links:
     - name: Documentation
       url: https://docs.<domain>
       about: Check the docs before opening an issue
     - name: Security Vulnerability
       url: https://github.com/<org>/<repo>/security/advisories/new
       about: Report security vulnerabilities privately
   ```

   - ✅ Bug/feature/task issue forms + `config.yml` exist under `.github/ISSUE_TEMPLATE/`.

3. **Create the project board.** Organization → Projects → New project → **Kanban** → name `<App> Development`; Status field: Backlog, Triage, Todo, In Progress, In Review, Done; custom fields `Priority` (Critical/High/Medium/Low), optional `Estimate` (XS–XL); workflows item added → Backlog, reopened → Todo, closed / PR merged → Done, Enable **Auto-add** with filter `is:issue is:open`; link it: `gh project link <number> --owner <owner> --repo <owner>/<repo>`.

   - ✅ The Kanban board exists, is linked, and auto-adds open issues.

4. **Create the PR template & discussions.** Create `.github/PULL_REQUEST_TEMPLATE.md` with sections: Description, Type of Change, Related Issues, Changes Made, Screenshots, Testing Instructions, Checklist, Deployment Notes. Optionally enable Discussions (Settings → General → Features). Commit `.github/` once done.

   - ✅ The PR template is committed and Discussions are enabled if wanted.

</Steps>

### 3. Set up Rybbit analytics

Privacy-first, cookieless analytics — session replay, funnels, goals, web vitals, and error tracking with no consent banner. A complement to (not replacement for) Google Analytics.

:::note[Who does this]
🔀 **User + Agent** — 👤 **User** redeems the license and authorizes the provider account. 🤖 **Agent** drives non-secret site creation/toggles when an authorized browser/API path exists, then installs the tracking script and wires env/config.
:::

<Steps>

1. **Activate & add the site.** [app.rybbit.io/redeem](https://app.rybbit.io/redeem) → redeem license → Dashboard → Sites → Add Website (domain, no `https://`) → set Public Analytics **Off**, User ID Salting **On** → copy the Site ID.

   - ✅ The site is added and its Site ID is copied.

2. **Configure the site settings** — Block Bot Traffic On, Track IP Address Off, Web Vitals On, Error Tracking On, Track Outbound Links On, Track SPA Navigation On; connect Google Search Console.

   - ✅ The site settings match the privacy-first profile.

3. **Install the tracking script** — find layout files with a `<head>` and add the tracking script (ideally a shared `partials/analytics.blade.php`).

   ```bash
   grep -r "<!DOCTYPE html" resources/views/ packages/ --include="*.blade.php" -l
   # Expected: the layout files with a <head> to inject the script
   ```

   ```bash
   # .env
   RYBBIT_SITE_ID=<your-site-id>
   ```

   ```php
   // config/services.php
   'rybbit' => ['site_id' => env('RYBBIT_SITE_ID')],
   ```

   - ✅ The tracking script is wired via a shared partial and the Site ID is in env/config.

4. **Set skip & mask patterns** — Dashboard → Settings → Tracking Script: skip `/admin/**`, `/setting/**`; mask `/users/*/profile`.

   - ✅ Admin paths are skipped and sensitive paths masked.

5. **Enable the dashboard features** — Performance (Web Vitals); Session Replay On with Masking + Mask All Inputs On; Error Tracking On.

   - ✅ Performance, masked session replay, and error tracking are on.

6. **Wire custom events & identity.**

   ```html
   <button data-rybbit-event="signup_clicked">Sign Up</button>
   ```

   ```javascript
   window.rybbit.event("plan_purchased", { plan: "pro", interval: "yearly" });
   // inside an @auth block:
   window.rybbit.identify("{{ auth()->id() }}");
   ```

   - ✅ Custom events and authenticated-user identity are wired.

7. **Create goals & funnels** — goals (Signup Completed, Pricing Page Viewed, Trial Started) and a funnel (`/` → `/pricing` → `/register` → event).

   - ✅ Goals and a conversion funnel exist.

8. **Deploy & verify.** Deploy, set `RYBBIT_SITE_ID` in production, `php artisan config:clear && php artisan view:clear`, then visit the site in incognito and confirm hits in the Rybbit real-time dashboard. Store the Site ID, account email, dashboard URL, tier, and any API key in your password manager.

   - ✅ Real-time hits appear in the Rybbit dashboard after deploy.

</Steps>

## Checklist

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

- [ ] **🔀 Slack webhook test posts** — Deployer notifies `#<app>-deploys`, or the unavailable/waived integration has a `Zaj-BACKLOG.md` row with owner, trigger, and acceptance criterion.
- [ ] **🤖 GitHub labels, issue forms, project board, PR template** — in place; only token-scope or policy blockers may move this to `Zaj-BACKLOG.md`.
- [ ] **🔀 Rybbit live and recording hits** — admin paths skipped and inputs masked, or a no-license/no-adoption row is tracked in `Zaj-BACKLOG.md`.
- [ ] **🔀 Every N/A or blocker was accounted for** — with evidence in `Zaj-BACKLOG.md`, not a silent skip.

:::next[Next step]
[Post-launch identity & changelog](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/08-configure-app/07-post-launch/)
:::