The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Mps Preflight listing page.
The Maha Strategies platform: one Next.js application serving the public site and publishing surfaces, the credentialed commercial APIs, and the private operations control planes behind them. It is deployed on Vercel at www.mahastrategies.com.
Most of what follows in this file is operating instructions for a specific subsystem — read the section you need rather than the whole document.
| Concern | Service |
|---|---|
| Application and hosting | Next.js (App Router), React, TypeScript, on Vercel |
| Database | Supabase Postgres, RLS with no public access policies |
| Cache, rate limits, balances | Upstash Redis, namespaced per deployment environment |
| GPU compute | Modal — workers/maha_workers.py |
| Payments | Stripe — a separate endpoint and signing secret per product line |
| Resend | |
| Telemetry | Sentry, payload-scrubbed |
Requires Node 22 or newer.
The app serves on http://localhost:3000. Copy
.env.example to .env.local and fill in what the surface you are working on
needs; most features degrade to a disabled state rather than crashing when their
variables are absent.
To exercise the database locally, start Supabase (supabase start) and apply
supabase/migrations plus supabase/seed.sql, which provides deterministic
fixtures.
npm test runs the full suite in test/. The same commands run in CI on every
pull request, together with a production build, a production-dependency audit,
and the migration integrity check below.
Three rules are enforced rather than assumed, because violating them corrupts state that cannot be reconstructed:
Migrations are append-only. Never edit, rename, or delete a migration
that has been committed — it may already have run in Production. Add a new
forward migration. Filenames are <14-digit UTC timestamp>_<snake_case>.sql
and must sort after everything already on main. Verify with:
Ledgers are append-only. Corrections are new rows and refunds are reversal entries; nothing edits or deletes a recorded commercial outcome. Operator interventions go through the audited, idempotent actions in the MPS operational control plane, not through direct table writes.
Secrets stay server-side. Only NEXT_PUBLIC_* variables reach the
browser. Credential secrets are disclosed exactly once at issuance and stored
only as hashes.
Framework note: this repository tracks a Next.js version whose APIs may differ
from older documentation. See AGENTS.md.
| Runbook | Covers |
|---|---|
docs/agent-discovery-metering.md | Measuring whether agents are finding the platform, and reading the numbers honestly |
docs/backup-restore.md | Rehearsing a database restore, and measuring RTO and RPO |
docs/database-migrations.md | Applying schema changes to Production, drift detection, evidence |
docs/observability.md | Sentry configuration, signed alert verification, readiness checks |
docs/release-recovery.md | Release health, recovery drill, rollback, rehearsal, required GitHub environments |
docs/preview-e2e.md | Integration gates on every Preview deployment, and making them block merges |
docs/slo-capacity.md | Service objectives, error budgets, the bounded capacity harness |
docs/x402-conformance-corpus.md | Vendor-neutral x402 v2 fixtures and the offline reference runner |
docs/x402-declaration-digest-proposal.md | Draft catalog-attested discovery declaration digest and test vectors |
docs/x402-doctor.md | Live resource, crawler, Bazaar drift, and bounded-settlement diagnostics |
docs/x402-observatory.md | Public protocol-correctness observations, inclusion policy, and scheduled operation |
docs/x402-buyer-policy.md | Vendor-neutral pre-signing budgets, approvals, replay controls, and settlement verification |
SECURITY.md | Vulnerability reporting and the platform's standing security assumptions |
The private Market Scout is a read-only discovery process. It pulls attributable web-search evidence into /admin/market-mapping, where every proposal remains subject to a deterministic score and human review. It cannot publish, spend, deploy, or contact a person.
With MARKET_SCOUT_SOURCES=exa and EXA_API_KEY set, the default matrix rotates five queries per UTC day across MPS claim verification, research briefs, document-data extraction, and receipt operations. Each query retrieves at most eight Exa results.
To replace the defaults, set this server-only JSON environment variable:
The matrix permits up to eight named lanes and twelve queries per lane; the Scout still selects only five cross-lane queries per daily run. The older MARKET_SCOUT_QUERIES JSON-string-array setting remains supported as a single custom lane for backward compatibility.
POST /api/agent-inquiries is an authenticated, non-binding intake endpoint for the offers published in /agent-offers.json. It validates against /agent-inquiry-schema.json, persists the inquiry and its first event to a private Supabase ledger, then attempts to notify the reviewer through Resend. It does not accept payment, create a commission, or send work automatically.
The inquiry gateway accepts named, database-backed client credentials. Credential issuance and revocation are private reviewer operations; there is no shared public inquiry token.
Set these deployment environment variables before enabling it:
Optional delivery overrides are AGENT_INQUIRY_FROM and AGENT_INQUIRY_TO. Keep the reviewer token server-side. Client credentials are created by the private registry and are shown only once at issuance.
Approved clients send JSON using the schema at /agent-inquiry-schema.json:
A successful 202 response means only that the request was recorded for human review. The returned notificationStatus shows whether the optional email notification was delivered. Neither result is an acceptance, purchase confirmation, or service-level commitment.
Apply supabase/migrations/20260716_agent_inquiry_ledger.sql, supabase/migrations/20260716_agent_client_credentials.sql, supabase/migrations/20260716_mps_audit_jobs.sql, and supabase/migrations/20260717_serverless_credential_rate_limits.sql in the Supabase SQL Editor before enabling the full agent infrastructure. Together, they create the private inquiry ledger, credential registry, MPS audit ledger, database-maintained event histories, and an atomic shared credential rate limiter with RLS and no public access policies. The existing NEXT_PUBLIC_SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY deployment variables are required.
Selected credential-based commercial APIs also write to commercial_api_usage_daily through 20260727000100_privacy_preserving_commercial_api_metering.sql. This is a daily aggregate meter for MPS audits, MPS credit reads, book-entitlement checks, and structured book-content delivery. It deliberately excludes IP addresses, user agents, token values or fingerprints, request and response bodies, referrers, emails, and visitor identifiers. The read-only aggregate board is /admin/commercial-api-metering and requires REVENUE_CONTROL_TOKEN.
Reviewer operations use a separate private endpoint:
Both require Authorization: Bearer <AGENT_REVIEW_TOKEN>. GET returns the full private request and its event history. PATCH accepts one action: start_review, needs_clarification, decline, or approve_for_scoping; the last is an internal disposition, not an acceptance of work.
Private reviewer operations are available at:
All require Authorization: Bearer <AGENT_REVIEW_TOKEN>. POST issues a credential once; its plaintext value is returned only in that response. Supply either a new clientName or an existing clientId, plus credentialLabel, one or more allowedOfferIds and/or optional allowedCapabilities, optional rateLimitPerHour (default 12), and optional expiresAt (default 90 days). A capability-only credential is permitted. Capabilities default to none; the only current capability is mps_audit. PATCH accepts { "action": "revoke", "reason": "optional note" }. GET endpoints never return a credential secret.
Example issuance:
POST /api/mps-audits applies the headless MPS/0.1 engine to a single passage. It requires a named client credential carrying the explicit mps_audit capability, uses the same credential rate limit, and stores an idempotent audit record in Supabase. The source passage is processed but deliberately not retained; the record retains the input hash, output claim excerpts, model identifier, status, and event history. This is a computational API, not a certification or a substitute for human verification.
The request schema is published at /mps-audit-schema.json. Use a unique clientRequestId; reuse of the same value with different text returns 409. A completed response contains the audit result. A replay with the same request ID and passage returns the stored result without a second model invocation.
/audit is the free, bounded public MPS preflight. It accepts a passage of up to 6,000 characters, returns a claim map in the browser, and lets a visitor download a source-free JSON record. It is distinct from the credentialed API and from the paid private Preflight at /mps/preflight.
Apply supabase/migrations/20260717_public_mps_audit_usage.sql and set the server-only MPS_PUBLIC_AUDIT_RATE_LIMIT_SECRET before deploying this version. The secret HMACs an IP-and-user-agent visitor fingerprint for a three-runs-per-day quota; neither the source text nor a source-text hash is saved in the public usage or event tables. The public event table records only submitted, completed, failed, and record-download events with counts/timestamps so that conversion can be measured without collecting the passage.
The repository includes self-service Stripe Checkout at /mps/audit-access. Each purchase creates a dormant credential scoped only to mps_audit; Stripe's signed webhook atomically grants the configured mps_audit_invocation pack and activates that credential. The secret is disclosed once in the purchasing browser.
It is disabled by default. It requires the 20260717_mps_audit_credit_ledger.sql, 20260717_self_service_mps_audit_access.sql, and 20260717_stripe_webhook_idempotency.sql migrations, a dedicated Stripe Price, a dedicated webhook endpoint at /api/mps-credits/webhook, and all of these server-only variables before POST /api/mps-credits/checkout can create a checkout:
Subscribe that endpoint to checkout.session.completed, checkout.session.async_payment_succeeded, refund.created, and refund.updated. Successful payment adds a purchase-grant entry; a successful refund adds a proportional reversal entry rather than mutating the grant. The webhook migration records each Stripe evt_ ID under a unique constraint and atomically commits that event record with its ledger change. Duplicate events are acknowledged without another balance change, while an out-of-order refund receives a retryable response until its checkout grant exists.
GET /api/mps-credits returns the authenticated client’s ledger balance. For prepaid credentials, POST /api/mps-audits atomically reserves one credit, returns HTTP 402 with the purchase URL when none remains, and creates an idempotent refund entry if execution fails. Existing credentials default to internal_meter and retain their prior meter-only behavior without credit enforcement.
Book checkout webhooks must subscribe to checkout.session.completed, checkout.session.async_payment_succeeded, refund.created, refund.updated, and charge.dispute.closed. A successful payment mints a book entitlement exactly once. Confirmed refund objects are recorded once per Stripe refund, and the entitlement is revoked only after the cumulative reversed amount reaches the original paid amount. A dispute revokes access only when Stripe closes it as lost.
Apply supabase/migrations/20260718_mps_operational_control_plane.sql after the prepaid-credit and Stripe-webhook migrations, then configure a dedicated server-only MPS_OPERATIONS_TOKEN. Do not reuse AGENT_REVIEW_TOKEN. The control plane has no public UI and never returns stored secret hashes or plaintext credentials.
Use the exact-match lookup endpoint before any intervention. The request body keeps receipt emails and customer identifiers out of URL/access logs. Supported values are a receipt email, client ID, credential ID, 14-character credential prefix, checkout ID, Stripe Checkout Session ID, PaymentIntent ID, Refund ID, or Event ID.
Mutations use /api/admin/mps-operations/actions. Every request requires a unique operator-supplied idempotency key, a reason, and an external ticket or Stripe reference. The database commits the mutation and immutable operator-action record in one transaction.
Append a credit correction; never edit or delete existing ledger rows:
Immediately revoke an active or pending-payment credential:
Replace a lost, active prepaid MPS credential while preserving its client-level balance:
Replacement revokes the old credential atomically and returns the new plaintext once. An idempotent replay confirms the original replacement but cannot redisclose its plaintext. Deliver new credentials through an approved secret-sharing channel; never put them in tickets, logs, source control, or chat. Supabase Studio may be used for inspection, but all balance corrections, revocations, and replacements must go through these audited actions rather than direct table edits.
Apply supabase/migrations/20260720001900_revenue_control_plane.sql and supabase/migrations/20260720002000_revenue_event_reconciliation.sql, then configure a separate, server-only REVENUE_CONTROL_TOKEN. Do not reuse reviewer or MPS operations tokens. The private endpoint is:
It records only non-PII source references, offer routing, and immutable commercial outcome events. It cannot send outreach, charge a customer, sign a contract, operate a wallet, or accept an engagement. Existing self-service offers route to their current purchase pages; Rapid Intelligence Brief and Verified Research Brief signals remain subject to human scope and price confirmation.
Route an inbound signal with a stable source reference:
Later record a stateful outcome with a different idempotency key. paid and refunded require positive amountCents and a three-letter currency. The ledger allows only valid transitions: routing/review to checkout, checkout to paid, paid to delivered, and paid or delivered to refunded.
Verified Stripe payment and reversal webhooks now reconcile automatically into this ledger. MPS audit credits and book entitlements are marked delivered only after their existing product webhooks issue access; MPS Preflight records delivery when its report completes. Stripe remains the payment authority, and no revenue control-plane token is sent to Stripe or the browser.
The platform includes privacy-scrubbed Sentry error/performance telemetry, Redis and Modal MCP dependency spans, signed low-credit and upstream-connectivity webhooks, and a private configuration-readiness endpoint. See the operations runbook for environment variables, signature verification, dashboards, and release tests.
Production release health runs four times per hour, preserves the exact last-known-good Vercel deployment, and supports a reviewer-gated rollback with post-recovery readiness and full canary verification. See the release recovery runbook.
Internal availability and latency objectives are enforced by a bounded Preview capacity harness covering public surfaces, readiness dependencies, Upstash key lookup, and an explicitly confirmed controlled-upstream MCP profile. See service objectives and capacity acceptance.
Apply supabase/migrations/20260720002100_inbound_revenue_gatekeeper.sql. Public human and agent submissions use POST /api/inbound-submissions, with the schema at /inbound-submission-schema.json and the machine-readable agent card at /.well-known/agent.json. The endpoint uses a database-backed hourly rate limit, a honeypot, strict size/schema validation, and deterministic qualification. It routes every accepted submission to the private Revenue Control Plane but never creates a commitment, payment, contract, or automatic outreach.
The scheduled GET /api/cron/inbound-digest endpoint sends one daily digest of unsent qualified submissions. Configure INBOUND_DIGEST_TO and Vercel's CRON_SECRET; INBOUND_DIGEST_TOKEN is available only for a separately authorized manual trigger. vercel.json schedules the Vercel Cron invocation for 13:00 UTC. The digest contains personal contact details, so keep its recipient address private.
Apply supabase/migrations/20260720003200_inbound_operations_queue.sql, configure a separate server-only INBOUND_OPERATIONS_TOKEN, then open /admin/inbound. The private queue displays inbound qualification, contact context, linked revenue status, and an append-only review history. Its actions are limited to review, clarification, scope approval, checkout referral, decline, and close-lost. It cannot send any message, accept an engagement, or mark a payment as received.