# Hyperchat 1.5.3 — preserve your customizations

This package includes all previous 1.5 updates plus optional direct Meta setup and webhook diagnostics. Extract it into a separate directory. Never extract over your installed app or rerun fresh-install setup on an existing installation.

## Prompt for your coding agent

> Read UPGRADE_1.5.3.md and the guides for my installed baseline. Inspect my version, deployment targets and customizations. Back up my source and database using my existing process; keep secrets out of logs and Git. Compare my customized installation, an untouched copy of my previous release and this incoming release with scripts/plan-upgrade.mjs. Prepare a feature-by-feature merge plan. Preserve branding, routes, roles, integrations, schema extensions, dependencies, secrets and data. Merge on an isolated branch without replacing folders or running fresh-install setup. Validate before deploying the merged backend, then frontend. Leave all new integrations, schedules and rules disabled until I configure them. Direct Meta Follow-to-DM is setup and diagnostics only; do not enable or claim a sending trigger.

## Choose your baseline

- **1.5.2:** merge the direct Meta setup/diagnostics changes below.
- **1.5.1:** also read UPGRADE_1.5.2.md and docs/AGENCY_OPERATIONS.md for leads, approval stages, reports, agency overview and monitoring rules.
- **1.5.0-beta.1:** also read UPGRADE_1.5.1.md for advertising/account reporting.
- **0.1.0 or unknown:** review the complete incoming manifest and docs/USER_GUIDE.md. Changes cover publishing, ads, creative templates, CRM/API, teams, reporting and automations. Do not assume copying only the newest files completes the upgrade. Without a trustworthy old archive, omit the baseline argument and review existing files manually.

```sh
node scripts/plan-upgrade.mjs --installed /path/to/current --baseline /path/to/untouched-old-release --incoming /path/to/hyperchat-1.5.3 > upgrade-plan.json
```

The planner is read-only. Its classifications do not authorize overwriting custom files or deleting local-only files. Keep .env files, provider credentials, bootstrap state, authentication secrets and database records unchanged.

## Direct Meta changes

Review new convex/metaFollow.ts, src/components/meta-follow-settings.tsx, tests/meta-follow.spec.ts, docs/FOLLOW_TO_DM.md and public/guides/meta-follow-to-dm.md. Merge shared changes in convex/http.ts, convex/schema.ts, src/components/connected-studio.tsx and src/app/workspace.css by intent; preserve existing webhook routes, signature checks, workspace authorization and custom UI.

Configuration is administrator-only and secrets remain server-side. Diagnostics validate verification tokens and account-scoped signed payloads without creating contacts, conversations or automation runs. The feature does not implement outbound Follow-to-DM sending. Restricted provider access and an independently tested sender are still required before that capability can be enabled.

## Verify the merged installation

```sh
pnpm install --frozen-lockfile
pnpm typecheck
pnpm test
pnpm test:backend
pnpm build
node scripts/doctor.mjs --json
```

Regenerate Convex bindings against your own project. Verify existing authentication, workspaces, inbox, automations, publishing, CRM integrations and custom features. Check that anonymous/non-admin users cannot access direct Meta configuration or secrets and that existing webhook routes remain intact. Deploy your merged backend before the frontend using your own project's deployment workflow. Provider fixtures and passing builds do not prove live channel acceptance.

Preserve the previous archive and your backups for rollback. Schema changes may require a database-aware rollback; restoring old frontend files alone is not sufficient.