Maintenance, diagnostics and recovery

Own your customized product

You operate the provider accounts and maintain the source you customize. There is no seller-operated service required for setup or runtime. This snapshot does not include an automatic starter-update mechanism, a general background-job system, analytics service, internationalization framework or alternative-provider matrix.

Use the acquisition, license and support terms actually supplied with your purchase. A future release number, response-time commitment or perpetual update entitlement cannot be inferred from the source. Keep your starting release/source identifier and a record of the changes you adopt. The update guide explains why a clean initial snapshot needs deliberate merging.

Responsibility map

Admin panel

The starter's /admin area gives operators a read-only view of customer information across users, workspaces, subscriptions, AI usage and feedback. Operators sign in through the normal application login. Access requires separate operator membership; an organisation's Owner or Admin role doesn't grant access to this panel.

After Kickstart, create and confirm your application account. From the configured project folder, grant that account access:

npm run admin:grant -- --email YOUR_EMAIL

Replace YOUR_EMAIL with your account email. The command uses the existing hosted project and matching setup receipt; it doesn't create an account or select another project. Add --check for a read-only preview. Then open /admin, or choose Admin in your account menu.

Operators can add or remove other confirmed operators through Manage admins. The last operator can't be removed. Customer data stays read-only: the panel doesn't provide impersonation, paid-access overrides or credit adjustments. Treat billing metrics as informational until you've verified payment synchronization in your installation.

Dependencies and formatting

Keep exact dependencies and the lockfile together. Before an update, read the package's official release/migration documentation, inspect your current installed version, and choose a bounded change. Next.js APIs can change between releases; consult the installed documentation under node_modules/next/dist/docs/ for the version in use.

Run npm ci, typecheck, lint, relevant fixtures and a production build. Exercise affected browser paths. npm run format writes TS/TSX formatting in the configured tree; review the resulting diff so a formatting pass does not conceal functional changes. Do not update every dependency solely to remove a warning without evaluating compatibility.

Pin and review any new integration. Do not publish setup credentials in screenshots, source examples, browser bundles or debug logs while diagnosing a package issue.

Migrations and persistent state

Every persistent schema/policy change belongs in a new versioned SQL migration. Released files are immutable. The starter uses its Management API runner and project-scoped checksum ledger, not Supabase CLI migration history. A CLI history command is not a drop-in repair for a missing installer receipt.

Installed maintenance commands

Run these from the configured application folder with its matching private .env, .kickstart and .secrets state:

• npm run kickstart:migrate -- --check inspects pending SQL without writing. npm run kickstart:migrate applies and verifies pending migrations for the configured hosted project. It does not rerun project provisioning or change Auth/email origins.
• npm run kickstart:recover -- --check reports which installation evidence is present or missing. It has no apply, adopt, reset or recreate mode, and cannot recover plaintext secrets.
• npm run kickstart:catalog -- --project PROJECT_REF --account acct_EXISTING_ACCOUNT --mode test --check checks an installed catalog. Remove --check only after reviewing the report to update names/descriptions in that same mode. It preserves product/price IDs, amounts, subscriptions, workers, receipts and the opposite mode; it does not create promotions.
• To disable optional modules, set their availability in config/features.json and restart/rebuild. Follow the specific feature's removal guide before deleting code or stored data; there is no general feature-removal command.

These operations use the existing account/project/mode receipts. A successful read-only check does not prove later write permissions. Never delete the receipts or switch targets to make a command pass.

Test changes against a dedicated hosted development/test project. Never reset a shared database to make migrations look clean. Preserve retries and customer modifications; changes that narrow permissions need tests for current users, stale sessions and cross-workspace access. Plan compatibility between schema and deployed code before a rollout or rollback.

Safe diagnostics

Collect the smallest report that explains the failure. A useful private report looks like this synthetic example:

Source: template 0.0.1 source snapshot, customized notes branch
Runtime: Node version from node --version
Command: npm run kickstart:deploy -- --check
Stage: GitHub App repository authorization
Result: required check failed before provider writes
Expected: designated private repository visible to Vercel
Observed: account token reads work; App cannot see the selected repository
Last change: repository created with selected-repository App access
Next diagnostic: inspect that installation's repository selection
Secrets / customer payloads: omitted

