@meadow-studio/platform 0.0.0-stage → 0.1.1

package/docs/PLATFORM_GUIDE.md

@@ -0,0 +1,423 @@
+# Meadow Platform Guide
+
+This is the current operating guide for developers and agents using or extending Meadow Platform.
+It explains what the platform is, how its parts fit together, what it can do today, and which
+responsibilities remain with each application.
+
+In the source repository, this project lives in `platform/` beside the independent, optional
+`design/` project. Each has its own dependencies and build. Apps install exact
+`@meadow-studio/platform` versions from the public npm registry.
+
+## Mission
+
+Meadow Platform is an app-production system for moving from an idea to a release-ready mobile
+application as quickly and repeatably as possible.
+
+It combines:
+
+- a CLI that creates and maintains standalone repositories with an app and companion website;
+- a pinned Angular and Capacitor foundation;
+- reusable runtime services and small infrastructure UI components;
+- integration setup and optional capability recipes;
+- pull-request CI, screenshot testing, native builds, diagnostics, and release gates; and
+- the conventions needed to apply that foundation consistently across many apps.
+
+The intended result is not a generic starter template. It is an evolving system that preserves
+proven app infrastructure so each new application can focus earlier on its unique product.
+
+```text
+Idea or existing app
+  ↓
+meadow new or meadow init
+  ↓
+Standalone release-oriented app repository
+  ↓
+Build app-owned product and design
+  ↓
+Add/configure only the capabilities the app needs
+  ↓
+Pull-request CI and visual review
+  ↓
+meadow doctor + meadow release-check
+  ↓
+Store preparation and release
+```
+
+The long-term measure of success is simple: each subsequent Meadow app should be faster to build and
+release than the previous one.
+
+## Mental model
+
+Meadow Platform has three cooperating parts.
+
+### The `meadow` CLI
+
+The CLI creates an ordinary standalone repository and automates repeatable development and release
+work. Generated files belong to the application and remain understandable without hidden framework
+machinery.
+
+Use the CLI to:
+
+- create and validate a new app;
+- adopt the Meadow control plane into a supported existing app without replacing app-owned work;
+- synchronize typed project intent into generated web, native, test, and package configuration;
+- add optional capabilities such as local data;
+- install app-owned service configuration;
+- generate native assets and signing guidance;
+- inspect readiness, synchronize versions, and run release checks; and
+- optionally create and push the app's GitHub repository.
+
+The complete command reference is in [CLI.md](CLI.md).
+
+### The `@meadow-studio/platform` runtime
+
+Every app consumes one pinned npm package. Its small public API provides stable Meadow-owned
+boundaries around runtime configuration, app metadata, analytics policy, purchases, and app-rating
+behavior. Third-party provider types should not spread through application code when a Meadow
+boundary exists.
+
+The package also ships the native app-rating plugin and an optional `@meadow-studio/platform/ui` entry point.
+
+### The generated application foundation
+
+Each app and its companion website share one repository with app-owned domain code, visual language, credentials, store
+records, and release history. The generated foundation currently uses:
+
+- Angular 22 with standalone components and strict TypeScript;
+- Capacitor 8 with generated iOS and Android projects;
+- a separate static `website/` project with home, support, privacy, and terms pages;
+- Node 24.15 and npm 11;
+- Vitest unit tests and coverage thresholds;
+- Playwright phone and tablet screenshot comparisons;
+- a repository-local app-development skill linked from `AGENTS.md`;
+- GitHub Actions for quality, web, visual, Android, and unsigned iOS builds; and
+- exact dependency versions and immutable GitHub Action revisions.
+
+Ionic and Meadow Design are not part of the foundation. Either may be adopted by an app as an explicit
+app-owned choice.
+
+## Ownership boundary
+
+Meadow Platform owns infrastructure that is useful across multiple applications:
+
+- the shared toolchain and repository structure;
+- provider-neutral runtime boundaries;
+- repeatable integration setup;
+- build, test, CI, diagnostics, and release guardrails;
+- small infrastructure-oriented UI; and
+- optional recipes proven by real apps.
+
+The application owns everything that makes the product distinct:
+
+- domain models, actions, rules, and terminology;
+- pages, navigation, visual design, and product UI;
+- analytics event names and the moments at which events are recorded;
+- the moment at which a rating request is appropriate;
+- purchase products, entitlement policy, pricing, and paywall copy;
+- database tables, validation, repositories, and deletion behavior;
+- Supabase schema, RLS, grants, storage policies, and backend lifecycle;
+- credentials, native service files, signing material, and store accounts; and
+- legal copy, privacy choices, store metadata, and final release decisions.
+
+Stay Light is a donor and evidence source, not the platform's architecture specification. 24h
+Pushups is the first POC consumer. New abstractions should continue to come from repeated real-app
+needs rather than hypothetical completeness.
+
+## Current capability map
+
+| Capability | Current behavior | Important boundary |
+| --- | --- | --- |
+| App creation | `meadow new` creates, installs, formats, builds, tests, generates native projects and visual baselines, initializes Git, and can create a GitHub repository. `meadow init` generates the same foundation inside an empty Git checkout while preserving its remote and history. | Product code and visual design remain app-owned. A clean checkout must contain only `.git`. |
+| Companion website | `meadow new` creates a static `website/` project in the same repository; `meadow init` adds it when absent and preserves an existing site. An optional base domain derives a subdomain URL, and `meadow sync` updates generated site metadata. The privacy draft pre-fills Meadow Development's publisher/contact details and explains the two Firebase consent choices. | Hosting, DNS, TLS, publication, app-specific data/events/retention/deletion details, and final legal review remain app-owned. Draft pages are marked `noindex`. |
+| Existing-app adoption | `meadow init` verifies Angular 22 and Capacitor 8, infers app/provider metadata, previews changes, installs the pinned platform, creates project configuration, and maintains marked agent and safety guidance. | It preserves existing source, scripts, CI, test configuration, and unmarked instructions; `meadow doctor` reports remaining foundation gaps. |
+| Typed project configuration | `meadow.config.json` v2 is the source of truth for identity, releases, targets, environments, links, capabilities, public provider identifiers, and analytics definitions. `meadow sync` generates dependent files and `meadow sync --check` detects drift. | Secrets and product behavior remain outside the config. Generated files are replaceable; app-owned files are not silently overwritten. |
+| Runtime configuration | `provideMeadowPlatform(...)` validates and freezes app identity, environment, links, and analytics allowlists. | Secrets never belong in runtime config committed to source. |
+| App information | `MeadowAppInfoService` returns platform, native version, and native build number behind Meadow types. | Web and unavailable native metadata return `null`, not invented values. |
+| Analytics | `MeadowAnalyticsService` persists explicit consent, requires a configured production environment, allowlists events/properties, and delivers native events through Firebase without exposing provider types. | The app owns its event catalogue, tracking moments, consent UI/copy, disclosures, and Firebase project. Web, development, and test delivery remain off. |
+| Crash reporting | `MeadowCrashReportingService` persists separate explicit consent and provides failure-safe handled-error and breadcrumb APIs over native Firebase Crashlytics. Generated native projects start collection off and eagerly enforce environment and consent state at startup. | The app owns consent UI/copy and decides which non-sensitive diagnostic context is appropriate. Final Firebase console and iOS symbol-upload verification remain release checks. |
+| App rating | `MeadowAppRatingService` calls the system store surface on native platforms with concurrency, version, cooldown, and rolling-year safeguards. | The app decides the meaningful success moment; Apple and Google decide whether a prompt appears. |
+| Infrastructure UI | `@meadow-studio/platform/ui` provides app-build information and privacy/support links with app-overridable labels and CSS variables. | It is not a design system; feature UI stays with the app or optional Meadow Design. |
+| Local data | `meadow add local-data` generates migrated SQLite, transactions, a typed document store, browser IndexedDB persistence, tests, and safety checks. Browser persistence and Android compilation are validated; a clean iOS simulator compile of this optional recipe remains pending. | Tables, domain mapping, data sensitivity decisions, and deletion/reset behavior remain app-owned. |
+| Local notifications | `meadow add notifications` pins and synchronizes the native provider. `MeadowNotificationService` exposes permission state, an explicit permission request, one-off and calendar schedules, replace/cancel/pending operations, Android channels, normalized failures, and tap actions. Web and disabled apps safely report the capability as unavailable. Clean generated Android and iOS simulator builds passed; on-device delivery remains app release verification. | The app owns permission explanation and trigger, copy, IDs, timing rules, channels, tap navigation, and analytics. Meadow never prompts as a scheduling side effect and uses inexact Android alarms by default. |
+| Firebase setup | The base app includes Analytics and Crashlytics dependencies; `meadow configure firebase` validates the files needed by enabled platforms, synchronizes native projects, installs Android build plugins, and registers `GoogleService-Info.plist` as an iOS app resource. `meadow doctor` checks dependencies, files, plugins, bundled resources, and opt-in defaults. | The app owns its Firebase project and must verify an event and test crash on a device before release. iOS dSYM upload configuration remains app-specific release setup. |
+| Purchases | Creation can add RevenueCat; `meadow configure revenuecat` validates public platform keys and records offering and entitlement identifiers. Generated builds load the ignored local keys, and `MeadowPurchaseService` provides products, live entitlement and premium state, purchase, restore, refresh, support ID, and normalized outcomes without exposing RevenueCat types. | The app owns its paywall UI and copy, product and package identifiers, pricing policy, entitlement policy, analytics, store catalog, and final sandbox/device verification. Web and unconfigured apps safely report the capability as unavailable. |
+| Supabase setup | Creation can add the client; configuration validates and records the URL and publishable key in an ignored local environment file. | The app must still create its client and own schema, RLS, grants, storage, auth UX, and database tests. Never use a service-role key in a client. |
+| Assets and metadata | CLI commands generate native assets and maintain support, privacy, terms, version, and build metadata. | Store listings and final legal content remain app-owned. |
+| Signing guidance | `meadow configure signing` creates app-local Android and iOS signing instructions. | It does not create certificates, profiles, keystores, passwords, or CI secrets. |
+| Diagnostics and release | `meadow doctor` explains missing or inconsistent setup; `meadow release-check` runs quality, visual, and selected native gates. | Passing technical checks does not publish the app or replace store review. |
+| Pull-request CI | Generated CI audits dependencies and runs formatting, linting, coverage-gated tests, app and website builds, screenshot comparison, Android build, and unsigned iOS build. Successful Android builds upload a downloadable debug APK; screenshot failures upload the report and receive a PR comment from a trusted follow-up workflow. | CI installs the exact public npm platform version with no Meadow package secret. Visual baselines are reviewed artifacts and are never silently updated. APKs and reports are Actions artifacts rather than externally hosted previews. |
+
+“Configured” in `meadow.config.json` means the CLI successfully installed or recorded the required
+setup inputs. It does not imply that an unfinished provider abstraction has become a complete
+product feature.
+
+## Standard app workflow
+
+### 1. Create the repository
+
+```sh
+meadow new my-app
+```
+
+Use the interactive questions for a one-off app or `--config`/`--yes` for repeatable creation. A
+normal creation produces a working web app, iOS and Android projects, a companion website, initial screenshots, CI, a
+release checklist, and an initial gitmoji commit.
+
+For a supported existing Angular 22 and Capacitor 8 repository, use the adoption path instead:
+
+```sh
+meadow init --dry-run
+meadow init
+```
+
+Review the plan first. Initialization installs the Meadow control plane conservatively, then uses
+`meadow doctor` to expose release-foundation work that cannot safely be inferred or merged.
+
+### 2. Build the smallest useful product
+
+Replace the generated home screen with the app's domain behavior. Keep the product model and UI in
+the app. Do not introduce optional infrastructure until the product demonstrates that it needs it.
+
+Treat `meadow.config.json` as project intent rather than editing generated native or TypeScript values
+in several places. After changing identity, releases, targets, environments, capabilities, links,
+provider identifiers, analytics definitions, or screenshot viewports, run:
+
+```sh
+meadow sync
+```
+
+Generated CI runs `meadow sync --check` to prevent drift. Credentials, service-role keys, signing
+material, and other secrets remain external.
+
+### 3. Add or configure capabilities
+
+Examples:
+
+```sh
+meadow add local-data
+meadow add notifications
+meadow configure firebase --google-services ... --google-service-info ...
+meadow configure revenuecat --ios-key ... --android-key ... --entitlement ... --offering ...
+meadow configure supabase --url ... --publishable-key ...
+meadow configure assets --source resources/icon.png
+meadow configure store --support-email ... --privacy-url ... --terms-url ...
+```
+
+Use [CLI.md](CLI.md) for the exact arguments and safety constraints.
+
+### 4. Keep every pull request releasable
+
+Run the same categories enforced by generated CI:
+
+```sh
+npm run check
+meadow sync --check
+npm run test:visual
+npm run build:android:ci
+npm run build:ios:ci
+```
+
+Screenshot differences are product changes. Review them rather than updating baselines merely to
+make CI green.
+
+### 5. Diagnose and prepare a release
+
+```sh
+meadow doctor
+meadow version patch production
+meadow release-check all
+```
+
+Then complete the app-owned release checklist, signing, privacy disclosures, store metadata, and
+submission. Meadow currently validates readiness; it does not upload releases to App Store Connect or
+Google Play.
+
+## Runtime usage
+
+Configure the runtime once in the Angular root providers:
+
+```ts
+import { ApplicationConfig } from '@angular/core';
+import { provideMeadowPlatform } from '@meadow-studio/platform';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideMeadowPlatform({
+      app: {
+        name: 'Example App',
+        id: 'app.meadow.example',
+        supportEmail: 'support@example.com',
+        privacyUrl: 'https://example.com/privacy',
+      },
+      environment: 'development',
+      analytics: {
+        enabled: true,
+        allowedEvents: ['item_created'],
+        allowedProperties: ['source'],
+      },
+      crashReporting: { enabled: true },
+      notifications: { enabled: true },
+    }),
+  ],
+};
+```
+
+The generated app already supplies this provider and maps development, device, and production
+builds to the matching environment. When RevenueCat is configured, it also maps public iOS and
+Android SDK keys from the ignored `.env.meadow.local` through a generated runtime asset. Those public
+client keys reach the compiled app by design; they do not belong in committed source.
+
+Use app-owned wrappers for product semantics:
+
+```ts
+import { inject, Injectable } from '@angular/core';
+import { MeadowAnalyticsService } from '@meadow-studio/platform';
+
+@Injectable({ providedIn: 'root' })
+export class ExampleAnalytics {
+  private readonly analytics = inject(MeadowAnalyticsService);
+
+  itemCreated(source: string): void {
+    this.analytics.track('item_created', { source });
+  }
+}
+```
+
+This keeps event names in the app and provider behavior behind Meadow Platform. The app's consent UI
+applies the user's separate choices without importing Firebase:
+
+```ts
+await inject(MeadowAnalyticsService).setConsent(analyticsGranted);
+await inject(MeadowCrashReportingService).setConsent(crashReportingGranted);
+```
+
+Both services expose `consentStatus()` and `isEnabled()`. Consent is persisted per app, provider
+errors are contained, and collection remains disabled outside a configured production environment.
+`MeadowCrashReportingService.recordError(...)` records handled failures and `log(...)` adds short
+diagnostic breadcrumbs after consent.
+
+Apps build their own paywall over the provider-neutral purchase service:
+
+```ts
+import { inject } from '@angular/core';
+import { MeadowPurchaseService } from '@meadow-studio/platform';
+
+const purchases = inject(MeadowPurchaseService);
+
+await purchases.loadProducts();
+const products = purchases.products();
+const outcome = await purchases.purchase(products[0].packageId);
+const premium = purchases.isPremium();
+```
+
+`products`, `entitlement`, `isPremium`, `status`, and `error` are Angular signals. Purchase and
+restore return a small Meadow-owned outcome union: `completed`, `cancelled`, `pending`, or `failed`.
+The service listens for customer-info changes and also exposes `refreshEntitlement()`, `restore()`,
+and `getSupportId()`. The app decides how those outcomes look and what premium means to the
+product. Before release, verify the real offering, products, purchase, cancellation/pending flow,
+restore, and entitlement state in both store sandboxes.
+
+Apps also own the notification experience while Meadow owns safe native delivery:
+
+```ts
+import { Injectable, inject } from '@angular/core';
+import { MeadowNotificationService } from '@meadow-studio/platform';
+
+@Injectable({ providedIn: 'root' })
+export class ReminderService {
+  private readonly notifications = inject(MeadowNotificationService);
+
+  // Call from an app-owned button after explaining why reminders are useful.
+  async enableDailyReminder() {
+    if (await this.notifications.requestPermission() !== 'granted') return;
+    return this.notifications.replace({
+      id: 1001,
+      title: 'Time to move',
+      body: 'Do a few pushups.',
+      schedule: { on: { hour: 18, minute: 0 }, repeats: true },
+      channel: { id: 'motivation', name: 'Motivation', importance: 'high' },
+      data: { route: '/today' },
+    });
+  }
+}
+```
+
+`permission`, `status`, and `lastAction` are Angular signals. `initialize()` and scheduling only
+check permission; only `requestPermission()` can display the native prompt. Scheduling returns
+`scheduled`, `permission_required`, `unavailable`, or a normalized `failed` outcome. Meadow uses
+inexact Android alarms so ordinary reminders do not require exact-alarm access. If exact timing
+becomes a real product requirement, it remains a separate native and release-policy decision.
+
+Infrastructure UI is imported separately:
+
+```ts
+import { MeadowAppBuildComponent, MeadowAppLinksComponent } from '@meadow-studio/platform/ui';
+```
+
+Apps may use these small components or their exported pure model functions without adopting a
+shared visual design.
+
+## Local-data model
+
+Local data is generated into the app rather than exposed as a broad package API. This lets the app
+own its schema while Meadow owns the repetitive native and browser setup.
+
+```text
+Page or domain service
+  ↓
+App-owned repository and validation
+  ↓
+Generated LocalDocumentStore or LocalDatabase
+  ↓
+SQLite on iOS/Android; SQLite persisted in IndexedDB on web
+```
+
+The recipe pins `jeep-sqlite` 2.8.0 with `sql.js` 1.11.0 because newer WebAssembly binaries are not
+ABI-compatible with that web component. Do not loosen this version without a real browser
+write/read/reload test. See [CLI.md](CLI.md#add-local-data) for migration and data-safety rules.
+
+## Release-ready means a foundation, not a finished product
+
+Meadow shortens the path to release by making the technical foundation reproducible. A generated app
+is ready for product development and has the machinery needed to become releasable. It is not ready
+for a store merely because generation succeeded.
+
+Every app must still provide and verify:
+
+- its useful product behavior and accessible UI;
+- real icons, screenshots, descriptions, and store records;
+- a published companion website with final support, privacy, and terms pages;
+- consent behavior and privacy disclosures matching actual data collection;
+- production service projects, policies, products, and public client keys;
+- signing identities and protected release credentials;
+- account/data deletion behavior where applicable; and
+- device testing and final human review.
+
+## Using or extending Meadow Platform as an agent
+
+Before changing an app or the platform:
+
+1. Identify the pinned `@meadow-studio/platform` version and read that version's documentation.
+2. Read `meadow.config.json` and run `meadow doctor` in a generated app before guessing about setup.
+3. Use an existing Meadow command, service, or recipe when it covers the need.
+4. Keep provider details, product policy, and domain behavior on the correct side of the ownership
+   boundary.
+5. Validate changes in a real consuming app when they affect generated or native behavior.
+6. After meaningful platform work, apply the documentation check in
+   `agent/skills/meadow-platform-documentation/SKILL.md`.
+
+Do not infer a capability from an installed dependency alone. Use this guide and the implementation
+to distinguish a complete Meadow capability from setup that is intentionally awaiting a proven app
+need.
+
+## Documentation map
+
+- [Project brief](PROJECT_BRIEF.md): purpose, architecture, constraints, and product direction.
+- [CLI guide](CLI.md): exact creation, configuration, diagnostics, CI, and release commands.
+- [POC findings](POC_FINDINGS.md): evidence and conclusions from Stay Light and 24h Pushups.
+- [Platform release guide](RELEASING.md): versioning and distributing `@meadow-studio/platform` itself.
+- [v0.1 path](V0.1_PATH.md): historical POC plan and dated implementation record.
+- Generated app documentation: app-local CI, release, signing, and local-data instructions.
+
+Source code remains authoritative for exact types and behavior. Documentation preserves the mental
+model and constraints that code alone cannot communicate efficiently.

package/docs/POC_FINDINGS.md

@@ -0,0 +1,218 @@
+# POC application findings
+
+These findings were gathered from the current Stay Light and 24h Pushups applications on 2026-09-14. They are implementation evidence, not permanent architecture requirements.
+
+## Application roles
+
+- Stay Light is close to its initial release. It is the donor and reference implementation for infrastructure that has survived real release work.
+- 24h Pushups is an early concept prototype. It is the first POC consumer of Meadow Platform, and integration should preserve fast product iteration.
+- Both applications currently live as workspaces in the same `website` repository. Meadow Platform remains a separate repository and package.
+
+## Shared proven baseline
+
+Both applications use:
+
+- Angular 20.3 with standalone application configuration;
+- Capacitor 7;
+- TypeScript 5.9;
+- RxJS 7.8;
+- Node 22 and npm 10–11; and
+- Angular dependency injection for application services.
+
+24h Pushups also uses Ionic 9. Stay Light does not currently depend on Ionic, so Ionic must not be a platform runtime requirement for the first POC.
+
+This supports an Angular-first platform API with Capacitor peer dependencies. A framework-neutral abstraction is not yet justified by a real consumer.
+
+## Stay Light donor inventory
+
+### App configuration
+
+Stay Light uses Angular `ApplicationConfig` plus build-time Angular environment replacement. Its environment fields mix generic concerns with app-specific development modes and RevenueCat public SDK keys.
+
+Generic candidates:
+
+- production/deployment identity;
+- app name, ID, support URL/email, and privacy URL; and
+- externally supplied provider configuration.
+
+Leave in Stay Light:
+
+- mock-photo behavior;
+- visual-test mode;
+- branch-preview routing;
+- Stay Light product identifiers; and
+- developer scenarios.
+
+### App information
+
+Stay Light reads the native version with `@capacitor/app` directly inside its About page and falls back to a hard-coded version on web. This is a small, clear first extraction target.
+
+The platform should own the mapping from Capacitor results to:
+
+```ts
+interface MeadowAppInfo {
+  version: string | null;
+  buildNumber: string | null;
+  platform: 'ios' | 'android' | 'web';
+}
+```
+
+Build ref, commit SHA, build timestamp, release channel, About-page links, and UI remain app concerns until reuse is proven.
+
+### Analytics and consent
+
+Stay Light already has a single Angular analytics service wrapping Firebase. It provides valuable proven behavior:
+
+- production-only collection;
+- explicit opt-in persisted locally;
+- native-only event delivery;
+- allowlisted events and properties;
+- property sanitization;
+- safe no-op behavior; and
+- provider failures that never interrupt product flows.
+
+The event union and property schema are entirely Stay Light-specific. Meadow Platform should provide a typed generic mechanism that lets each app own its event catalogue. Consent storage currently uses Stay Light-specific keys and coordinates analytics with crash reporting, so consent orchestration should not be copied into the first POC.
+
+### Purchases and entitlements
+
+Stay Light's purchase implementation is mature but large: purchase access, entitlement evaluation, payment flow, and consent together exceed 1,300 lines before UI tests and components.
+
+Reusable candidates include:
+
+- RevenueCat configuration by native platform;
+- product loading;
+- normalized product metadata;
+- purchase outcome/error categories;
+- restore purchases;
+- customer-info refresh/listening;
+- entitlement verification; and
+- resilience during provider or network failures.
+
+Stay Light-specific concerns include:
+
+- monthly versus lifetime product taxonomy;
+- unlimited-review terminology;
+- product identifiers;
+- payment-modal behavior and copy;
+- developer payment simulations;
+- subscription upgrade rules;
+- analytics funnel events; and
+- entitlement persistence in Stay Light's database service.
+
+Purchases should therefore be designed as its own vertical slice. Moving the existing services wholesale would preserve too much product policy and expose RevenueCat types.
+
+### Purchase capability conclusion — 2026-09-18
+
+The implemented Meadow boundary follows that evidence: it owns native key selection, RevenueCat
+initialization, offering product loading, normalized product and entitlement state, live customer
+updates, purchase/restore, support identifiers, and a small outcome/error model. RevenueCat types
+do not cross the public API. The app still owns its product identifiers and taxonomy, paywall,
+copy, upgrade rules, analytics, persistence decisions, and entitlement meaning.
+
+The capability was verified through platform unit tests, a packed clean consumer, generated
+RevenueCat configuration, and clean Android and iOS simulator compilation. A real app must still
+exercise store sandbox transactions with its own catalog and public SDK keys before release.
+
+### App ratings
+
+Stay Light uses the system-owned App Store and Play Store review surfaces rather than a custom rating modal. Its reusable safeguards are:
+
+- native-only availability with a safe web no-op;
+- one in-flight request at a time;
+- no repeated request for the same app version;
+- a 120-day cooldown;
+- no more than two attempts in a rolling year;
+- persistence only after the native store accepts the request; and
+- failures that never interrupt the product flow.
+
+Stay Light's swipe count, active-day threshold, and premium-purchase trigger are product policy and remain app-owned. The native plugin implementation and frequency safeguards are generic platform infrastructure.
+
+## 24h Pushups consumer inventory
+
+24h Pushups currently has:
+
+- a small standalone Angular/Ionic bootstrap;
+- one environment field (`production`);
+- a generated Android project;
+- no generated iOS project yet;
+- local-only persistence behind app-owned repositories;
+- local notifications behind an app-owned service;
+- no analytics provider, crash reporting, or purchases;
+- Meadow Platform app information and provider-neutral analytics foundations; and
+- an app-owned rating qualification based on completed pushups and winning days.
+
+Its local persistence, pushup calculations, progression, notifications, UI primitives, and domain actions are product logic. They should stay in the app.
+
+Potential future analytics events are visible—intro completed, pushups logged, level changed, notifications enabled. The first provider-neutral foundation now records the app-owned `pushups_logged` action behind a disabled transport, allowing the API to be exercised without introducing Firebase/native/privacy setup during concept exploration.
+
+## First POC boundary
+
+Add only:
+
+```ts
+provideMeadowPlatform({
+  app: {
+    name: '24h Pushups',
+    id: 'app.pushups24h'
+  },
+  environment: 'development'
+});
+```
+
+and a Meadow-owned app-information service for use in Settings.
+
+The first POC uses a local file dependency and separately verifies the publishable files with `npm pack --dry-run`. This keeps the feedback loop local while checking the same package contents a registry would receive.
+
+## Explicit POC exclusions
+
+- analytics and Firebase configuration;
+- privacy/diagnostics consent UI;
+- RevenueCat and premium behavior;
+- notification abstraction;
+- persistence abstraction;
+- Meadow Design migration;
+- iOS project generation;
+- GitHub Packages publishing; and
+- release automation.
+
+Each exclusion can become a later slice when the app reaches the point where that infrastructure is genuinely needed.
+
+App ratings were added after the initial POC boundary was proven. The shared capability remains separate from Meadow Design: the stores own the rating interface, Meadow Platform owns native delivery and frequency safeguards, and each app owns the moment at which it asks.
+
+## Local-notification capability evidence — 2026-10-06
+
+24h Pushups proves the reusable reminder lifecycle: permission is checked before scheduling,
+permission is requested only from an explicit app action, an Android channel is created, existing
+IDs can be replaced, and one-off or daily reminders carry app-owned navigation data. Stay Light's
+review reminder independently proves explicit permission timing, failure containment, and warm or
+cold tap navigation, while its photo-aware eligibility and custom alarm behavior are product
+specific and were not generalized.
+
+`meadow add notifications` therefore installs the pinned Capacitor provider and enables a Meadow-owned
+runtime boundary. `MeadowNotificationService` owns permission state, scheduling mechanics,
+replace/cancel/pending operations, Android channel adaptation, provider error containment, and tap
+actions. Each app still owns permission copy, IDs, message copy, timing policy, channel names, tap
+routing, and analytics. Scheduling never triggers the permission prompt, and Android uses inexact
+alarms by default to avoid introducing special-alarm access for ordinary reminders.
+Capacitor Local Notifications 8.3 [requests display permission during scheduling and defaults
+Android notifications to exact alarms](https://capacitorjs.com/docs/apis/local-notifications).
+Meadow checks display permission first and sets `isExactNotification: false` on each scheduled
+notification to preserve the app's explicit permission moment and avoid a surprise exact-alarm
+settings screen. A clean generated app passed its checks and compiled Android and iOS simulator
+targets with this optional capability installed; device delivery and tap behavior remain app release
+verification.
+
+## Local-data recipe evidence — 2026-09-16
+
+The later CLI work revisited persistence as an opt-in app foundation rather than adding storage to
+the original package API.
+
+- 24h Pushups proves the app-owned repository boundary, typed domain mapping, validation on read,
+  and immutable migrations.
+- Nyttebjerggaard proves `@capacitor-community/sqlite` on the shared Capacitor 8 baseline.
+- Stay Light proves the value of queued writes, recovery, and deeper database lifecycle handling,
+  but those behaviors remain too specific to generalize from one mature app.
+
+`meadow add local-data` therefore generates only the shared setup: native and browser SQLite,
+parameterized operations, transactions, sequential migrations, a typed document store, and data
+safety checks. Each app continues to own its tables, domain models, decoders, and repositories.