@meadow-studio/platform 0.0.0-stage → 0.1.1

package/dist/ui/app-links.component.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-links.component.js","sourceRoot":"","sources":["../../src/ui/app-links.component.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EACL,8BAA8B,EAC9B,cAAc,GAEf,MAAM,sBAAsB,CAAC;;;;IAUpB,+BAIC;IACC,YACF;IAAA,oBAAI;;;IALF,wDAAkB;;IAIlB,cACF;IADE,8CACF;;;IARJ,8BAAqC;IACnC,sGAQC;IACH,oBAAM;;;;IATJ,cAQC;IARD,cAAA,cAAO,CAQN;;AAfT,2EAA2E;AA4C3E,MAAM,OAAO,uBAAuB;IACjB,MAAM,GAAG,MAAM,CAAC,sBAAsB,CAAC,CAAC;IAEhD,SAAS,GAAG,KAAK,CAAC,iBAAiB;kFAAC,CAAC;IACrC,YAAY,GAAG,KAAK,CAAC,8BAA8B,CAAC,OAAO;qFAAC,CAAC;IAC7D,YAAY,GAAG,KAAK,CAAC,8BAA8B,CAAC,OAAO;qFAAC,CAAC;IAC7D,UAAU,GAAG,KAAK,CAA4B,SAAS;mFAAC,CAAC;IACzD,YAAY,GAAG,KAAK,CAA4B,SAAS;qFAAC,CAAC;IAEjD,KAAK,GAAG,QAAQ,CAAC,GAAG,EAAE;QACvC,MAAM,MAAM,GAAwB;YAClC,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE;YAC5B,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE;SAC7B,CAAC;QACF,OAAO,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE;YAC7C,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE;YAC7B,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE;SAClC,CAAC,CAAC;IACL,CAAC;8EAAC,CAAC;iHAlBQ,uBAAuB;6DAAvB,uBAAuB;YAvChC,sFAAsB;;YAAtB,6CAYC;;;iFA2BQ,uBAAuB;cA3CnC,SAAS;2BACE,kBAAkB,cAChB,IAAI,YACN;;;;;;;;;;;;;;GAcT;;kFA0BU,uBAAuB"}

package/dist/ui/app-links.model.d.ts

@@ -0,0 +1,18 @@
+import type { MeadowAppConfig } from '../platform.js';
+export type MeadowAppLinkKind = 'privacy' | 'support';
+export interface MeadowAppLink {
+    readonly kind: MeadowAppLinkKind;
+    readonly label: string;
+    readonly href: string;
+}
+export interface MeadowAppLinkLabels {
+    readonly privacy: string;
+    readonly support: string;
+}
+export interface MeadowAppLinkOverrides {
+    readonly privacyUrl?: string | null;
+    readonly supportEmail?: string | null;
+}
+export declare const DEFAULT_MEADOW_APP_LINK_LABELS: Readonly<MeadowAppLinkLabels>;
+export declare function meadowAppLinks(app: Readonly<MeadowAppConfig>, labels?: Readonly<MeadowAppLinkLabels>, overrides?: Readonly<MeadowAppLinkOverrides>): readonly Readonly<MeadowAppLink>[];
+//# sourceMappingURL=app-links.model.d.ts.map

package/dist/ui/app-links.model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-links.model.d.ts","sourceRoot":"","sources":["../../src/ui/app-links.model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,SAAS,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED,eAAO,MAAM,8BAA8B,EAAE,QAAQ,CAAC,mBAAmB,CAGvE,CAAC;AAEH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,QAAQ,CAAC,eAAe,CAAC,EAC9B,MAAM,GAAE,QAAQ,CAAC,mBAAmB,CAAkC,EACtE,SAAS,GAAE,QAAQ,CAAC,sBAAsB,CAAM,GAC/C,SAAS,QAAQ,CAAC,aAAa,CAAC,EAAE,CAcpC"}

package/dist/ui/app-links.model.js

