podverse

Just-in-time phase workflow for the Podverse mobile master plan. Use when the operator asks what to work on next in the mobile master plan, to plan or detail the next mobile phase, to create deferred detail docs and COPY-PASTA sets, or to implement a mobile master-plan phase.

Cross-platform theme AND visual parity for apps/mobile — same theme IDs and design tokens as web, RN ThemeProvider, uit pref, and web-referenced screen layouts. Use when adding mobile styling, ThemeProvider, theme selector, design token imports, or building any mobile screen that has a web counterpart.

FOSS vs playstore Android/iOS product flavors — FCM vs UnifiedPush, non-FOSS dependency register, defer full implementation to Track 20.

Expo SDK 52 as a standalone install under apps/mobile — own lockfile, file: shared packages, Metro. Use when mobile npm install, prebuild, pod install, mobile:dev fails, or when telling the operator how to run expo install (never bare root npx expo).

abcmemory checklist for mobile work — when to update .cursor/ rules/skills vs .llm/plans; abcremember vocabulary; links mobile-master-plan-phasing.

Offline-first mobile data layer — SQLite/Drizzle repositories, background sync, storage boundaries. Use when adding or changing apps/mobile data fetching, local persistence, queue/history/add-by-RSS storage, or sync.

After React Native mobile UI changes, instruct the operator to run npm mobile E2E scripts and open failures.json + per-slot/per-flow HTML reports under .artifacts/mobile-e2e-reports/latest/. Read those reports when diagnosing failures. Not Playwright or web make e2e_* targets.

Prefer fastest Maestro wait timeouts via shared TIMEOUT_* ladder; use when writing or editing apps/mobile/e2e YAML flows.

End implementation responses with scoped verification commands — web/management-web make screenshot reports, or mobile npm Maestro slot reports. Use after feature work so the operator can review results in HTML reports.

After Next.js, React, or shared UI changes, instruct the operator to run a targeted make E2E screenshot report and where to review it.

Investigate and decide on npm audit vulnerabilities—fix vs. allowlist pattern with shared gate utility

Use @podverse/ui ResourceTableWithFilter and related wrappers for management-web CRUD list pages (actions, permissions, delete confirm).

Prefer shared UI components from @podverse/ui over app-local one-off components or page-specific SCSS wrappers when behavior is generic.

Common patterns and examples for the podverse-web Next.js application

Design tokens, themes, mixins, and font-faces live in @podverse/ui. Apps must consume them via @podverse/ui/styles/* or the repo-relative packages/ui paths used in this monorepo. Do not duplicate tokens in app SCSS.

Tier A NodeNext .js specifiers vs Tier B Next.js src — follow repo boundaries when editing imports.

Map web playback policy to NativePlaybackBridge and podverse-media-engine — playback-core, queue/auto-queue parity, seamless video reparenting, background Now Playing. Do not use react-native-track-player.

Scope parallel Cursor sessions per mobile master-plan Track using git-worktree-sibling — which tracks can run concurrently vs must stay sequential (native vs RN UI).

Create decomposed, parallelizable execution plans with copy-pasta prompts for multi-agent workflows. Use when planning large migrations, refactoring tasks, or any work that can benefit from parallel execution across multiple agents. Every COPY-PASTA prompt must recommend a Cursor model.

Common patterns for Kubernetes manifests in infra/k8s. Use when editing or adding K8s manifests, changing deployment config, adding env vars to ConfigMaps, or working with ArgoCD/Kustomize/SOPS.

Author Podverse linear SQL migrations as strict greenfield-only forward chains—no upgrade/idempotency clutter unless a prior file in the same chain requires it.

Per-job env validation and config patterns for the workers app. Use when adding or changing worker commands, touching workers startup validation, or documenting worker env vars.

E2E seed and fixture id_text values must fit nano_id_v2 (9–15 chars). Use when adding or renaming IDs in seed scripts, seedConstants, demo links, or E2E fixtures that insert into id_text columns.

When layout, functionality, or conditions change in apps/web or apps/management-web, add or update the corresponding E2E (Playwright) test so page behavior stays covered.

Create and use Podverse git worktrees in sibling directories named podverse_<branch_slug> (underscores). Use when starting feature work, moving WIP off the main checkout, or opening the correct worktree path for a branch.

TypeORM v1 patterns for @podverse/orm — DataSource lifecycle, find options, services, linear SQL migrations

User vocabulary abcmemory and abcremember — where Cursor guidance lives and how to persist new instructions. Use when the user says abcmemory or abcremember.

Keep monorepo build order dependency-safe and keep build-order docs in sync when build orchestration changes.

Common patterns for the podverse-api Express application

Keeps bundle size in mind when adding dependencies, changing helper packages, or modifying the web app. Use when adding npm deps, touching @podverse/helpers*, introducing heavy UI, or working on client-side code in apps/web.

Never use the second argument to CSS var() in SCSS/CSS or inline styles; no nested var fallbacks.

Documentation file naming conventions for the Podverse monorepo. Use when creating or modifying documentation files, README files, or any markdown documentation.

Env vars with code fallbacks must show the default in .env.example and K8s env files. Use when adding or editing env vars that have fallback values in code.

Env file value formatting — double quotes for Node/Docker .env; unquoted values for K8s source/*.env. Use when adding or editing .env, .env.example, or env templates.

Three-pillar env layout — Observability, Integrations, Extensions — plus config.extensions.* and extension sidecar keys. Use when adding extension toggles, Prometheus env, integrations ConfigMaps, or Extensions section in app env files.

Built-in web integrations via @podverse/integrations-web and podverse-integrations-config. Use when adding Cloudflare or other front-end integrations, runtime-config JSON, or sidecar env for integrations.

Keeps Lighthouse env handling aligned with apps/api and apps/web startup validation. Use when changing Lighthouse env loading, .env.api/.env.web examples, or app validation requirements.

Repository source of truth for AI editor guidance is under .cursor, .cursorrules, and .cursorignore. Use when adding, editing, or deleting skills, rules, .cursorrules, or .cursorignore.

Log directory (LOG_DIR) behavior across the monorepo. Use when adding or changing log directory behavior, LOG_DIR env, or file logging in any app or package.

Common patterns for the podverse-management-api Express application