Maha Strategies

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.

Stack

Running it locally

Requires Node 22 or newer.

npm install
npm run dev

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.

Checks

npm run typecheck && npm run lint && npm test

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.

Working on this codebase

Three rules are enforced rather than assumed, because violating them corrupts state that cannot be reconstructed:

1. 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:

   bash

   Copy

   node --experimental-strip-types scripts/check-migrations.ts
   

2. 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.

3. 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.

Operations

Outbound Market Discovery Matrix

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:

MARKET_SCOUT_QUERY_MATRIX={"lanes":[{"id":"claims","label":"Claim verification","queries":["claim verification API pricing","citation audit tool quote"]},{"id":"documents","label":"Document extraction","queries":["PDF table extraction API pricing"]}]}

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.

Agent Inquiry Gateway

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:

AGENT_REVIEW_TOKEN=<unique reviewer bearer token>
RESEND_API_KEY=<existing Resend key>

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:

curl --request POST https://www.mahastrategies.com/api/agent-inquiries \
  --header "Authorization: Bearer $CLIENT_CREDENTIAL" \
  --header "Content-Type: application/json" \
  --data '{
    "clientRequestId": "client-generated-unique-id",
    "offerId": "rapid-intelligence-brief",
    "requester": { "name": "Requesting principal", "email": "principal@example.com" },
    "decision": "The decision this brief will inform.",
    "question": "One clearly defined market, technology, or policy question.",
    "requesterAuthorized": true,
    "agent": { "name": "Approved client agent", "version": "1.0" }
  }'

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:

GET   /api/agent-inquiries/:inquiryId
PATCH /api/agent-inquiries/:inquiryId

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.

Client Credential Registry

Private reviewer operations are available at:

GET  /api/agent-credentials
POST /api/agent-credentials
GET  /api/agent-credentials/:credentialId
PATCH /api/agent-credentials/:credentialId