@@ -0,0 +1,17 @@
+export const DEFAULT_MEADOW_APP_LINK_LABELS = Object.freeze({
+    privacy: 'Privacy',
+    support: 'Contact support',
+});
+export function meadowAppLinks(app, labels = DEFAULT_MEADOW_APP_LINK_LABELS, overrides = {}) {
+    const privacyUrl = overrides.privacyUrl === undefined ? app.privacyUrl : overrides.privacyUrl;
+    const supportEmail = overrides.supportEmail === undefined ? app.supportEmail : overrides.supportEmail;
+    const links = [];
+    if (privacyUrl && /^https?:\/\//i.test(privacyUrl)) {
+        links.push({ kind: 'privacy', label: labels.privacy, href: privacyUrl });
+    }
+    if (supportEmail && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(supportEmail)) {
+        links.push({ kind: 'support', label: labels.support, href: `mailto:${supportEmail}` });
+    }
+    return Object.freeze(links.map((link) => Object.freeze(link)));
+}
+//# sourceMappingURL=app-links.model.js.map

package/dist/ui/app-links.model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-links.model.js","sourceRoot":"","sources":["../../src/ui/app-links.model.ts"],"names":[],"mappings":"AAoBA,MAAM,CAAC,MAAM,8BAA8B,GAAkC,MAAM,CAAC,MAAM,CAAC;IACzF,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,iBAAiB;CAC3B,CAAC,CAAC;AAEH,MAAM,UAAU,cAAc,CAC5B,GAA8B,EAC9B,SAAwC,8BAA8B,EACtE,YAA8C,EAAE;IAEhD,MAAM,UAAU,GAAG,SAAS,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC;IAC9F,MAAM,YAAY,GAChB,SAAS,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,YAAY,CAAC;IACnF,MAAM,KAAK,GAAoB,EAAE,CAAC;IAElC,IAAI,UAAU,IAAI,eAAe,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QACnD,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,YAAY,IAAI,4BAA4B,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;QACpE,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,UAAU,YAAY,EAAE,EAAE,CAAC,CAAC;IACzF,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACjE,CAAC"}

package/dist/ui/index.d.ts

@@ -0,0 +1,5 @@
+export { MeadowAppBuildComponent } from './app-build.component.js';
+export { DEFAULT_MEADOW_APP_BUILD_LABELS, formatMeadowAppBuild, type MeadowAppBuildLabels, } from './app-build.model.js';
+export { MeadowAppLinksComponent } from './app-links.component.js';
+export { DEFAULT_MEADOW_APP_LINK_LABELS, meadowAppLinks, type MeadowAppLink, type MeadowAppLinkKind, type MeadowAppLinkLabels, type MeadowAppLinkOverrides, } from './app-links.model.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/ui/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EACL,+BAA+B,EAC/B,oBAAoB,EACpB,KAAK,oBAAoB,GAC1B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EACL,8BAA8B,EAC9B,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,GAC5B,MAAM,sBAAsB,CAAC"}

package/dist/ui/index.js

@@ -0,0 +1,5 @@
+export { MeadowAppBuildComponent } from './app-build.component.js';
+export { DEFAULT_MEADOW_APP_BUILD_LABELS, formatMeadowAppBuild, } from './app-build.model.js';
+export { MeadowAppLinksComponent } from './app-links.component.js';
+export { DEFAULT_MEADOW_APP_LINK_LABELS, meadowAppLinks, } from './app-links.model.js';
+//# sourceMappingURL=index.js.map

package/dist/ui/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EACL,+BAA+B,EAC/B,oBAAoB,GAErB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EACL,8BAA8B,EAC9B,cAAc,GAKf,MAAM,sBAAsB,CAAC"}

package/docs/CLI.md

