premortem

Learned User Preferences

• Prefer native modular Next.js components over Framer/Unframer iframe embeds when rebuilding marketing or landing UI.
• Use existing assets under public/ (especially apps/web/public/logo/, public/static/*.png demo frames, and raster refs in apps/web/public/landing/) when implementing designs; compare against modular components in apps/web/src/components/landing/.
• Verify MCP server connectivity with scripts/mcp/verify-all.ts when working with the project's MCP configuration.
• GitLab published findings must default to CDN logo plus clickable public site links (currently premortem.jstn.site) in the attribution footer, not plain text alone.
• Landing UI uses custom extracted CSS, not Tailwind/shadcn, for marketing and auth surfaces. Build with landing-native components and landing.css. shadcn/ui is installed under src/components/ui/ for optional future use but auth routes use landing tokens.
• For marketing, auth, and reviewer console (/app) UI work, reuse existing blocks and layouts as the design source of truth; apply the ui-ux-pro-max skill for UI/UX work.
• Consult .agents/rules/ (umbrella CORE-BEHAVIOR.md, MISSION.md, PREDICTION-POLICY.md, data-retention.md, failure-policy.md, and domain split files), docs/architecture/adr-0001-canonical-product-and-system-design.md, and .agents/skills/ when implementing product content or filling application gaps; structure /docs with Diátaxis (Tutorials, How-To Guides, Reference, Explanations). Marketing docs share app/docs/layout.tsx with a persistent sidebar; preserve docs nav scroll across page navigations. JSON schemas in .agents/schemas/. Do not reference .internal/ paths in public or tracked docs; .internal/ is gitignored.
• Agent skills are categorized under .agents/skills/ (behavior: stop-slop, humanizer; security: ai-security-arsenal; engineering: mattpocock/skills; llm-ops: promptfoo, langfuse, invariant; reference: awesome-ai-software-engineering). Cursor bridges mirror behavior and llm-ops skills under .cursor/skills/. Prompt regression gate: pnpm run eval:prompts.
• Avoid em dash punctuation (—) in Premortem application UI and copy; use colons, commas, periods, or hyphens instead. Do not mention external reference projects (e.g. go-mirofish, mirofish) in user-facing Premortem strings or docs; preserve Premortem brand identity.
• Keep .env.example minimal with no duplicate variables; group by concern and comment pooler vs direct URLs clearly.
• When updating README.md or SECURITY.md, follow reference structure and annotation style from agentfs-core README.md and Hyperkit SECURITY.md; use repo-local logos (public/logo/png/Premortem_abstract.png) in README branding tables and avoid broken third-party CDN badge URLs. Public onboarding copy should lead with hosted try at premortem.jstn.site/signup before local clone; keep GitHub presentation neutral in hero and Projects until provider coverage is production-ready (Projects defaults to GitLab).
• Prefer real runtime/API data over static mocks in /app and BFF routes; run pnpm run verify:env after updating .env.local to confirm configured (real GitLab + LLM) vs fixture mode; deprecated in-memory store.ts paths are not production targets.

Learned Workspace Facts

• pnpm monorepo (pnpm@9.12.0) with Turbo; primary web app at apps/web, local dev via pnpm run dev.
• Marketing landing page is composed from modular components in apps/web/src/components/landing/; app/page.tsx renders LandingPage directly. Raster mockups in apps/web/public/landing/; brand SVGs under apps/web/public/logo/. No Framer/Unframer; styles in landing.css with viewport scaling via landing-scale.tsx and mobile reflow in landing-responsive.css. Legacy Framer export at apps/web/src/vendor/premortem-landing/ is reference-only (excluded from tsconfig.json via src/vendor/**).
• Product mission, prediction policy, data retention, and failure handling: .agents/rules/MISSION.md, PREDICTION-POLICY.md, data-retention.md, failure-policy.md. Architecture context: docs/architecture/adr-0001-canonical-product-and-system-design.md.
• Marketing routes (/products, /solutions, /how-it-works, /privacy, /terms, /docs, /signup, /login and subpages) share marketing-page-layout.tsx or blocks/marketing-doc-layout.tsx; copy lives in src/content/marketing/; reusable blocks in src/components/landing/blocks/; URLs in src/lib/marketing-links.ts and src/lib/auth-links.ts.
• Premortem reviewer console lives at /app under route group app/(os)/; legacy /reviews redirects to /app. Implementation in src/components/premortem-os/ with shared os-* primitives; OS design tokens in design-system/premortem/MASTER.md (Tailwind-based, distinct from marketing landing.css). UI branding in src/lib/premortem-os/branding.ts; GitLab publish footers use packages/domain/src/branding.ts (renderPremortemPublishAttribution) with production CDN logo at https://premortem.jstn.site/logo/svg/premortem-mark.svg. Runtime data flows web BFF → apps/api → @premortem/orchestrator; semantic vocabulary centralized in @premortem/domain. Snapshot read model: AuditRunSnapshot from orchestrator. Business tier limits in @premortem/db entitlements (PLAN_LIMITS). Local dev fixture IDs: LOCAL_DEV_FIXTURE in domain (re-exported by @premortem/db). Legacy in-memory store.ts is deprecated for runtime paths. Continuous Audit toggle (continuousAuditEnabled, sidebar + dashboard) defaults to OFF: OFF = manual scans only; ON = ~90s idle rotation when no active run; turning OFF does not cancel in-flight audits. Stop all (POST /api/workspace/runtime/stop-all) disables continuous audit and cancels queued/running/paused runs so the operator can start manual scans; per-audit Resume applies to individually paused checkpointed runs. Integration providers sync Work Item Attributes as automated metadata/tags via workspace APIs. BFF POST /api/audits/run returns 202 with auditRunId (no 120s server poll); client tracks progress via audit refetch. API routes reject client organizationId that mismatches the session actor org (403). /app hard-locks only on 401; other load errors toast; fixture-mode banner when PREMORTEM_AUTH_DISABLED is active. Workflow canvas merges repository graph with Phoenix semantic spans (GET /api/audits/[id]/semantic-graph); node click opens inspect panel.
• MCP server definitions live in repo-root mcp.local.json (fallback mcp.json); Cursor does not automatically load this file—verify with scripts/mcp/verify-all.ts. Toolbox Postgres MCP runs via scripts/mcp/run-toolbox-postgres.sh and requires DATABASE_URL in .env.local. Phoenix MCP (Phoenix, Phoenix Docs in mcp.json) uses scripts/mcp/run-phoenix-mcp.sh and requires PHOENIX_API_KEY; runtime agent introspection uses the same @arizeai/phoenix-mcp package in @premortem/agent-builder. Hackathon alignment: docs/guides/phoenix-arize-track.md, pnpm run smoke:arize. Official GitLab MCP at gitlab.com/api/v4/mcp uses OAuth in Cursor; static PAT in env is not the supported auth path. GitLab OAuth for Supabase sign-in and /app workspace connect both use scopes read_user api read_repository (app/api/auth/[provider]/route.ts, gitlab-oauth.ts).
• Production smoke (pnpm run smoke:production-readiness) requires a GitLab Personal Access Token with classic api scope for issue publish (GITLAB_TOKEN or GITLAB_SMOKE_PUBLISH_TOKEN). Cursor MCP OAuth tokens and read_api-only PATs fail publish with 403 insufficient_scope; verify with pnpm run smoke:verify-gitlab-publish. Review-edit smoke (scripts/smoke/smoke-review-edit.ts) preserves synthesized issue titles and only patches whyItMatters / recommendedActionSummary.
• GitLab repository enable (POST /api/workspace/integrations/:id/repositories/enable) verifies with the selected integration token (not org-level fallback) and accepts read-only discovered repos without requiring issue-write access. Audit scans gate on assertAuditReadiness (LLM + GitLab read); publish gates on assertGitLabPublishReadiness (issue write/create). GitLab API calls use gitLabAuthHeaders (Bearer + PRIVATE-TOKEN) so OAuth tokens work on GitLab.com.
• Canonical stack (ADR §7): Next.js, Supabase Auth/Postgres/Storage, Prisma, TanStack Query, Sentry, PostHog, Stripe, GitLab, Neo4j graph store. LLM: Gemini 3 Flash Preview (gemini-3-flash-preview) primary when GEMINI_API_KEY set. Workflow canvas uses @xyflow/react with elkjs auto-layout. SDK wiring lives in packages/observability, packages/storage, packages/db, apps/web/src/lib/canonical/, and reviewer hooks in use-os-console-data.ts. When Phoenix tracing is enabled, Sentry initializes with skipOpenTelemetrySetup to avoid OTel conflicts. Verify env/SDK readiness with node scripts/canonical/verify-stack.mjs. Cursor MCP plugins for Sentry, PostHog, Stripe, and Prisma complement repo MCP config for ops and debugging.
• pnpm run build may fail on pre-existing dashboard type errors around AuditRunSnapshot in @premortem/orchestrator, independent of landing-page changes.
• pnpm run dev runs scripts/dev/run-local-stack.ts (db migrate, then API + web). Default ports: web :13000, API :18787 (overridable via PREMORTEM_WEB_PORT / PREMORTEM_API_PORT). Local OAuth: set NEXT_PUBLIC_APP_URL=http://127.0.0.1:13000 and match GitLab redirect URIs; do not mix localhost and 127.0.0.1 (breaks PKCE/state cookies; middleware canonicalizes loopback for auth/integration routes). Supabase OAuth handlers attach PKCE/session cookies via src/lib/supabase/route-handler.ts. Configured mode (.env.local has DATABASE_URL + GITLAB_TOKEN + LLM + Supabase keys per scripts/lib/configured-env.ts): real Supabase auth (user.id profileId), personal workspace onboarding, real GitLab ingest and LLM. Fixture mode when credentials missing: PREMORTEM_AUTH_DISABLED=1 + LOCAL_DEV_FIXTURE for smoke only. Repo-root .env.local is loaded via scripts/load-local-env.ts (also wired in apps/web/next.config.ts). pnpm run docker:up starts Neo4j and local Postgres via docker-compose.yml when using localhost database URLs. Default GitLab demo repo: GITLAB_EXTERNAL_PROJECT_ID=jstn-studio/meta-architect. Purge smoke audit rows with pnpm run db:reset-audits; run a configured-mode audit with pnpm run audit:local or from /app. Supabase free-tier Postgres: runtime DATABASE_URL uses transaction pooler port :6543 with pgbouncer=true; Prisma migrations use DIRECT_URL session pooler :5432 on the same .pooler.supabase.com host, not direct db.*.supabase.co.