Build a Drive for the Garage.

1. What is a Drive?

A Drive is a self-contained product that plugs into Merkava Core (the Merkava platform) via the Meridian Platform Contract. Merkava Core is the host — portfolio dashboard, venture registry, Forge AI, billing, identity. Drives are the modules that execute work — content, SEO, paid ads, CRM, support, finance. Each one is its own product with its own URL, its own users, and its own pricing; the Contract is what lets Merkava roll them up into a single workspace.

• Quillsly — content Drive. Standalone at app.quillsly.com; also mounts inside Merkava.
• Beacon — SEO + GEO Drive. Audits, then ships the fix as a repo commit. Built-in to Merkava Core today.
• Relay — embeddable support chat. Installs provision a scoped widget token the operator drops into their site.

A Drive is not a plugin, not an integration, not an API. It's a full product that happens to speak the Platform Contract.

2. The two modes

Most Drives support both modes. Some (Beacon today) are Merkava-mounted only.

• Standalone. The Drive runs on its own domain, has its own brand identity and design system, bills its own customers, and has users who may never touch Merkava.
• Merkava-mounted. The same Drive, installed into a Merkava tenant. Merkava's chrome (nav, sidebar, platform chrome) stays intact — the Drive renders only into the content area. Each install is scoped to exactly one venture.

3. Platform Contract v1 overview

The Contract is a minimal, HMAC-signed HTTP protocol. No OAuth, no SDK required, no per-service API keys. One shared agent secret signs every request between Merkava Core and a Drive.

Two headers on every authenticated request:

X-Meridian-Timestamp: <unix-milliseconds>    (NOT seconds)
X-Meridian-Signature: <raw-hex hmac-sha256>  (NO "sha256=" prefix)

Signed payload is the canonical string ${timestamp}:${path}. Path includes query string; not method or body. Timestamps more than 5 minutes skewed are rejected. Signature comparison is constant-time (crypto.timingSafeEqual or equivalent).

One env var, MERIDIAN_AGENT_SECRET, shared across the fleet. Rotate it once and every Drive reconnects. See the Platform Contract reference for more.

4. Required endpoints

Seven endpoints. Health and manifest are public; the rest are HMAC-gated.

Every response is wrapped in {ok, data, meta: {version, generated_at}}. Failure returns {ok: false, error: '<reason>'} with an appropriate HTTP status.

5. The Drive manifest

The manifest is the Drive's self-description. The Garage reads it to render the Drive's card. Merkava Core reads it on install to know what capabilities and permissions to provision.

Example — Quillsly's live manifest at https://api.quillsly.com/api/meridian/drive/manifest:

{
  "ok": true,
  "data": {
    "name": "Quillsly",
    "description": "Content written for the AI-search era.",
    "category": "Content",
    "version": "1.4.2",
    "contract_version": "v1",
    "pricing": {
      "model": "subscription",
      "currency": "usd",
      "plans": [
        {"id": "solo", "name": "Solo", "price_cents": 4900, "interval": "month"}
      ]
    },
    "capabilities": ["pillars", "briefs", "articles", "jsonld_export"],
    "routes_exposed": [
      {"path": "/content/pillars", "label": "Pillars", "icon": "layers"}
    ],
    "permissions_requested": ["venture.read", "events.emit", "billing.read"],
    "icon_url": "https://app.quillsly.com/assets/img/quillsly-mark.svg"
  },
  "meta": {"version": "v1", "generated_at": "2026-04-19T12:00:00Z"}
}

Required: name, description, category, version, contract_version, capabilities, permissions_requested, icon_url. Optional: pricing, routes_exposed (needed if Merkava-mounted).

6. Install handshake

When an operator clicks Install in the Garage, Merkava POSTs to the Drive's install endpoint. The Drive provisions a workspace, returns a scoped token, and Merkava stores it for future per-install signed requests.

┌──────────────┐                                  ┌─────────────┐
│  Merkava     │  POST /api/meridian/install      │   Drive     │
│  Core        │ ────────────────────────────────>│  (Quillsly) │
│              │  {merkava_tenant_id,             │             │
│              │   merkava_venture_id,            │             │
│              │   venture_name,                  │             │
│              │   operator_email} + HMAC         │             │
│              │  200 {ok, data: {                │             │
│              │    scoped_token,                 │             │
│              │    drive_workspace_id}}          │             │
│              │ <────────────────────────────────│             │
└──────────────┘                                  └─────────────┘

Request body (canonical, from src/drives/marketplace.js):

{
  "merkava_tenant_id": "meridian",
  "merkava_venture_id": "quillsly-prod",
  "venture_name": "Quillsly",
  "operator_email": "[email protected]",
  "install_origin": "https://emmett.meridian.llc"
}

Response body:

