This repository has been archived on 2026-11-17. You can view files and clone it, but cannot push or open issues or pull requests.
gitgram-ai/SINGLE_SOURCE_PLAN.md

85 KiB
Raw Permalink Blame History

gitgram-ai Single Source Plan (v1)

Last updated: 2026-06-21

The Mission

Git is 20 years old. GitHub is a web UI bolted on top. Neither was built for AI agents generating 35 PRs a day, social-first development, or deterministic workflow restore.

GitGram is the social layer for GitHub repositories. Every repository can become a social account with posts, reels, stories, team photos, product videos, screenshots, followers, and publishing workflows. GitGram uses GitHub APIs and webhooks; it does not replace Git hosting, repository permissions, object storage, refs, packfiles, or the Git wire protocol.

AITM is deterministic workflow time travel for AI coding. It captures and restores agent actions, context, messages, tool calls, and checkpoints. It does not claim to implement or replace Git. The separate Rust Git Forge product owns the future Rust Git implementation and self-hostable forge boundary.

See INTEGRATION_PLAN.md for how the 8 cloned external repos get merged into the actual product source trees.

Launch operations note (2026-05-09):

  • The canonical launch contract is now the manual single-host runbook in docs/runbook.md.
  • Historical references in this file to Vercel, Railway, or unfinished GitHub deploy workflows should be treated as planning notes, not launch instructions.

Reference intake note (2026-05-12):

  • docs/can be fork.md is the maintained reference-clone inventory for external upstream repos under external/.
  • Launch-critical external reference adoption is complete; this file remains the canonical execution plan.

1) Purpose

This document is the canonical execution plan for v1. It merges:

  • Product/architecture decisions from NORTH_STAR_PRD_ARCHITECTURE_V1.md
  • Delivery sequencing from PLAN.md

If any document conflicts with this one, this plan wins for implementation order.

2) Product Scope (Locked)

Products:

  • gitgram: repository-first social network for developers (posts, reels, stories, comments, reactions, follows, trending).
  • aitimemachine (AITM): deterministic restore and timeline system for AI coding workflows.

Out of scope for v1:

  • Enterprise SSO/SAML hardening beyond scaffolding.
  • Autonomous research/oracle workflows as primary UX.
  • Private repo ingest without explicit legal and security controls.

3) Architecture and Policy Decisions (Locked)

  1. Source of truth:
  • Backend DB + object storage are authoritative.
  • Local .aitimemachine/ is cache/offline buffer only.
  1. Storage model:
  • blobs, trees, checkpoints, precomputed diffs, plus linked messages, tool_calls, contexts.
  1. Capture model per AI action:
  • before_action checkpoint.
  • tool call metadata + initiating message link.
  • after_action checkpoint.
  • diff generation/classification.
  • optional async indexing/embeddings.
  1. Privacy and training:
  • Training export is opt-in per workspace/org.
  • Default is operational capture only.
  • Redaction required before export.
  1. Security minimums:
  • Tenant isolation.
  • Scoped auth and per-project authorization.
  • Encryption at rest/in transit.
  • Audit logs for restore/export/delete.
  • Retention + hard-delete workflows.
  • PII/secret redaction before training export.

4) Current State (As of 2026-03-17)

  • Both products are fully implemented, compiled, tested, and production-ready at the code level.
  • All core features verified end-to-end (see Section 4a and 4b below).
  • Payment provider migrated from Stripe to Polar.sh (Stripe unavailable in Turkey).
  • Only deployment/infrastructure work remains for launch.

Completed (prior to 2026-03-02):

  • Route duplication removed in Gitgram.
  • Socket service migration completed.
  • Logging standardized with Winston.
  • API response helper foundation added in AITM.
  • Disk-full handling added in AITM ContentStore writes.
  • MCP rate limiting added.
  • Abuse detection moved to Redis-backed store (with fallback).
  • AITM backend URL alignment fixes completed.
  • TypeScript strict mode confirmed in both backends.

Completed (2026-03-02 to 2026-03-09):

Rebranding & Core Fixes:

  • AITM rebranded from legacy "gitmind" references across CLI, API server, extensions.
  • CLI modularized from monolithic cli-v2.ts into per-command files under src/cli/.
  • MCP server consolidated from 3 separate packages into single unified package.
  • AITM API server error responses standardized via wrapErrorMessage() middleware.

Test Coverage (1130+ tests, all passing):

  • AITM Core: 520/520 (35 suites) — CLI commands, smart-restore, core engine.
  • AITM API Server: 538/538 + 19 skip (45 suites) — all integration/service tests.
  • AITM VS Code Extension: 62/62.
  • Gitgram Web: 72/72 (7 suites) — auth, post, user, component tests.
  • Test infrastructure: fixed supertest/listen mock conflict, fixed error format across 18 test files.

Security Hardening:

  • Advertisement endpoints: added rate limiting, UUID validation, ad-exists check before tracking.
  • Advertisement creation: added input validation (URL, budget, type, dates, content length).
  • Repository claim: added GitHub ownership verification via Octokit permissions check.
  • Webhook signature: fixed timing-unsafe comparison to use crypto.timingSafeEqual.
  • Gitgram auth already uses httpOnly cookies (JWT primary method).
  • AITM OAuth: CSRF state tokens verified in SSO tests.

Type Safety:

  • AITM API server db export: fixed root cause any → NeonHttpDatabase<typeof schema> (eliminated ~30 implicit any errors).
  • Fixed 21 explicit any types in AITM services (retention, webhookDelivery, sessionManager, data-pipeline).
  • Fixed any types in Gitgram paymentService, aitmService, mobile storeService, messages, notifications.
  • All type checks pass with zero errors across all products.

Bug Fixes:

  • Mobile store: fixed call to non-existent getProducts() → getItems().
  • Mobile create post: replaced stubbed console.log handler with real postService.createPost.
  • Docker: fixed postgres version, port mappings, added missing env vars to AITM Dockerfile.
  • Removed dead code (unused mock.ts service file).

CI/CD (already in place):

  • 7 GitHub Actions workflows: ci.yml, tests.yml, integration-tests.yml, smoke-tests.yml, migrations.yml, verify-production-db.yml, openapi-validation.yml.
  • .env.example files for all products (root + per-package).

Completed (2026-03-17):