Include the sanitized exact error, a safe request ID if provided, and whether a timed-out operation might have been accepted. Avoid whole .env files, cookies, authorization headers, token URLs, private SQL results or full provider response bodies. The installer withholds provider bodies for this reason. A request identifier helps correlation; it is not a reason to attach an entire customer record.

Inspect provider service status and the relevant request/deployment logs using your authorized account. For public ingress, redact query tokens and sensitive headers and use appropriate rate limits. The contact form's process-local backstop is not a global serverless quota.

Credential rotation and receipts

Separate setup credentials from runtime credentials. Supabase Management, GitHub and Vercel tokens stay on the setup machine. Resend, Stripe, optional OpenRouter and narrowly used Supabase secret keys are server/runtime dependencies as documented in the configuration reference.

Rotate in a controlled order: identify every consumer and its mode/target, create or obtain the authorized replacement through the provider, update the intended private configuration, validate read access, deploy/reconcile the affected consumer, confirm behavior, then revoke the old value. Some providers do not reveal a secret again; store it securely when issued. Never copy all setup values into Vercel to avoid tracking consumers.

Setup receipts bind provider account, project, mode and sometimes a credential fingerprint to progress. An incomplete bootstrap can reject a changed Resend key even if it belongs to the same account. Restore the matching state and reconcile the specific boundary instead of deleting the receipt. Generated key/resource IDs are recovery information, not fresh initial manual inputs.

Current schedules and quotas

Billing uses a named hosted cron schedule per installed mode, forma-billing-test or forma-billing-live, every five minutes to invoke guarded synchronization/recovery. The optional AI module uses forma-ai-recovery every minute to recover expired work. These are specific application mechanisms, not a general queue for arbitrary tasks.

Check schedule existence and recent outcome on the authorized hosted target without dumping secret-bearing invocation SQL. A schedule present in the catalog does not prove it ran successfully. For another module, add its own deliberate migration/configuration and retry semantics; do not overload billing or AI jobs.

Current API/MCP limits are 60 requests per credential per minute. AI uses the limits in its canonical config and a one-time workspace credit grant; subscription renewal does not create recurring AI credits. Provider budgets and limits are separate. Monitor actual usage in the provider account and update your product promises when you change supported behavior.

Data backups and setup state

Customer data and setup progress need different backups. A copy of Git source does not contain hosted database rows. A database backup does not reconstruct the original setup receipts, deployed environment, Stripe state or sent email.

Supabase's current backup documentation describes plan-dependent daily retention and optional point-in-time recovery. Confirm the selected project's actual backup availability in Database → Backups; do not assume the default new project includes a paid plan's retention. Database backups include Storage metadata, but not the file objects themselves. Retain an independently designed Storage-object backup for avatars if your recovery policy requires them. Database-backed logos follow the database backup, subject to its coverage and restore point.

Keep source/lockfile/migrations in your private source history; protect .env, .kickstart and .secrets in a separate encrypted, access-controlled recovery location. Check that a restore would recover the matching provider identities without leaking credentials. Store authorized database exports and objects according to your retention policy; this starter does not ship a complete backup automation system.

Rehearse recovery before promising it

Choose an authorized separate target and a recovery point, then follow the provider's current restore procedure for the actual plan. Establish expected downtime and acceptable data loss first. Validate table data, roles/RLS, Auth, Storage objects, subscriptions/webhooks, email origin, integration audiences and current runtime keys afterward. A restored database may describe external events that have since changed, so reconciliation is essential.

Do not run a destructive production restore as a tutorial experiment. This manual's authoring task did not access the project's backup plan or rehearse a provider restore. Backup availability, object coverage and end-to-end recovery remain deployment-specific evidence to record before launch.

Escalate with a concrete result

State what failed, what you expected, the source identifier, the sanitized result and the checks already attempted. Distinguish an access error, a confirmed rejected operation and an uncertain accepted operation. Keep the original state intact while investigating. When the fix changes code or instructions, rerun the checks that exercise that boundary and update the release record and affected guide together.