@@ -0,0 +1,389 @@
+# Meadow CLI
+
+The Meadow CLI turns an app idea into a validated standalone repository with the repetitive mobile
+foundation already installed. It intentionally generates ordinary project files: the app owns its
+product code and design, while Meadow supplies the common toolchain, integrations, checks, and release
+guardrails.
+
+Read the [Meadow Platform guide](PLATFORM_GUIDE.md) first for the overall idea-to-release system,
+capability map, ownership boundaries, and current maturity limits.
+
+## Requirements
+
+- Node 24.15.x and npm 11
+- Git
+- Xcode for local iOS builds
+- Android Studio/JDK 21 for local Android builds
+- GitHub CLI only when creating a remote repository
+
+Install `@meadow-studio/platform` from npm at an exact version, then run `meadow` through its package
+binary. During platform development, a local file installation is supported.
+
+## Create an app
+
+```sh
+meadow new <name>
+```
+
+The app stays at the repository root. A second, static project is created in `website/` with home,
+support, privacy, and terms pages. Both projects share one Git repository. To plan a subdomain, pass
+`--website-base-domain meadow-development.app`; Flockbook then gets
+`https://flockbook.meadow-development.app/` in `links.websiteUrl`. The domain is optional until it
+is purchased. DNS, hosting, TLS, and publication are separate setup steps.
+
+The privacy page starts with Meadow Development's publisher and support details, and reusable
+explanations of the separately consented Firebase Analytics and Crashlytics services. New app
+configs use `oestbalmer@gmail.com` as the support email unless another address is supplied.
+The page is a draft with `noindex`: review the final app's data, events, retention, deletion,
+website hosting, publisher address, and effective date before publication. The generated page
+must match actual native behavior and store privacy disclosures.
+
+Interactive creation asks for the display name, bundle/application ID, optional website base domain,
+store links, supported orientation and device classes, and whether the app needs RevenueCat or Supabase. Firebase
+Analytics and Crashlytics are part of the base stack but remain unconfigured until app-owned native
+configuration is supplied.
+
+Useful options:
+
+```text
+--yes                       Use safe defaults without prompts
+--config <file>             Read answers or a full Meadow config from JSON
+--website-base-domain <name>  Derive the companion subdomain from the app slug
+--directory <path>          Choose the parent directory
+--github                    Create and push a GitHub repository
+--github-owner <owner>      Choose a GitHub account or organization
+--visibility <value>        private, internal, or public; defaults to private
+--no-install                Write files without installing or validating
+--no-git                    Do not create the local Git repository
+--skip-visual-baselines     Defer baseline screenshot generation
+```
+
+Creation is atomic. The final directory appears only after dependency installation, formatting,
+native-project generation, unit tests, linting, and production/device builds succeed. A normal
+creation also installs Chromium and creates initial phone and tablet screenshot baselines. The
+repository receives an initial gitmoji commit unless `--no-git` is used.
+
+Each generated repository includes:
+
+- Angular 22 standalone application code and strict TypeScript;
+- a separate, dependency-free `website/` project with editable home, support, privacy, and terms pages;
+- Capacitor 8 iOS and Android projects;
+- Firebase Analytics and Crashlytics native dependencies;
+- optional RevenueCat and Supabase client dependencies;
+- provider-neutral `@meadow-studio/platform` runtime APIs;
+- Vitest unit tests with 80% line/function/statement and 70% branch thresholds;
+- Playwright phone and tablet screenshot tests;
+- formatting, linting, web, device, Android, and unsigned iOS build commands;
+- GitHub Actions for pull-request verification and manual visual-baseline generation;
+- exact dependency versions, immutable GitHub Action hashes, and dependency auditing;
+- release, CI, signing, and store checklists;
+- an editable root-level `PRODUCT_BRIEF.md` template for audience, core jobs, product rules,
+  experience, the first usable flow, and deferred ideas;
+- an `inspiration/README.md` where app owners can add visual references with notes about what to
+  borrow for specific screens or flows;
+- an `AGENTS.md` pointer to the capability guide bundled with the app's pinned platform version and
+  a repository-local `.agents/skills/meadow-app-development/SKILL.md` for normal app development; and
+- a `.gitignore` that excludes generated web/native output, local configuration, signing files,
+  and test reports.
+
+The template deliberately does not include Ionic or Meadow Design. An app may adopt either as an
+app-owned decision, but neither is part of the Meadow foundation.
+
+## Adopt an existing app
+
+In a newly created, empty Git checkout, `meadow init` generates the full app and companion website
+directly in that repository. The checkout must contain only `.git`; Meadow preserves its Git history
+and remote and does not create or push another repository. The display name defaults to the checkout
+directory name, and the command prompts for app details unless `--yes` is supplied. Use
+`--website-base-domain meadow-development.app` to plan the app's subdomain. `--dry-run` lists the
+files without writing. With installation enabled, initialization runs the same app, native, and
+visual validation as `meadow new`. Build tools may print paths inside a temporary `.meadow-init-*`
+directory during validation; Meadow moves the completed project into the existing checkout only after
+every step succeeds.
+
+The generated project includes Firebase Analytics and Crashlytics dependencies by default. Both
+native collection switches start disabled; production collection requires each service's separate
+consent and app-owned Firebase configuration. The app must provide the actual consent interface.
+
+For an existing Angular and Capacitor application, `init` follows the adoption flow below.
+
+Use `init` inside an existing Angular 22 and Capacitor 8 application:
+
+```sh
+meadow init --dry-run
+meadow init
+```
+
+Initialization also creates `website/` if it is missing. If the app already has a website project
+in that directory, Meadow leaves it intact. `--dry-run` includes the website plan without writing.
+It also adds `PRODUCT_BRIEF.md` when missing and preserves an existing brief.
+It creates `inspiration/README.md` when missing and preserves existing reference notes and images.
+The optional `--website-base-domain` sets a missing planned website URL; it does not replace an
+existing URL in `meadow.config.json`.
+
+The command inspects `package.json`, `angular.json`, and the Capacitor configuration before making
+changes. It infers the display name, application ID, package version, and whether RevenueCat or
+Supabase is already in use. Unsupported Angular or Capacitor major versions are rejected before any
+file is written. Interactive mode asks for a missing website base domain and whether to add optional
+providers that are not already detectable; use `--config` to override other inferred metadata.
+
+The adoption plan can:
+
+- create `meadow.config.json` when it is missing, while preserving an existing valid configuration;
+- install a pinned `@meadow-studio/platform` and missing shared provider dependencies;
+- add only missing Meadow-owned package scripts, leaving existing scripts unchanged;
+- create `.nvmrc` only when the app does not already have one;
+- add or refresh marked Meadow sections in `AGENTS.md`, `.gitignore`, and `.env.example`;
+- add the app-development skill when it is missing, preserving any existing copy; and
+- install dependencies and finish by printing the complete `meadow doctor` result.
+
+Useful options:
+
+```text
+--dry-run                   Print the complete plan without writing or installing
+--yes                       Accept inferred values without prompts
+--config <file>             Override inferred answers with JSON
+--website-base-domain <name>  Set a missing planned companion website URL
+--directory <path>          Initialize a project outside the current directory
+--platform-spec <value>     Install or intentionally replace the platform dependency spec
+--no-install                Update files without running npm install
+```
+
+Managed sections are delimited by `meadow-platform:start` and `meadow-platform:end`. Re-running `init`
+updates only those sections and is otherwise idempotent. A malformed or half-present marker pair is
+treated as an error rather than risking app-owned content.
+
+`init` establishes the Meadow control plane; it does not blindly replace application code, existing
+CI, test configuration, Angular or Capacitor versions, or app-specific architecture. `meadow doctor`
+reports missing pieces of the complete release-oriented foundation so they can be adopted
+deliberately. Ionic and other app-owned dependencies are retained and reported without becoming
+Meadow Platform dependencies.
+
+## Synchronize typed configuration
+
+`meadow.config.json` version 2 is the source of truth for durable application and release intent:
+
+- display name, slug, and separate iOS and Android identifiers;
+- enabled platforms, device classes, and orientation;
+- semantic version, build number, and release channel;
+- development, test, and production runtime behavior;
+- support, privacy, terms, website, App Store, and Play Store links;
+- enabled Firebase, RevenueCat, Supabase, local-data, and local-notification capabilities;
+- RevenueCat entitlement, offering, and product identifiers;
+- the Supabase project reference and names of variables containing public client configuration;
+- analytics events and typed property definitions; and
+- CI screenshot viewports.
+
+For a Meadow-generated companion site, `meadow sync` also updates `website/site.config.json` with
+the app name, description, planned URL, and support email. Website page content and styling stay
+app-owned. Use `npm run website:start` to preview the site and `npm run website:check` to build it.
+Draft support and legal content must be replaced and `noindex` removed before publication.
+
+After editing the config, run:
+
+```sh
+meadow sync
+```
+
+Synchronization updates:
+
+- `package.json` release metadata, platform/capability dependencies, and Meadow scripts;
+- `capacitor.config.ts` app identity and generated environment files;
+- app-owned generated runtime configuration and typed analytics APIs under `src/app/meadow/`;
+- the local-service configuration generator used before development and production builds;
+- Playwright viewport projects;
+- Android application ID, display name, orientation, version, and build metadata when present; and
+- iOS bundle ID, display name, orientation, version, and build metadata when present.
+
+When dependencies change, the command runs `npm install`; use `--no-install` when a separate process
+will update the lockfile. Generated TypeScript and configuration files carry a warning header. Meadow
+will not replace a conflicting unmarked file at one of those paths.
+
+Use the read-only form locally and in CI:
+
+```sh
+meadow sync --check
+```
+
+It exits unsuccessfully when normalized configuration, dependencies, generated source, native
+metadata, or testing viewports have drifted. `meadow doctor` includes the same drift check.
+
+Analytics definitions generate an app-owned, compile-time API. For example:
+
+```json
+{
+  "analytics": {
+    "events": {
+      "pushups_logged": {
+        "properties": {
+          "reps": { "type": "integer", "required": true },
+          "source": {
+            "type": "string",
+            "required": false,
+            "values": ["home", "notification"]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+This produces an `AppAnalytics` wrapper that rejects unknown events, missing required properties,
+wrong value types, and invalid enumerated strings during TypeScript compilation.
+
+Never put credentials, service-role keys, signing material, or other secrets in
+`meadow.config.json`. Supabase and RevenueCat configuration records variable names and public product
+identifiers; actual environment values remain external. Generated apps run `npm run
+services:config` before serving or building. It reads local public client values and writes the
+ignored `public/meadow-service-config.js` runtime asset.
+
+## Add local notifications
+
+From a generated app, add native local notifications with:
+
+```sh
+meadow add notifications
+```
+
+The recipe pins `@capacitor/local-notifications`, updates `meadow.config.json`, installs the package,
+synchronizes each existing native project, updates the generated runtime and release checklist,
+and runs the app checks before marking the capability configured. If installation or native sync
+is interrupted, rerun the same command; an enabled but unconfigured capability is resumable.
+
+The runtime does not request permission during initialization or scheduling. The app explains the
+benefit and calls `MeadowNotificationService.requestPermission()` from a user action. The app also
+owns notification IDs, copy, schedule rules, Android channels, tap navigation, and analytics.
+Meadow owns provider adaptation, permission state, one-off and recurring calendar scheduling,
+replace/cancel/pending operations, tap events, safe web behavior, and normalized failures.
+
+Android schedules are inexact by default. Do not add exact-alarm permission unless a concrete app
+requires exact timing and its store/disclosure implications have been reviewed. Before release,
+test grant and denial behavior, scheduling, replacement, cancellation, the Android channel, and
+tap navigation on both enabled platforms.
+
+## Add local data
+
+From a generated app, add the proven local-data foundation with:
+
+```sh
+meadow add local-data
+```
+
+The recipe installs pinned SQLite dependencies, synchronizes both native projects, and generates:
+
+- a Meadow-owned `LocalDatabase` wrapper with parameterized queries, writes, and transactions;
+- sequential, immutable database migrations;
+- a small typed JSON document store for settings and other simple records;
+- an example unit test and app-repository guidance;
+- the SQLite WebAssembly runtime for browser development; and
+- Android backup exclusions plus local-data release checks.
+
+iOS and Android use native SQLite. Browser development uses the same SQLite engine persisted in
+IndexedDB, avoiding a second storage behavior just for web previews. Application-specific tables,
+models, validation, and repositories stay in the app rather than `@meadow-studio/platform`.
+
+If installation or validation is interrupted, rerun the same command. Meadow records the incomplete
+recipe, preserves any generated file you changed while fixing the problem, fills in missing files,
+and validates the capability again before marking it configured.
+
+After adding a migration, update `services.localData.databaseVersion` in `meadow.config.json` to match
+the final migration. Never edit a migration that has shipped. Before release, test both a fresh
+database and an upgrade from the previous app version, verify deletion/reset behavior, and review
+the generated SQLCipher export-compliance checklist item.
+
+## Configure integrations
+
+Run configuration commands from the generated app directory:
+
+```sh
+meadow configure firebase \
+  --google-services /path/to/google-services.json \
+  --google-service-info /path/to/GoogleService-Info.plist
+
+meadow configure revenuecat \
+  --ios-key <public-sdk-key> \
+  --android-key <public-sdk-key> \
+  --entitlement <id> \
+  --offering <id>
+
+meadow configure supabase \
+  --url https://<project>.supabase.co \
+  --publishable-key <publishable-key>
+
+meadow configure assets --source /path/to/icon.png
+meadow configure signing
+meadow configure store --support-email <email> --support-url <url> \
+  --privacy-url <url> --terms-url <url> --website-url <url> \
+  --apple-app-id <id> --app-store-url <url> --play-store-url <url>
+meadow configure github --owner <owner> --visibility private
+```
+
+RevenueCat and Supabase client values go in the ignored `.env.meadow.local`. RevenueCat configuration
+requires a public key only for each enabled native platform, validates the `appl_`, `goog_`, or
+`test_` key prefix, installs the pinned SDK, synchronizes Capacitor, and records the app-owned
+offering and entitlement identifiers. Builds convert those keys into the ignored runtime asset;
+`MeadowPurchaseService` then owns initialization, product loading, entitlement state, purchase,
+restore, and provider-error normalization.
+
+The Supabase command rejects service-role and secret keys; release readiness still requires
+explicit grants, row-level security, storage policies, and database tests. Firebase configuration
+is required only for the enabled native platforms. The command validates and copies those
+app-owned files, synchronizes Capacitor, installs the Android build plugins, registers the iOS
+configuration file as an app resource, and keeps Analytics and Crashlytics collection off at the
+native layer until the user grants consent. Firebase files are never added to the platform
+package.
+
+The application owns the consent screen and copy. Apply the resulting choices through
+`MeadowAnalyticsService.setConsent(...)` and `MeadowCrashReportingService.setConsent(...)`. Choices are
+persisted separately. Development and test environments remain disabled even when a stored
+production consent choice exists.
+
+## Diagnose and release
+
+```sh
+meadow doctor
+meadow doctor --json
+meadow version patch test
+meadow release-check all
+```
+
+`meadow doctor` checks the pinned stack, required files and scripts, native projects, Meadow-generated
+website pages, the local-data
+runtime when enabled, Firebase dependencies, native opt-in defaults, the bundled iOS Firebase
+resource, RevenueCat dependency, platform keys and catalog identifiers, local-notification
+dependency and native synchronization, visual baselines, and integration state. `meadow version`
+increments or sets the semantic app version, increments the build
+number, and synchronizes web, Android, and iOS metadata.
+
+`meadow release-check` turns missing native projects, baselines, or enabled-service configuration into
+failures and then runs the complete quality, visual, and selected native build gates. Production
+also requires a website URL plus support, privacy, and terms information.
+
+## Pull-request CI
+
+Every generated pull request runs four independent jobs:
+
+1. formatting, linting, dependency audit, coverage-gated unit tests, production app web build,
+   and companion website build;
+2. deterministic Playwright screenshot comparisons at phone and tablet sizes;
+3. Android debug compilation on Linux with JDK 21; and
+4. an unsigned iOS simulator build on macOS.
+
+Successful Android jobs upload `android-debug-apk`, a downloadable debug APK in the Actions run.
+The visual job uploads `playwright-report` with the HTML report and screenshot results. Playwright
+also adds GitHub test annotations; a separate trusted workflow comments on a PR when screenshot
+comparisons fail, naming the failures and linking to the downloadable report. This reports failures
+without requiring a preview host or a custom token for inline image attachments.
+
+CI installs the exact public `@meadow-studio/platform` version from npm using the committed lockfile. No
+Meadow package secret or source-repository access is needed, including for fork pull requests. The
+version must be published before a default `meadow init` install can run.
+
+CI never updates screenshots implicitly. The visual comparison and baseline workflow both use the
+same pinned macOS runner family as the local Meadow development environment. Use the manual **Generate
+visual baselines** workflow to produce candidates, inspect the artifact, then commit intentional
+changes. Generated visual test commands select an available local port for their Angular server, so
+an unrelated process on Angular's default port 4200 does not block initialization or local screenshot
+tests. Playwright never reuses an existing server for these checks.
+When Playwright is invoked directly, its generated configuration defaults to port 4400.