Payment Migration:

  • Stripe → Polar.sh across entire codebase (backend, frontend, mobile, docs).
  • @polar-sh/sdk@0.46.4 replaces stripe package.
  • Webhook verification uses validateEvent from @polar-sh/sdk/webhooks (Standard Webhooks spec).
  • Prisma schema: stripeCustomerId/stripeSubscriptionId → polarCustomerId/polarSubscriptionId.
  • Env vars: POLAR_ACCESS_TOKEN, POLAR_WEBHOOK_SECRET, POLAR_PREMIUM_PRODUCT_ID, POLAR_CREATOR_PRODUCT_ID, POLAR_MODE.

Completed (2026-05-12):

Payment Launch Alignment From Local Polar Source:

  • Added docs/polar-payment-setup.md using the cloned external/polar docs/source as the billing reference.
  • Confirmed service integrations should use Polar Organization Access Tokens, not OAuth/OpenID Connect.
  • Confirmed sandbox and production are isolated, and both Gitgram and AITM now honor POLAR_MODE.
  • AITM website billing routes now share a POLAR_MODE-aware Polar client instead of assuming one environment.
  • AITM API webhook verification now uses the SDK validator path and accepts both camelCase and snake_case event fields.
  • Gitgram backend webhook handling now uses the SDK validator flow through a CommonJS-compatible wrapper instead of ad hoc event-field assumptions.
  • AITM API env validation now includes POLAR_MODE, and remaining env examples were updated to document it.
  • npm run verify:launch is back to failing only on real missing secrets / placeholder values, not on Polar contract mismatches.
  • Launch tooling now supports env-specific operator files such as .env.gitgram.staging and .env.aitm-api.staging, so staging can use Polar sandbox values without conflicting with production POLAR_MODE=production.
  • Dedicated Neon databases now exist for Gitgram and AITM staging/production, and the root env files now contain real DB URLs plus generated app-owned secrets instead of placeholders.
  • Launch readiness is now split into core versus full integration gates, so deployability is no longer blocked on GitHub OAuth, Polar, Resend, or Sentry being configured on day zero.

Completed (2026-05-13):

Reference Clone Adoption Into Product Code:

  • Gitgram adopted external/repo2txt / external/repo-to-text into a shipped repo-to-text surface: backend export endpoint, short-path text page, raw text route, queryable export sizing, and discovery-surface Text / Raw links.
  • Gitgram web now has real Playwright coverage for the public repo-routing and repo-to-text surface: short-path /:owner/:repo, legacy github/.../text canonicalization, queryable export sizing, and repo-page → text-view navigation.
  • AITM MCP adopted external/a2a-js into a real A2A contract layer: canonical message/send handling with legacy tasks/send compatibility, protocol-versioned agent cards, spec-shaped task responses, and a repeatable scripts/a2a-smoke-test.sh verification path.
  • AITM MCP adopted the core external/pal-mcp-server patterns: real stable-vs-experimental tool policy, DISABLED_TOOLS shutdown support, aligned A2A/HTTP capability reporting, modular category-based tool registration instead of a monolithic src/index.ts, shared tool-annotation/output helpers, and declarative createToolRegistrar / defineTool registration helpers across the extracted tool modules.
  • AITM MCP adopted external/context7 transport-hardening patterns end to end: request-scoped HTTP context, stable request IDs exposed via X-Request-Id, structured parse/protocol error mapping, per-request logging across MCP/A2A/discovery/health routes, and nested request-ID propagation from A2A into the internal /mcp bridge.
  • Launch readiness now includes real CLI/MCP tarball inspection for npm publishability, not only npm pack --dry-run.

4a) AITM Feature Verification

All time-travel features verified as fully implemented:

  • Checkpoint creation: SHA256 content-addressable storage, lazy file reading.
  • Restore: Atomic 3-phase (delete/restore/context), auto-backup, rollback on failure.
  • Diff: 3 algorithms (Myers, Patience, Histogram), unified output.
  • Cat: View any file from any past checkpoint.
  • Storage: .aitimemachine/store/ loose objects + pack files + SQLite metadata.
  • Cloud Sync: Checkpoint/blob upload with quota, efficient dedup via hash checking.
  • Web UI: 6-step restore flow with preview, selective restore, undo.
  • VS Code Extension: List/create/restore/diff commands with autocomplete.
  • API Server: Full REST API for restore, manifest, blobs, batch operations.

4b) Gitgram Feature Verification

All 12 core social features verified as fully implemented (backend + frontend + database):

  • Auth (JWT + 2FA + GitHub/Google OAuth)
  • Posts (media, code snippets, mentions, hashtags)
  • Feed (algorithm-driven, personalized)
  • Comments (nested) & Likes
  • User Profiles (avatar, bio, settings)
  • Follow/Unfollow (with notifications, private account support)
  • GitHub Integration (real Octokit OAuth, repo sync, claiming)
  • Reels (video upload, comments, reactions)
  • Stories (24hr expiry, analytics, highlights)
  • Direct Messages (WebSocket real-time, group chat, read receipts)
  • Search (multi-type, advanced filters, relevance ranking)
  • Notifications (WebSocket real-time, push support)

4c) App-Code Stub / Placeholder Audit (2026-05-12)

This audit overrides earlier "fully implemented" wording for the specific surfaces below. These routes/components exist in product code, but some were empty shells, wired to wrong endpoints, or claimed features that are not backed by schema/routes yet.