{
  "ok": true,
  "data": {
    "scoped_token": "qws_live_a1b2c3...",
    "drive_workspace_id": "qws_01HXYZ...",
    "metadata": {"mount_url": "https://app.quillsly.com/w/qws_01HXYZ..."}
  },
  "meta": {"version": "v1", "generated_at": "2026-04-19T12:00:00Z"}
}

7. HMAC signing reference

Verbatim from src/meridian/hmac.js. Any mainstream language reproduces this in ~15 lines. Don't reinvent.

const crypto = require('crypto');
const MAX_SKEW_MS = 5 * 60 * 1000;

function signRequest({ path, secret, now }) {
  const ts = String(now == null ? Date.now() : now);
  const sig = crypto.createHmac('sha256', secret)
    .update(`${ts}:${path}`).digest('hex');
  return {
    'x-meridian-timestamp': ts,
    'x-meridian-signature': sig,
  };
}

function verifyRequest({ path, headers, secret, now }) {
  const ts = headers['x-meridian-timestamp'];
  const sig = headers['x-meridian-signature'];
  if (!ts || !sig) return { ok: false, reason: 'missing_signature_headers' };
  if (Math.abs((now || Date.now()) - Number(ts)) > MAX_SKEW_MS) {
    return { ok: false, reason: 'stale_timestamp' };
  }
  const expected = crypto.createHmac('sha256', secret)
    .update(`${ts}:${path}`).digest('hex');
  const a = Buffer.from(sig, 'hex');
  const b = Buffer.from(expected, 'hex');
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return { ok: false, reason: 'bad_signature' };
  }
  return { ok: true };
}

Timestamp is milliseconds, not seconds. Signature is lowercase hex with no prefix. timingSafeEqual is non-negotiable.

8. Events — what to emit

Drives emit events for Merkava's rollup. Every event is a JSON row on GET /api/meridian/events.

• install_created / install_revoked — install lifecycle.
• user_signup — new end-user on the Drive's standalone side.
• subscription_started / subscription_canceled — paid plan lifecycle.
• article_generated, brief_created — Quillsly examples.
• audit_completed, fix_committed — Beacon examples.
• message_received — Relay example.

Events are append-only. Duplicating an event by ID is fine (idempotent); changing its data after emission is not.

9. Dual-mode design system

Standalone: ship your own design system. Quillsly's is Quires (Library Dusk: Fraunces + Manrope, amber on dark green). Pick your own palette, typography, ornament language. Do not copy Graphite Dawn — that's Merkava's.

Merkava-mounted: respect Merkava's chrome. Two territorial cues are permitted — a 2 px accent stripe along the top edge of the content area, and your display typeface on section headers inside your routes. Everything else uses Graphite Dawn tokens.

10. Pricing model

First-party Drives: own pricing, with the standard policy that Merkava-network customers pay less than open-market. Quillsly: $39/mo inside Merkava, $49/mo standalone on quillsly.com. Beacon: $99/mo (no standalone yet). Every future Drive follows the same pattern.

Third-party Drives: 70/30 in favor of the author. Per-install billing via Merkava; paid monthly. Or opt into author-billing — 100% to the author, Merkava charges a flat listing fee. Free Drives ship free.

11. Reference implementations

• Quillsly — github.com/everettsteele/quillsly. Standalone + Merkava-mounted content Drive. Full manifest, install handshake, metrics/events/billing endpoints. The most complete reference.
• Beacon — inside Merkava Core (src/audits/*). Built-in Drive demonstrating "ship the fix, not just the finding" — SEO/GEO audits produce repo commits.
• Relay — relay-production.up.railway.app. Support-chat Drive. Demonstrates scoped-token issuance for embeddable widgets.

Study Quillsly first. It's the fullest build and the one every third-party Drive should aim to match.

12. Developer portal stub

developers.withmerkava.com is coming. It will host the SDK (@meridian-hq/drive-sdk), a manifest validator, a signing-key generator for local dev, and the submission pipeline for Garage review. Until the portal ships, third-party Drive submissions are handled by emailing [email protected] with a link to your manifest URL.

13. What NOT to build

• Never call out to LLM providers by name in user-facing copy. Your Drive is the subject. Inference uses whatever it uses; the UI talks about what the Drive does.
• Never collide with Merkava Core's routes. Mount your routes under a namespace your Drive owns.
• Never store operator credentials beyond scoped_token. Request extra permissions explicitly in permissions_requested.
• No third-party analytics reading operator data. Marketing-site trackers are fine; instrumenting operator workflows is not.

14. Versioning

v1 is current. Every Drive running today implements v1. Backward-compatible changes ship as v1.x — new optional manifest fields, new event kinds, new endpoints — and existing Drives keep working. Breaking changes would be v2; none planned. If v2 ever happens, Merkava Core will run v1 and v2 side-by-side through a minimum 6-month deprecation window.

Drives declare the version they implement in the manifest's contract_version field.

Drive Author spec — questions, plainly answered.

Ready to build?