metaboost

Canonical linear DB migrations under infra/k8s/base/ops/source/database/linear-migrations, ops bundles, env keys, and runners. Use when adding or changing SQL migrations, K8s DB bootstrap, or scripts/database in this repo.

When an E2E test verifies a specific element, pass it to the capture helper so the step screenshot is taken with that element vertically centered.

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

Distributed tracing and OTLP export patterns. Use when adding trace context, log correlation, or Observability env — after Metaboost adopts a shared observability package.

When you finish a plan file in active/, automatically move it to completed/. If it's the last plan in its set, move the whole set. Use when completing any plan under .llm/plans/active/.

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

Common patterns for the Metaboost HTTP API (Express)

When adding or changing files under infra/k8s/ or sync targets for k8s, know what Argo CD syncs and remind the user to push to Git so the cluster can sync.

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

Prevents workspace package omissions in Docker images by verifying runtime-stage COPY coverage for every app dependency. Use when editing Dockerfiles, debugging ERR_MODULE_NOT_FOUND in containers, or changing workspace dependencies.

Documentation file naming for the Metaboost repo. Use when creating or modifying docs, README, or markdown.

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.

Maintain E2E spec order for full reports and respect parameter order for specified runs.

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

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.

Keeps tools/generate-data seeders and docs in sync when main or management DB schema or ORM entities change. Use when adding or changing tables/entities in packages/orm, packages/management-orm, or infra database migrations.

gh CLI and GitHub issue/PR workflow for agents. Use when referencing PRs, issues, or Dependabot updates.

Global patterns for the Metaboost repo (API + Next.js app). Use when starting work in the repo or when applying repo-wide code quality, structure, or plan conventions.

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

Kustomize bases vs overlays under infra/k8s — no sibling ../ bases in component kustomizations; shared bundles (e.g. product-membership) composed in alpha/common with matching remote ?ref=. Use when editing infra/k8s kustomization.yaml, alpha overlays, or GitOps remote resources.

Regenerate committed linear baseline .sql.gz artifacts whenever app/management linear SQL migrations change.

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.

Post-save navigation via ROUTES to the canonical management-web list for one-row create/edit pages; exceptions for invite links and password-only updates.

Modal overflow, ModalDialogContent actions row, right-aligned wrapping footers (web + management-web).

Detect and surface missing-native-binary errors (e.g. @rollup/rollup-darwin-arm64) without mutating node_modules or the lockfile.

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.

Where and how to save LLM plan files locally. Use when creating, saving, or completing plan sets (e.g. multi-phase plans). Aligns with Podverse monorepo convention.

Standardizes 429 handling with RateLimitModal and retry-after UX. Use when handling API errors that may return 429 (rate limited) responses.

End implementation responses with scoped make-based screenshot report commands for web and management-web verification.

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

Enforces URL query param handling across pages. Use when adding or updating list/detail filters, pagination, or sorting. Keep URLs clean by not auto-inserting params; only preserve params when the user navigates with them, and remove defaults from the URL.

Keep apps/*/lib/startup/validation.ts push order aligned with apps/*/.env.example section order when practical. Use when adding env vars, startup validation entries, or editing validation.ts.

Add or update Storybook stories when adding or changing UI components in packages/ui. Use when creating or modifying components in @metaboost/ui.

Enforces import ordering so styles (CSS/SCSS module) imports are last. Use when editing React components or pages in .tsx/.jsx files, or when the user mentions import order or style imports.

Design tokens, themes, mixins, and reset live in @metaboost/ui. Apps consume them via @metaboost/ui/styles/* — do not duplicate tokens in app SCSS.

Ensures client-side time displays use formatDateTimeReadable for localized, readable timestamps. Use when rendering dates/times in the UI or when the user mentions time formatting or local timezone display.

Extract or deduplicate UI between apps/web and apps/management-web via packages/ui; thin app wrappers for Next and i18n.

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