Fixed in current remediation batches (2026-05-12)

  • gitgram/web/app/explore/trending/page.tsx
    • Replaced the empty shell with live trending posts, repos, and creators.
  • gitgram/web/services/storyService.ts and story pages under gitgram/web/app/story/**
    • Rewired to the real /api/v1/stories/* contract, including archive, analytics, replies, grouped feeds, and reaction summary behavior.
  • gitgram/web/app/story/highlights/** and gitgram/web/app/story/settings/page.tsx
    • Backed by real Prisma models and backend routes for named highlights plus allowReplies / hideFrom settings.
  • gitgram/web/app/reel/[id]/page.tsx, gitgram/web/app/reel/[id]/likes/page.tsx, and gitgram/web/app/reel/[id]/share/page.tsx
    • Normalized against real like/share contracts and the added GET /api/v1/reels/:id/likes backend route.
  • gitgram/web/app/reel/[id]/music/page.tsx
    • Replaced the fake /v1/reels/music call with real /api/v1/music/* search plus POST/DELETE /api/v1/reels/:id/music.
  • gitgram/web/app/reel/[id]/reactions/page.tsx and gitgram/mobile/app/reel/[id]/reactions.tsx
    • Made truthful by presenting reel likes instead of pretending typed reel reactions exist.
  • gitgram/backend/src/controllers/reelsController.ts, gitgram/backend/prisma/schema.prisma, and reel players on web/mobile
    • Reel effect and trim metadata now persist (effectId, trimStart, trimEnd, thumbnailTime) and the actual players honor those saved values instead of dropping them after publish.
  • gitgram/web/app/reel/[id]/effects/page.tsx
    • Replaced the fake effects endpoint call with a real view over the persisted reel effect metadata.
  • gitgram/web/app/reel/drafts/page.tsx
    • Removed the fake drafts endpoint assumption; the route now 404s instead of pretending reel drafts exist.
  • gitgram/mobile/app/reel/[id]/music.tsx, gitgram/mobile/app/(modals)/create-reel.tsx, and gitgram/mobile/app/create/reel.tsx
    • Real music selection now persists through the reel editor flow and saves through the reel music contract instead of fake success fallbacks.
  • gitgram/mobile/app/(modals)/create-reel.tsx, gitgram/mobile/app/create/reel.tsx, and gitgram/mobile/components/Reel/ReelTrimEditor.tsx
    • Replaced the disabled trim placeholder with real persisted trim controls shared across both mobile reel creation flows, and added real device-camera capture plus library import instead of library-only intake.
  • gitgram/mobile/app/map/explore.tsx
    • Replaced the broken map placeholder/no-op filter screen with a real project explorer backed by trending repositories, working language filters, optional location-aware map context, and an honest explanation that repository coordinates are not stored yet.
  • gitgram/web/app/reels/create/page.tsx
    • Removed non-persisted text/code overlay authoring, added real saved effect selection, and limited the UI to the reel fields the backend actually stores today.

Remaining web placeholder-backed surfaces

  • None currently identified in the active remediation scope.

Remaining mobile placeholder-backed surfaces

  • gitgram/mobile/app/reel/drafts.tsx
    • Now explicitly reports that reel drafts are unsupported rather than calling fake endpoints; real reel draft persistence still does not exist.

Immediate remediation batch — NEXT

  • Decide whether reel drafts are a real product requirement or should stay removed until backed by schema/routes.
  • Decide whether dedicated in-app reel recording is required beyond the now-working device camera capture path.
  • Decide whether text/code overlays on reels are a real persisted feature worth adding back later with schema/routes and rendering support.

Queued after current batch

  • Align any future reel overlay authoring with a persisted backend contract before surfacing it again on mobile.

4d) External Reference Adoption Status

This section summarizes launch-state reference adoption. No launch-critical reference adoption remains; future uses below are post-launch enhancements only if the product needs them.

Reference Product Status Active plan
repo2txt + repo-to-text Gitgram adopted No launch-critical follow-up remains. Revisit only if Gitgram adds compose/share/import workflows that need deeper repo-text embedding.
a2a-js AITM MCP adopted No launch-critical follow-up remains. Revisit only if AITM adds true A2A streaming or additional task lifecycle methods beyond the current blocking message/send bridge.
context7 AITM MCP adopted No launch-critical follow-up remains. Revisit only if AITM later needs deeper user/auth context propagation across downstream remote calls.
pal-mcp-server AITM MCP adopted No launch-critical follow-up remains. Revisit only if the MCP surface expands enough to justify automatic output-schema or capability-family generation.

5) Unified Delivery Sequence

The sequencing below resolves prior ambiguity:

  • Architecture/security gates remain mandatory.
  • Launch blockers are prioritized first because they prevent external usability.
  • Feature acceleration continues only after launch unblockers are complete.

Stage A: Launch Unblockers (Immediate) — IN PROGRESS

Goal: make both products externally usable.

Stage A readiness helpers now in repo:

  • docs/runbook.md remains the canonical manual launch path.
  • scripts/verify-launch-readiness.sh is the one-command gate for PM2, env file presence, secret contract validation, and AITM package publishability.
  • npm run verify:aitm-packages now goes beyond npm pack --dry-run: it also creates real CLI/MCP tarballs, unpacks them, and verifies published bin paths, packaged files, and the MCP dependency on @gitgram/timemachine.
  • npm run verify:a2a is the standards smoke for AITM's HTTP A2A card and message/send/tasks/send behavior.
  • npm run verify:launch runs the default core gate.
  • npm run verify:launch:full runs the stricter third-party integration gate.
  • scripts/deploy-launch.sh is the PM2-aligned scripted deploy path for Gitgram and AITM.
  • scripts/verify-public-launch.sh is the public-domain smoke pass for gitgram.app and AITM endpoints after DNS/nginx cutover.

A1. Publish AITM packages to npm — TODO

Both packages are fully configured for publishing. CLI must be published first (MCP depends on it).

Step-by-step publish plan:

  1. Pre-publish checks:

    cd aitimemachine && npm run build && npm test   # verify clean build + 520 tests pass
    cd mcp && npm run build                          # verify MCP builds
    
  2. Publish CLI first (@gitgram/timemachine@2.0.0):

    cd aitimemachine
    npm publish --access public
    
    • Package: @gitgram/timemachine
    • Bin: aitm, aitimemachine
    • Entry: lib/cli-v2.js
    • Files: lib/**/*, README.md, LICENSE
    • Hooks: prepack → build, prepublishOnly → build + test
  3. Verify CLI install:

    npx @gitgram/timemachine --version
    mkdir /tmp/aitm-test && cd /tmp/aitm-test
    npx @gitgram/timemachine init
    npx @gitgram/timemachine checkpoint --message "test"
    
  4. Publish MCP server (@gitgram/timemachine-mcp@2.0.0):

    cd aitimemachine/mcp
    npm publish --access public
    
    • Package: @gitgram/timemachine-mcp
    • Bin: aitm-mcp, aitm-mcp-client
    • Entry: dist/index.js
    • Depends on: @gitgram/timemachine@^2.0.0 (must be on npm first)
    • Files: dist/**/*, server.json, README.md, LICENSE
  5. Verify MCP install:

    npx @gitgram/timemachine-mcp --help
    
  6. Automated releases (future tags):

    • CI workflow (aitimemachine/.github/workflows/ci.yml) has a release job
    • Triggered on tag push matching v*
    • Uses GitHub secret NPM_TOKEN, passed to npm as NODE_AUTH_TOKEN
    • Current workflow publishes @gitgram/timemachine; MCP publish still requires a manual step until automation is aligned

npm cost: $0 (public packages are free)

A2. Configure production secrets — TODO

Secret Product Source
POLAR_ACCESS_TOKEN Gitgram polar.sh > Organization Settings > Access Tokens
POLAR_WEBHOOK_SECRET Gitgram polar.sh > Organization Settings > Webhooks
POLAR_PREMIUM_PRODUCT_ID Gitgram polar.sh > Products (create Premium $9.99/mo)
POLAR_CREATOR_PRODUCT_ID Gitgram polar.sh > Products (create Creator $19.99/mo)
POLAR_ACCESS_TOKEN AITM polar.sh (same or separate org)
GITHUB_CLIENT_ID Gitgram github.com/settings/developers
GITHUB_CLIENT_SECRET Gitgram github.com/settings/developers
GOOGLE_CLIENT_ID Gitgram console.cloud.google.com
GOOGLE_CLIENT_SECRET Gitgram console.cloud.google.com
CLERK_SECRET_KEY AITM dashboard.clerk.com
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY AITM dashboard.clerk.com
RESEND_API_KEY Both resend.com/api-keys
SENTRY_DSN (x2) Both sentry.io (one project per product)
DATABASE_URL Gitgram Neon console
DATABASE_URL AITM Neon console
REDIS_URL Gitgram Upstash console
AWS_ACCESS_KEY_ID Gitgram AWS IAM
AWS_SECRET_ACCESS_KEY Gitgram AWS IAM
JWT_SECRET Gitgram Generate: openssl rand -base64 48
JWT_REFRESH_SECRET Gitgram Generate: openssl rand -base64 48

A3. Deploy production baseline — TODO

  • Provision VPS (Hetzner CX32 recommended: 4 vCPU, 8 GB RAM, 80 GB NVMe).
  • Configure DNS records (A/AAAA) for gitgram.app, api.gitgram.app, aitm.gitgram.app.
  • TLS via Let's Encrypt / Caddy auto-HTTPS.
  • Build the services and start them under PM2 on the launch host.
  • Verify health endpoints and monitoring.

A4. Run E2E smoke tests — PARTIAL

  • AITM install/init/checkpoint/timeline path. DONE — covered by 520 CLI tests.
  • Gitgram public repo routing + repo-to-text path. DONE — covered by focused Playwright browser tests with mocked repository/export APIs.
  • Gitgram signup/oauth/post/comment/notification path. PARTIAL — auth/post/comment/notification mocks, selectors, and a focused Playwright spec now exist; backend notification detail routes and checkpoint-aware post flows are wired. Local next dev browser execution still blanks on protected client pages, so deployment-backed verification is still required before treating this as closed.

Exit criteria:

  • Both products are installable/deployable.
  • All health checks pass.
  • End-to-end flows complete without critical failure.

Stage B: Security Closure — COMPLETE

  1. JWT storage migration to httpOnly cookies in Gitgram. DONE
  2. OAuth callback URL hardening + redirect validation + CSRF state checks in AITM. DONE
  3. Complete API response helper migration in AITM for consistent error/success semantics. DONE
  4. Validate retention/delete/export audit paths in staging. DONE

Additional security work completed beyond original plan:

  • Advertisement tracking endpoints: rate limiting + ad-exists validation.
  • Repository claim: GitHub ownership verification via Octokit.
  • Webhook signature: timing-safe comparison fix.
  • Input validation added on advertisement and claim routes.

Exit criteria: ALL MET

Stage C: Reliability and Code Quality — COMPLETE

  1. Split AITM cli-v2.ts into modular command files. DONE
  2. Reduce any usage in AITM by priority surfaces. DONE
  3. Add Gitgram frontend unit/integration tests. DONE — 72 tests.
  4. Add Playwright critical-path E2E and CI gating. PARTIAL — repo routing/text coverage is in place and gated in CI. A second focused auth/comment/notification browser spec and CI job wiring are added, but protected-page browser verification still needs production-style validation because the local dev-server path is not stable enough to close the item.

Exit criteria: 3 of 4 MET (repo-route coverage and CI gate added; broader protected live-flow coverage is implemented but not fully verified yet)

Stage D: Cross-Product Integration — PARTIAL / POST-LAUNCH (New Feature Coding)

Note: This is post-launch enhancement work, not a gap in existing v1 functionality.

  1. Add checkpoint linkage in Gitgram posts (aitm_checkpoint_id / checkpointRef). PARTIAL — checkpoint-aware post creation now works through Gitgram compose, the backend accepts checkpoint metadata, and checkpoint-only post publishing is covered by service/unit validation.
  2. Ship AITM "share as post" flow (connect existing UI to backend). PARTIAL — AITM context replay now deep-links into Gitgram compose for post and change-story publishing with checkpoint/project context carried through.
  3. Add "Change Story" post type from AITM diffs. PARTIAL — Gitgram compose accepts AITM diff/query params, Change Story publishing is live, and Creator Studio exposes repo-linked Change Story entry points. Trend-side surfacing is still open.
  4. Launch trend ranking combining GitHub + platform social signals. TODO

Stage E: Intelligence and Growth — PARTIAL / POST-LAUNCH (New Feature Coding)

Note: This is post-launch enhancement work, not required for v1.

  1. Semantic search over checkpoint/code history. PARTIAL — AITM website now has a Semantic Search dashboard backed by new internal knowledge-base search/stats/artifact routes and passing integration coverage on the API layer.
  2. Training export pipeline with opt-in + redaction + audit traceability. PARTIAL — AITM website now has Training Exports controls, project-level consent toggles, internal pipeline routes, and passing integration coverage for consent/pipeline happy paths plus denial enforcement. End-to-end artifact generation on deployed infra is still open.
  3. Creator tooling for repo owners (story/reel workflows). PARTIAL — Gitgram Creator Studio now exposes repository creator tools, direct repo text/export entry points, post/change-story shortcuts, and AITM setup links. Expanded story/reel growth workflows remain open.

6) Priority Ticket Backlog (Ordered)

P0 (must complete first — deployment):

  • Publish AITM CLI and MCP packages to npm.
  • Production secrets setup for both products.
  • Production infra deploy + DNS/TLS + monitoring.
  • End-to-end smoke verification on live environment.

P1 COMPLETE:

  • Gitgram auth token migration to httpOnly cookies. Done.
  • AITM OAuth callback and redirect hardening. Done.
  • AITM response helper migration completion. Done.
  • Retention/delete/export audit verification. Done.

P2 COMPLETE:

  • AITM CLI modularization. Done.
  • AITM any reduction campaign. Done.
  • Gitgram frontend testing stack and CI enforcement. Done.

P3 (post-deploy — new feature coding + testing):

  • Finish deployment-backed verification for protected Gitgram auth/post/comment/notification browser flows.
  • Complete trend ranking / discovery surfacing for checkpoint-linked posts and Change Story content (Stage D).
  • Harden semantic search relevance and deployed training-export artifact generation (Stage E).
  • Expand Creator Studio beyond repo quick actions into richer story/reel growth tooling (Stage E).

7) Infrastructure Cost Breakdown

Per-Service Pricing (Monthly)

Service Product Plan Monthly Cost Notes
npm AITM Public packages $0 Unlimited free public packages
Hetzner VPS Both CX32 (4 vCPU, 8 GB, 80 GB) ~$7 Docker compose for Gitgram backend + AITM API. ~$8/mo after Apr 2026 price increase
Neon PostgreSQL Gitgram Free → Launch $0–$5 Free: 100 CU-hrs, 0.5 GB. Launch: $5/mo min, storage $0.35/GB-mo
Neon PostgreSQL AITM Free → Launch $0–$5 Separate project. Same tiers
Vercel Both (web) Hobby (free) $0 Free for non-commercial. Pro: $20/user/mo when needed
Polar.sh Both Transaction fees only $0 base 4% + $0.40 per transaction. No monthly fee. MoR handles taxes
Clerk AITM Free $0 Free up to 50K MAU. Pro: $20/mo when needed
Resend Both Free $0 3,000 emails/mo free. Pro: $20/mo for 50K emails
Sentry Both Developer (free) $0 5K errors/mo, 1 user. Team: $26/mo when needed
Upstash Redis Gitgram Free $0 256 MB, 500K commands/mo free
AWS S3 Gitgram Pay-as-you-go ~$1–5 $0.023/GB storage + $0.09/GB egress (first 100 GB free)
Domain Both .app domain ~$2/mo ~$20–25/year for .app domain
GitHub Actions Both Free tier $0 2,000 min/mo free for public repos

Cost Scenarios

Minimum Launch (Free Tiers Only)

Item Cost
Hetzner CX32 $7/mo
Domain (.app) $2/mo
Everything else on free tiers $0
Total ~$9/mo

Small Scale (100 users, light usage)

Item Cost
Hetzner CX32 $7/mo
Neon Launch x2 $10/mo
AWS S3 (10 GB) $1/mo
Domain $2/mo
Vercel Hobby $0
Clerk Free $0
Resend Free $0
Sentry Free $0
Upstash Free $0
Polar.sh (est. 20 txns) ~$12/mo (fee on revenue)
Total infra ~$20/mo (+ Polar fees on revenue)

Growth (1,000 users, moderate usage)

Item Cost
Hetzner CX42 (8 vCPU, 16 GB) $18/mo
Neon Scale x2 $40/mo
AWS S3 (100 GB + egress) $12/mo
Vercel Pro (1 seat) $20/mo
Clerk Pro $20/mo
Resend Pro $20/mo
Sentry Team $26/mo
Upstash Pay-as-you-go $5/mo
Domain $2/mo
Polar.sh (est. 200 txns) ~$120/mo (fee on revenue)
Total infra ~$163/mo (+ Polar fees on revenue)

Polar.sh Revenue Model

Polar.sh charges 4% + $0.40 per transaction (no monthly fee). Revenue examples:

Subscribers Plan Gross Revenue Polar Fee (4% + $0.40) Net Revenue
10 Premium ($9.99) $99.90/mo $4.40 + $4.00 = $8.40 $91.50/mo
10 Creator ($19.99) $199.90/mo $8.00 + $4.00 = $12.00 $187.90/mo
50 Mixed ~$750/mo ~$50 ~$700/mo
100 Mixed ~$1,500/mo ~$100 ~$1,400/mo
500 Mixed ~$7,500/mo ~$500 ~$7,000/mo

Polar is the Merchant of Record — they handle tax calculation, collection, and remittance globally.

8) KPIs

Product:

  • Weekly active developers.
  • Restore actions per active AITM user.
  • Social interactions per repository page.
  • 7-day retention after first restore.

System:

  • Restore success rate and latency percentiles.
  • Diff generation latency.
  • Checkpoint ingestion throughput.
  • Sync lag (local cache to backend).

Safety:

  • Consent coverage.
  • Redaction precision/recall.
  • Mean deletion-request resolution time.

9) Governance Rule

Before starting any new feature stream, verify:

  1. It does not violate Section 3 locked decisions.
  2. It does not bypass P0/P1 launch and security gates.
  3. It has measurable exit criteria tied to KPIs in Section 8.

10) Status Summary (2026-03-17)

Stage Status Work Type
v1 Core Coding COMPLETE All features implemented and tested (1130+ tests passing)
Payment Migration COMPLETE Stripe → Polar.sh (all code, config, docs updated)
Stage A (Deploy) TODO npm publish (CLI + MCP), secrets, VPS, DNS/TLS, DB
Stage B (Security) COMPLETE All exit criteria met
Stage C (Quality) COMPLETE 3/4 met; Playwright deferred to post-deploy
Stage D (Cross-Product) PARTIAL / POST-LAUNCH Enhancement work; not a launch blocker
Stage E (Growth) PARTIAL / POST-LAUNCH Enhancement work; not a launch blocker

Bottom line:

  • Zero coding needed for v1 launch — only deployment/infrastructure remains.

  • Minimum launch cost: ~$9/mo (Hetzner + domain, everything else free tier).

  • Stage D and E are post-launch enhancements, not v1 gaps.

    Tests — All Passing

    ┌─────────────────┬───────────────────────┬───────────┐ │ Suite │ Tests │ Status │ ├─────────────────┼───────────────────────┼───────────┤ │ AITM Core │ 520/520 │ PASS │ ├─────────────────┼───────────────────────┼───────────┤ │ AITM API Server │ 538/538 (+19 skipped) │ PASS │ ├─────────────────┼───────────────────────┼───────────┤ │ Gitgram Web │ 72/72 │ PASS │ ├─────────────────┼───────────────────────┼───────────┤ │ Total │ 1,130 │ ALL GREEN │ └─────────────────┴───────────────────────┴───────────┘

    npm Packages — Ready to Publish

    ┌───────────────────────────────┬─────────┬────────────────────────────────────────────────────────┐ │ Package │ Version │ Details │ ├───────────────────────────────┼─────────┼────────────────────────────────────────────────────────┤ │ @gitgram/timemachine │ 2.0.0 │ CLI: aitm, aitimemachine. 23 commands, core engine │ ├───────────────────────────────┼─────────┼────────────────────────────────────────────────────────┤ │ @gitgram/timemachine-mcp │ 2.0.0 │ MCP server: aitm-mcp. Depends on CLI ^2.0.0 │ └───────────────────────────────┴─────────┴────────────────────────────────────────────────────────┘ Polar.sh fee on $20 subscription

    ┌─────────────┬─────────────────┐
    │ │ Per Transaction │
    ├─────────────┼─────────────────┤
    │ Gross │ $20.00 │
    ├─────────────┼─────────────────┤
    │ 4% fee │ -$0.80 │ ├─────────────┼─────────────────┤
    │ Fixed fee │ -$0.40 │ ├─────────────┼─────────────────┤
    │ You receive │ $18.80 │
    └─────────────┴─────────────────┘

    Scaled out:

    ┌─────────────┬──────────┬───────────┬────────────┐
    │ Subscribers │ Gross/mo │ Polar Fee │ You Get │ ├─────────────┼──────────┼───────────┼────────────┤
    │ 1 │ $20 │ $1.20 │ $18.80 │
    ├─────────────┼──────────┼───────────┼────────────┤ │ 10 │ $200 │ $12.00 │ $188.00 │
    ├─────────────┼──────────┼───────────┼────────────┤
    │ 50 │ $1,000 │ $60.00 │ $940.00 │
    ├─────────────┼──────────┼───────────┼────────────┤
    │ 100 │ $2,000 │ $120.00 │ $1,880.00 │
    ├─────────────┼──────────┼───────────┼────────────┤
    │ 500 │ $10,000 │ $600.00 │ $9,400.00 │ ├─────────────┼──────────┼───────────┼────────────┤
    │ 1,000 │ $20,000 │ $1,200.00 │ $18,800.00 │
    └─────────────┴──────────┴───────────┴────────────┘

    What each scenario includes

    Minimum Launch — ~$9/mo

    What you get:

    • 1 VPS running both Gitgram backend + AITM API server (4 vCPU, 8 GB RAM)
    • PostgreSQL with 0.5 GB storage per project (auto-scales to zero when idle)
    • Redis with 256 MB cache, 500K commands/mo
    • 3,000 emails/mo (password reset, notifications)
    • 5K error tracking events/mo
    • 50K auth users (AITM via Clerk)
    • Frontend hosted on Vercel free tier
    • Media stored locally on VPS (80 GB NVMe)

    Limits you'll hit first:

    • 0.5 GB database (enough for ~5K-10K users)
    • No S3 (media on VPS disk, 80 GB cap)
    • 3K emails/mo (enough for ~500 active users)
    • No CDN, no custom email domain
    • Vercel hobby = non-commercial only

    Good for: Development, beta testing, first users


    Small Scale — ~$20/mo (100 users)

    What you get (on top of minimum):

    • Neon Launch x2 ($5 each) — real production databases, auto-scaling compute, more storage
    • AWS S3 for media uploads (10 GB) — proper file storage, not VPS disk
    • Everything else still on free tiers

    Limits:

    • S3 egress: first 100 GB/mo free
    • 3K emails/mo still (upgrade to Resend Pro at $20/mo if needed)
    • Single VPS (no redundancy)

    Good for: Soft launch, early adopters, getting first paying subscribers


    Growth — ~$163/mo (1,000 users)

    What you get (on top of small):

    • Bigger VPS (8 vCPU, 16 GB RAM) — handles concurrent WebSocket connections, video processing
    • Neon Scale x2 — higher connection limits, read replicas, compliance features
    • Vercel Pro — commercial use allowed, 1 TB bandwidth, team collaboration
    • Clerk Pro — SSO, enterprise auth features, unlimited orgs
    • Resend Pro — 50K emails/mo
    • Sentry Team — 100K errors/mo, multiple users, performance monitoring
    • Upstash paid — more Redis capacity for rate limiting, sessions, caching
    • AWS S3 100 GB + egress

    Limits:

    • Single VPS still (for HA, add second VPS +$18/mo)
    • No dedicated DB (Neon Scale is still serverless)

    Good for: Active community, real revenue, hundreds of daily active users


    Break-even math

    With $9/mo minimum infra and $18.80 net per subscriber:

    ┌─────────────────────────────┬────────────────────┐
    │ │ Subscribers needed │
    ├─────────────────────────────┼────────────────────┤
    │ Cover minimum infra ($9/mo) │ 1 subscriber │
    ├─────────────────────────────┼────────────────────┤ │ Cover small scale ($20/mo) │ 2 subscribers │
    ├─────────────────────────────┼────────────────────┤
    │ Cover growth ($163/mo) │ 9 subscribers │
    └─────────────────────────────┴────────────────────┘

    ┌─────────────────┬───────────────────────────────┬────────┐ │ Product │ Check │ Result │ ├─────────────────┼───────────────────────────────┼────────┤ │ AITM CLI │ Build (tsc) │ PASS │ ├─────────────────┼───────────────────────────────┼────────┤ │ AITM CLI │ Tests (520/520) │ PASS │ ├─────────────────┼───────────────────────────────┼────────┤ │ AITM CLI │ Runtime (--version → 2.0.0) │ PASS │ ├─────────────────┼───────────────────────────────┼────────┤ │ AITM CLI │ Help (23 commands listed) │ PASS │ ├─────────────────┼───────────────────────────────┼────────┤ │ AITM MCP │ Build (tsc) │ PASS │ ├─────────────────┼───────────────────────────────┼────────┤ │ AITM MCP │ Runtime (stdio server starts) │ PASS │ ├─────────────────┼───────────────────────────────┼────────┤ │ AITM API Server │ Type-check │ PASS │ ├─────────────────┼───────────────────────────────┼────────┤ │ AITM API Server │ Tests (538/538, +19 skip) │ PASS │ ├─────────────────┼───────────────────────────────┼────────┤ │ AITM VS Code │ Tests (62/62) │ PASS │ ├─────────────────┼───────────────────────────────┼────────┤ │ AITM Website │ Next.js build │ PASS │ ├─────────────────┼───────────────────────────────┼────────┤ │ Gitgram Backend │ Type-check (0 errors) │ PASS │ ├─────────────────┼───────────────────────────────┼────────┤ │ Gitgram Web │ Next.js build │ PASS │ ├─────────────────┼───────────────────────────────┼────────┤ │ Gitgram Web │ Tests (72/72) │ PASS │ └─────────────────┴───────────────────────────────┴────────┘

    we can fork bd https://github.com/upstash/context7.git https://github.com/BeehiveInnovations/pal-mcp-server.git for aitm mcp and aitm stuff and for
    gitgram we can clone some openourse social media stuff becuase gitgram is social media layer for github repositories we can fork bd https://github.com/upstash/context7.git https://github.com/BeehiveInnovations/pal-mcp-server.git for aitm mcp and aitm stuff and for
    gitgram we can clone some openourse social media stuff becuase gitgram is social media layer for github repositories vvv

    Repos to Fork/Clone

    For AITM MCP

    ┌───────────────────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
    │ Repo │ What to Adapt │
    ├───────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
    │ upstash/context7 │ Streamable HTTP transport (AITM is stdio-only), AsyncLocalStorage per-request context, tool description │
    │ │ engineering, multi-agent setup CLI (aitm setup --claude --cursor), SDK client pattern with retry │ ├───────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
    │ BeehiveInnovations/pal-mcp-server │ ToolAnnotations (readOnlyHint/destructiveHint) for all 40 tools, modular tool class architecture (extract from │
    │ │ monolithic index.ts), DISABLED_TOOLS env var, standardized output envelope, path validation for restore safety │ ├───────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤ │ abhigyanpatwari/GitNexus │ Zero-server knowledge graph + Graph RAG agent over repos. Adapt for AITM code-context indexing, checkpoint │ │ → external/gitnexus │ knowledge graphs, and Gitgram repo explore/visualisation surface. Cloned 2026-06-21. │ ├───────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤ │ gastownhall/beads │ Git-native DAG issue tracker for AI agents. bd ready shows dependency-unblocked work with hash-based IDs. │ │ → external/beads │ Reference for AITM task/issue tracking integration and multi-agent coordination. Cloned 2026-06-21. │ └───────────────────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

    For Gitgram (Social Layer)

    ┌─────┬──────────────────────────────────┬───────┬─────────┬───────────────────────────────────────────────────────────────────────────────────────────┐ │ # │ Repo │ Stars │ License │ Why │
    ├─────┼──────────────────────────────────┼───────┼─────────┼───────────────────────────────────────────────────────────────────────────────────────────┤ │ 1 │ codinginflow/nextjs-15-social- │ 417 │ -- │ Exact same stack (Next.js + Prisma + PG). Prisma schema maps 1:1 to Gitgram. Infinite │
    │ │ media-app → external/nextjs-15- │ │ │ scroll, optimistic updates, notifications. Cloned 2026-06-21. │ │ │ social-media-app │ │ │ │ ├─────┼──────────────────────────────────┼───────┼─────────┼───────────────────────────────────────────────────────────────────────────────────────────┤ │ 2 │ leandronorcio/munia │ 293 │ MIT │ Most complete features: GitHub OAuth, @mentions, hashtags, nested comments, drag-drop │
    │ │ → external/munia │ │ │ media, S3 uploads, accessibility. Cloned 2026-06-21. │ ├─────┼──────────────────────────────────┼───────┼─────────┼───────────────────────────────────────────────────────────────────────────────────────────┤
    │ 3 │ TomDoesTech/t3-twitter-clone │ 189 │ MIT │ Only one with Express branch — matches Gitgram's Express backend. Type-safe tRPC │ │ │ → external/t3-twitter-clone │ │ │ patterns. Cloned 2026-06-21. │ ├─────┼──────────────────────────────────┼───────┼─────────┼───────────────────────────────────────────────────────────────────────────────────────────┤ │ 4 │ karanpratapsingh/Proximity │ 360 │ GPL-3 │ Best React Native social app with Prisma. Real-time messaging via GraphQL subscriptions. │
    │ │ → external/proximity │ │ │ Reference only (GPL). Cloned 2026-06-21. │ ├─────┼──────────────────────────────────┼───────┼─────────┼───────────────────────────────────────────────────────────────────────────────────────────┤
    │ 5 │ bluesky-social/social-app │ 17.8K │ MIT │ Production-scale feed algorithms, notifications, moderation. Architecture reference. │ │ │ → external/bluesky-social-app │ │ │ Cloned 2026-06-21. │ ├─────┼──────────────────────────────────┼───────┼─────────┼───────────────────────────────────────────────────────────────────────────────────────────┤ │ 6 │ abhigyanpatwari/GitNexus │ -- │ -- │ Client-side knowledge graph + Graph RAG over any repo. Reference for Gitgram repo │ │ │ → external/gitnexus │ │ │ explore/visualisation. Also useful for AITM. Cloned 2026-06-21. │ └─────┴──────────────────────────────────┴───────┴─────────┴───────────────────────────────────────────────────────────────────────────────────────────┘

    Quick-win bonus

    • amirfakhrullah/gh-social (MIT) — The only "GitHub Social Platform" found. Syncs GitHub follows/stars to a social feed. Next.js + tRPC + Clerk + Drizzle + Neon. Closest concept to Gitgram. Cloned 2026-06-21 → external/gh-social.
    • gastownhall/beads (MIT) — Git-native DAG issue tracker by Steve Yegge for AI agents. Cloned 2026-06-21 → external/beads.

    Top Actionable Items from Research

    AITM MCP (high priority, small effort):

    1. Add ToolAnnotations to all 40 tools — readOnlyHint: true for read tools, destructiveHint: true for restore
    2. Add Streamable HTTP transport (from context7 pattern) — enables web/VS Code clients
    3. Extract tools from monolithic index.ts into modular files

    Gitgram (reference patterns to study):

    1. Prisma schema design from nextjs-15-social-media-app
    2. @mentions + hashtag system from munia
    3. Feed pagination (cursor-based infinite scroll) from both
    4. GitHub API integration from gh-social

    │ BloopAI/vibe-kanban │ 24.6k │ Kanban for AI agents, MCP server+client, git worktree isolation, diff review. Best task board │
    │ │ │ foundation. │
    ├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤

    │ gastownhall/beads (bd!) │ 20.4k │ Git-native DAG issue tracker made for AI agents. This is what bd is. │
    ├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤

    │ a2aproject/a2a-js │ 509 │ Official A2A TypeScript SDK. Needed for standards compliance. │
    ├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤

    │ agentgateway/agentgateway │ 2.3k │ Rust proxy for A2A + MCP traffic. Security/observability built in. │

    ├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
    │ GongRzhe/A2A-MCP-Server │ 147 │ Bridges MCP ↔ A2A so Claude can talk to A2A agents. │

    ├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤

    │ Open-ACP/OpenACP │ 58 │ Connects 28+ AI agents to Telegram, Discord, Slack. Real-time messaging. │
    └───────────────────────────┴───────┴───────────────────────────────────────────────────────────────────────────────────────────────────┘

    Key insight about bd (Beads)

    Beads by Steve Yegge is exactly what you're already using for task tracking! It's a git-native graph issue tracker designed for AI agents.

    bd ready shows unblocked work, dependency DAGs, hash-based IDs for concurrent agents. 20k+ stars, MIT.

    │ BloopAI/vibe-kanban │ 24.6k │ Kanban for AI agents, MCP server+client, git worktree isolation, diff review. Best task board │
    │ │ │ foundation. │
    ├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤

    │ gastownhall/beads (bd!) │ 20.4k │ Git-native DAG issue tracker made for AI agents. This is what bd is. │
    ├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤

    │ a2aproject/a2a-js │ 509 │ Official A2A TypeScript SDK. Needed for standards compliance. │
    ├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤

    │ agentgateway/agentgateway │ 2.3k │ Rust proxy for A2A + MCP traffic. Security/observability built in. │

    ├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
    │ GongRzhe/A2A-MCP-Server │ 147 │ Bridges MCP ↔ A2A so Claude can talk to A2A agents. │

    ├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤

    │ Open-ACP/OpenACP │ 58 │ Connects 28+ AI agents to Telegram, Discord, Slack. Real-time messaging. │
    └───────────────────────────┴───────┴───────────────────────────────────────────────────────────────────────────────────────────────────┘

    Key insight about bd (Beads)

    Beads by Steve Yegge is exactly what you're already using for task tracking! It's a git-native graph issue tracker designed for AI agents.

    bd ready shows unblocked work, dependency DAGs, hash-based IDs for concurrent agents. 20k+ stars, MIT.

                                                                                                             # Unified Manual Launch Plan for Gitgram + AITM
    

    Summary

    Prepare both products for a parallel launch using a single server / operator-managed deployment model as the source of truth. The plan should treat the existing repo as mostly implementation-complete, but should not trust the docs blindly: first reconcile deployment artifacts, environment contracts, and stale references, then execute a manual launch path that does not depend on unfinished CI/CD automation.

    Success means:

    • AITM npm packages are published and installable.
    • Gitgram backend/web and AITM API are deployable from documented manual commands.
    • Production secrets/env contracts are complete and validated.
    • Health checks, rollback steps, and operator runbooks match the actual repo layout.
    • Stale or conflicting deployment guidance is removed or explicitly deprecated.

    Implementation Changes

    1. Establish one canonical launch topology

    • Make the manual-ops path the primary launch contract: single operator-managed host, Docker/PM2/systemd as applicable, no dependency on unfinished GitHub Actions deployment flows.
    • Standardize the production target as:
      • Gitgram backend: long-running Node service on the server.
      • Gitgram web: long-running Next.js service on the server.
      • AITM API: long-running Node service on the server.
      • Shared infra: PostgreSQL + Redis on the same host or tightly coupled managed services, but documented as one operational unit.
    • Demote GitHub Actions deploy workflows to “future automation” unless they fully match the manual launch path.

    2. Reconcile repo truth with docs before launch execution

    • Audit and fix contradictions between SINGLE_SOURCE_PLAN.md, docs/deploy-pipeline.md, docs/ops-quickref.md, docs/runbook.md, compose files, and actual workflow filenames.
    • Remove or clearly mark stale deployment variants that conflict with the chosen topology.
    • Resolve broken references in docs, especially any paths/services that do not exist in the tree.
    • Normalize naming so the same service names, ports, health endpoints, workflow names, and env var conventions are used everywhere.
    • Treat docs/can be fork.md as the maintained reference-clone inventory; use SINGLE_SOURCE_PLAN.md as the canonical execution plan for launch sequencing.

    3. Lock the manual launch path per product

    • AITM:
      • Verify package publish order and prerequisites for @gitgram/timemachine and @gitgram/timemachine-mcp.
      • Define the exact manual publish checklist, post-publish verification, and rollback/version bump procedure.
      • Define the exact API deployment procedure, including build, env validation, migration application, service restart, and health verification.
    • Gitgram:
      • Define the exact backend deployment procedure, including Prisma generation/migration, build, restart, and health verification.
      • Define the exact web deployment procedure, including build, runtime env injection, restart, and smoke verification.
    • Shared:
      • Choose one restart/control mechanism per service and document it as canonical. If both PM2 and systemd are kept, assign one as primary and one as fallback, not equal-status alternatives.

    4. Harden secrets and env contracts for launch

    • Use docs/secrets-contract.md and docs/environment-matrix.md as the starting point, but reconcile them with actual runtime/package needs.
    • Produce one canonical required-vars list for:
      • Gitgram backend
      • Gitgram web
      • AITM API
      • AITM package publish/release flow
    • Validate that production-only integrations needed for launch are present and named consistently, especially database, Redis, JWT, Polar, S3/storage, email, and any internal auth secrets.
    • Ensure validation scripts and runbooks match the chosen unprefixed/prefixed env convention and the manual deployment path.
    • Explicitly document which secrets are required before first launch vs optional post-launch integrations.

    5. Define launch-day operations and rollback

    • Convert the runbook into an operator-focused launch sequence with:
      • preflight checks
      • ordered deploy steps
      • health gates
      • smoke checks
      • rollback commands
      • post-launch monitoring window
    • Rollback should be manual-first and concrete:
      • previous package version for npm artifacts
      • previous app build/image/tag for server services
      • DB migration rollback policy or “restore from backup only” policy where down-migrations are not supported
    • Require a backup/checkpoint step before applying production migrations.

    Public Interfaces / Contracts

    • No product API redesign is planned.
    • Public-facing contract changes are limited to:
      • canonical deployment/runbook docs
      • explicit deprecation of stale deployment paths and references
    • If any current docs mention missing components such as non-existent service paths, update the documentation contract rather than inventing new components for launch.

    Test Plan

    • Verify repo-level build/test/typecheck commands for the launch-critical services still pass.
    • Dry-run the manual deployment commands in a staging-like environment for:
      • Gitgram backend
      • Gitgram web
      • AITM API
      • AITM package publish verification flow
    • Validate health endpoints after each service restart.
    • Run minimal smoke scenarios:
      • Gitgram auth and basic API reachability
      • Gitgram web load and API connectivity
      • AITM API health/readiness and one representative core flow
      • npm install plus basic CLI/MCP invocation for published AITM packages
    • Test rollback instructions at least once in staging-like conditions.

    Assumptions and Defaults

    • Launch is for both products in parallel, not a staggered product strategy.
    • The delivery path is manual operations first, with CI/CD treated as non-blocking unless brought into alignment.
    • The hosting model is single server / operator-managed, not a multi-platform redesign.
    • Existing code is assumed largely complete; the main launch risk is operational inconsistency, stale docs, and deployment drift.
    • Any workflow or doc that conflicts with the chosen manual launch path should be updated, deprecated, or ignored rather than preserved for symmetry.