SDK Discoverability & AI-Driven Vertical App Builder

1 · TL;DR

ProjexCloud's ~70 cross-cutting SDKs (identity, tenancy, billing, audit, AI gateway, evidence chain, geo, dispatch, …) are useless if a tenant developer has to grep source to find them. P9 fixes that by turning the SDK catalog into a machine-readable, AI-consumable platform. The architecture is four cooperating layers:

2 · Why auto-discovery, why now

After P1–P8 the SDK stack is broad enough that the bottleneck to ProjexCloud's growth is no longer features — it is composability. A tenant who signs up today gets an empty workspace; the only way to actually build something is to clone the monorepo and learn ~70 packages. That doesn't scale to thousands of tenants.

The MCP ecosystem (Anthropic, Cursor, Windsurf, Cline) has converged on a stable protocol over the last 6 months. Building on it now means every AI coding tool, present and future, becomes a ProjexCloud entry point with no per-tool plugin. Delay means: every onboarding burns operator hours, the AI-native window closes as competitors ship their own MCP catalogs, and the P8 vertical packs (Healthcare, FinServ, Public Sector) have no surface to materialize on.

3 · The four-layer architecture

4 · Layer 1 — Capability Manifests

The sdk-capability.json file is the foundation of the whole stack. If a manifest doesn't exist, the SDK doesn't exist to the AI. If a manifest is wrong, the AI suggests it for the wrong things. The schema is versioned (schema_version: "1.0"); future bumps are backward-compatible or carry a migration.

4.1 — Manifest anatomy

{
  "schema_version": "1.0",
  "name": "sdk-consent",
  "version": "1.4.2",
  "summary": "GDPR/CCPA consent receipts with cryptographic proof, double opt-in flows, and revocation propagation.",
  "tags": ["privacy", "gdpr", "ccpa", "consent", "compliance"],
  "provides": {
    "endpoints": ["POST /v1/consent", "GET /v1/consent/:subject"],
    "events":    ["consent.granted.v1", "consent.revoked.v1"],
    "models":    ["ConsentReceipt", "ConsentScope"],
    "hooks":     ["beforeConsentGrant", "afterConsentRevoke"],
    "ui_components": ["<ConsentBanner/>", "<ConsentPreferences/>"]
  },
  "consumes": {
    "events":      ["identity.subject.created.v1"],
    "infra":       ["sdk-audit", "sdk-vault"],
    "config_keys": ["CONSENT_DEFAULT_TTL_DAYS"]
  },
  "scenarios": [
    {
      "id": "gdpr-receipt",
      "title": "Issue a GDPR-compliant consent receipt",
      "when_to_use": "Customer opts in to marketing email; you must store proof.",
      "example_code": "await consent.grant({ subject, scope: 'marketing.email' });",
      "expected_outcome": "Hash-anchored receipt; event emitted; revocation honored within 30 days."
    }
    /* … 2–4 more scenarios … */
  ],
  "compliance_posture": {
    "regimes": ["GDPR", "CCPA", "SOC2"],
    "notes":   "Receipts hash-anchored into sdk-audit chain."
  },
  "pool_placement": "app",
  "pricing_skus":   [{ "sku": "consent.receipt", "mode": "metered", "unit_description": "per receipt issued" }],
  "links": {
    "readme":      "packages/sdk-consent/README.md",
    "source":      "packages/sdk-consent",
    "prd_section": "P3#consent"
  }
}

4.2 — Authoring economics

Hand-writing 70 manifests was the single biggest risk (R-1 in the PRD). It is mitigated by splitting the work:

4.3 — CI gate (the no-exceptions rule)

# .github/workflows/registry-validate.yml (excerpt)
- name: Validate every manifest
  run: pnpm registry:validate
  # Fails the build with structured errors:
  #   MANIFEST_MISSING  packages/sdk-foo          (no sdk-capability.json)
  #   MANIFEST_INVALID  packages/sdk-bar/v1.0.0   (summary > 500 chars)
  #   SCENARIO_TBD      packages/sdk-baz#sc-2     (example_code contains "TBD")

This gate codifies Architecture Doctrine §C — Capability-First SDK Authoring: every new SDK ships its manifest at v1.0. No exceptions.

5 · Layer 2 — Registry & Embedding Index

The registry is two artifacts produced by one build job:

5.1 — Why bge-small-en-v1.5

Open question Q-1 (locked 2026-05-25) chose bge-small-en-v1.5 loaded via @huggingface/transformers as INT8-quantized ONNX. Three properties matter:

• In-process. ~33 MB on disk, ~150 MB resident. Runs inside both the hosted MCP and the CLI-bundled local MCP — no separate inference service, no per-query API cost.
• Offline-capable. The same model that built the index runs on the developer's laptop, so search_sdks still works with no network — required for AC-12.
• On-par recall. For a 70-SDK corpus its precision@3 matches text-embedding-3-small within noise, while saving ~$140/mo at projected traffic.

5.2 — Public API surface

// @projexlight/sdk-registry
export interface Registry {
  list(): SdkCapabilityManifest[];
  get(sdk_name: string): SdkCapabilityManifest | null;
  searchByIntent(query: string, top_k?: number): Promise<RegistryHit[]>;
  findCompatibleSdks(sdk_name: string): string[];
  getScaffold(sdk_names: string[], app_name: string): ScaffoldTree;
}
export function loadRegistry(catalogPath?: string): Promise<Registry>;

6 · Layer 3 — MCP Server (Hosted + Local Split)

The MCP layer is where the architecture's most consequential design decision lives: split into two cooperating binaries that share one wire protocol.

6.1 — Side-by-side

6.2 — How the same wire protocol works both ways

6.3 — Tool catalog (what AI tools see)

6.4 — Offline behavior

When the hosted side is unreachable, the local MCP gracefully degrades per FR-MCP-L5:

• Read tools — answer from ~/.projex/cache/. AI tool notices nothing.
• Write tools — return a structured error: { status: "queued", queued_id: ... }. The CLI surfaces projex deploy --queue hints. On reconnect, projex registry drain replays queued operations.

AC-12 enforces this in chaos tests: network down → all reads succeed → write queues → reconnect → queue drains within 30 s with byte-identical results to an online write.

7 · Layer 4a — The CLI / IDE path (Claude Code, Cursor, Windsurf)

This is the path most tenant developers will take. It is built around zero-configuration auto-discovery: the developer never reads the SDK list, never edits MCP configs by hand, and never has to know which region their tenant lives in.

7.1 — The first-run flow

7.2 — What projex init actually writes

// .claude/mcp.json — auto-generated by `projex init`
{
  "mcpServers": {
    "projex_registry": {
      "command": "npx",
      "args": ["-y", "@projexlight/registry-mcp-local"],
      "env": {
        "PROJEX_HOSTED_MCP": "https://mcp.us-east.projexcloud.com",
        "PROJEX_TENANT_ID":  "tenant_01HXY...",
        "PROJEX_KEYCHAIN_REF": "projex.tenant_01HXY"
      }
    }
    // If Projexlight is detected on this machine, projex_dev_mcp and
    // projex_test_mcp blocks are appended here too (see §10 Cohabitation).
  }
}

7.3 — The full CLI surface

8 · Layer 4b — The Cloud Builder path (non-developers)

The Cloud Builder is the same substrate aimed at a different persona: a non-developer in a tenant who wants a working application without filing an IT ticket. It lives at /build inside the tenant workspace.

8.1 — Anatomy of a build session

8.2 — The guardrail layer (where safety actually lives)

The agent does not enforce safety. The agent is treated as untrusted prompt-pipe; real enforcement happens server-side in two places:

8.3 — Cost shaping (Q-4 decision)

9 · The auto-discovery mechanism — how it actually works

This is the part the user most cares about. Auto-discovery isn't one mechanism — it is a chain of four discrete handshakes that compose into the experience of "the AI just knew what was available." Each handshake is independently observable and independently testable.

9.1 — Handshake 1: CLI detects installed AI tools

When projex init runs, the CLI looks for marker files in the user's home directory:

// @projexlight/cli — detection logic (sketch)
const DETECTORS = {
  "claude-code": () => existsSync(path.join(os.homedir(), ".claude")),
  "cursor":      () => existsSync(path.join(os.homedir(), ".cursor")),
  "windsurf":    () => existsSync(path.join(os.homedir(), ".windsurf")),
  "cline":       () => existsSync(path.join(os.homedir(), ".cline")),
  // Projexlight cohabitation marker — see §10
  "projexlight": () => existsSync(path.join(os.homedir(), ".projexlight", "config.json")),
};
const installed = Object.entries(DETECTORS).filter(([_, fn]) => fn()).map(([k]) => k);

The CLI writes configs only for the tools actually installed. Order matters: detection is per-machine, but every AI client ends up seeing the same MCP tool catalog.

9.2 — Handshake 2: CLI writes per-tool MCP config

Each AI tool has its own config path; the CLI knows them all and writes the matching block. Critical property: the CLI is the only sanctioned writer of these files. If a user hand-edits, the next projex init warns rather than overwrites. This avoids the "two MCPs in Claude Code config confuse non-technical users" failure mode (R-11).

9.3 — Handshake 3: AI tool launches local MCP and lists tools

This handshake is standard MCP, no ProjexCloud customization. When the IDE starts, it spawns npx @projexlight/registry-mcp-local as a stdio child process, exchanges the MCP initialize handshake, then calls tools/list. The local MCP responds with the tool catalog defined in §6.3 — read tools backed by the local cache, write tools that proxy to the hosted side.

// MCP initialize handshake (excerpt of stdio JSON-RPC)
> { "jsonrpc": "2.0", "id": 1, "method": "initialize",
>   "params": { "protocolVersion": "2025-03-26",
>               "capabilities": { "tools": {} },
>               "clientInfo": { "name": "claude-code", "version": "1.x" } } }
< { "jsonrpc": "2.0", "id": 1, "result":
<   { "protocolVersion": "2025-03-26",
<     "serverInfo": { "name": "projex-registry-local", "version": "1.0.0" },
<     "capabilities": { "tools": { "listChanged": true } } } }

> { "jsonrpc": "2.0", "id": 2, "method": "tools/list" }
< { "jsonrpc": "2.0", "id": 2, "result":
<   { "tools": [
<     { "name": "projex_registry_search_sdks",      "description": "...", "inputSchema": { ... } },
<     { "name": "projex_registry_get_manifest",     "description": "...", "inputSchema": { ... } },
<     { "name": "projex_registry_scaffold",         "description": "...", "inputSchema": { ... } },
<     ...
<   ] } }

9.4 — Handshake 4: AI tool queries by intent → registry returns relevant SDKs

This is the handshake users feel. When the developer types "I need consent receipts for GDPR", the AI tool decides (based on the tool descriptions in §9.3) to call projex_registry_search_sdks(query: "consent receipts for GDPR"). The local MCP:

1. Embeds the query with bge-small-en-v1.5 in-process (~5 ms).
2. Searches the HNSW index over (sdk_name, scenario_id) vectors (~2–10 ms).
3. Returns top-K hits with score, scenario excerpt, and a "why this matched" snippet.

// Sample response (top 3 of K=5)
{
  "hits": [
    { "sdk_name": "sdk-consent", "scenario_id": "gdpr-receipt", "score": 0.91,
      "summary": "GDPR/CCPA consent receipts with cryptographic proof...",
      "why_match": "scenario 'gdpr-receipt' matches 'consent receipts for GDPR'" },
    { "sdk_name": "sdk-privacy",  "scenario_id": "dsar-flow",     "score": 0.74, "...": "..." },
    { "sdk_name": "sdk-audit",    "scenario_id": "evidence-anchor","score": 0.68, "...": "..." }
  ]
}

AC-3 enforces this works: a 50-query test suite must hit precision@3 ≥ 0.9 with the target SDK in the top 3. Quarterly catalog-quality audits widen the suite to 200 queries and trigger manifest rewrite PRs when precision regresses.

10 · End-to-end build flows

10.1 — Building a vertical app from scratch (CLI path)

10.2 — Building a vertical app from a prompt (Cloud path)

10.3 — The unified picture

Both paths end up in the same place: a scaffolded application running in the tenant's app pool, with every step in the audit chain, every tool call metered, and every guardrail enforced server-side. The difference is the orchestrator (developer-with-IDE vs. agent-with-prompt), not the substrate.

11 · Cohabitation with existing Projexlight MCPs

ProjexCloud's new registry-mcp-local is a peer, not a replacement, of the existing Projexlight MCPs at projex_mcp/projex_dev_mcp and projex_mcp/projex_test_mcp. They expose disjoint tool catalogs and zero-collision names.

11.1 — One config, all MCPs

When projex init detects ~/.projexlight/config.json, it writes a single .claude/mcp.json (and equivalents) that registers both Projexlight MCPs and the new registry-mcp-local. The AI client sees all three in one tool list and routes calls by name.

// .claude/mcp.json — Projexlight + ProjexCloud cohabiting
{
  "mcpServers": {
    "projex_registry": {
      "command": "npx", "args": ["-y", "@projexlight/registry-mcp-local"],
      "env": { "PROJEX_HOSTED_MCP": "https://mcp.us-east.projexcloud.com" }
    },
    "projex_dev": {
      "command": "docker", "args": ["run", "--rm", "-i", "projexlight/projex_dev_mcp:latest"]
    },
    "projex_test": {
      "command": "docker", "args": ["run", "--rm", "-i", "projexlight/projex_test_mcp:latest"]
    }
  }
}

AC-13 enforces this works: load all three in one Claude Code session, invoke projex_registry_search_sdks and projexlight_create_feature in the same conversation, both succeed.

11.2 — Projexlight-on-ProjexCloud — the dogfood proof

The prd-management blueprint (FR-DF-1..5) rebuilds Projexlight's PRD/feature/ scenario/task surface as a vertical app composed from ProjexCloud SDKs. Projexlight retains its proprietary AI-review IP (as a private SDK), but every cross-cutting concern (multi-tenancy, identity, billing, audit, webhooks, approvals, RAG search, AI gateway) is delegated to ProjexCloud SDKs.

12 · Security, guardrails, compliance

12.1 — The five non-negotiables

1. Writes never happen client-side. Local MCP can queue, never commit.
2. Every write is audited before it succeeds. Audit failure = write failure.
3. Pack guardrails are policy, not prompt. Agent can't talk its way out.
4. Confirm-by-default for non-dev users. Autonomous mode is opt-in and $ -capped.
5. Catalog is single-source-of-truth across hosted + local. Cache mismatches are detected at install time and refuse to scaffold removed SDKs (R-10 mitigation).

13 · Component glossary

13.1 — Key NFRs at a glance

13.2 — Related companion docs

• Architecture-v3.1.html — overall ProjexCloud architecture & doctrines
• SDK-Build-Plan-v3.1.html — SDK roadmap that ~70 manifests will describe
• AgenticIntegration-v3.1.html — agent runtime, AI gateway, MCP bridge details
• ProjectStructure-v3.1.html — monorepo layout (where manifests live)
• prd/P9-SDK-Discoverability-AI-Builder.md — source PRD for this architecture

14 · v3.2 (P9.2) — RAG Catalog Store, Payload Contracts & Planner v2

The original L2 registry (§5) is a build-time file artifact: a normalized registry.catalog.json plus an embeddings.bin, scanned once and shipped. The first tenant-facing planner at /build took the cheapest possible shortcut on top of it — it loaded all ~90 manifests, trimmed them, and pasted the entire catalog into one LLM prompt, then trusted the model to pick. Three problems surfaced in production:

14.1 — L2 evolves into a Postgres + pgvector RAG store

The catalog stops being only a file and becomes an auto-populated, auto-refreshed table in the global-catalog pool (SDK manifests are identical for every tenant, so this is global state — not per-tenant rag.* corpus). The existing migration-runner auto-creates the schema on boot (no manual SQL), and a sync job reuses the sdk-registry scanner to keep it fresh.

-- catalog schema · global-catalog pool · auto-created by migration-runner
CREATE TABLE catalog.sdk (
  name           text PRIMARY KEY,          -- @projexlight/sdk-billing
  summary        text NOT NULL,
  tags           text[] NOT NULL DEFAULT '{}',
  tier           text,                       -- 'foundation' | 'domain'  (drives §14.3 injection)
  content_hash   text NOT NULL,              -- sha256(manifest) -> skip unchanged on resync
  updated_at     timestamptz NOT NULL DEFAULT now()
);
CREATE TABLE catalog.endpoint (
  id             uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  sdk_name       text NOT NULL REFERENCES catalog.sdk(name) ON DELETE CASCADE,
  method         text NOT NULL,
  path           text NOT NULL,
  kind           text NOT NULL DEFAULT 'query',  -- NEW: ingest|bulk|query|mutation|webhook
  request_schema  jsonb,                          -- NEW: JSON Schema of the body
  response_schema jsonb,                          -- NEW
  auth_scopes    text[] DEFAULT '{}',             -- NEW: e.g. {billing:write}
  UNIQUE (sdk_name, method, path)
);
CREATE TABLE catalog.embedding (
  ref_kind   text NOT NULL,                  -- 'sdk' | 'endpoint' | 'scenario' | 'ingest'
  ref_id     text NOT NULL,
  card       text NOT NULL,                  -- the NL text that was embedded
  embedding  vector(384) NOT NULL            -- bge-small space; SEPARATE from the 1536 template
);
CREATE INDEX ON catalog.embedding USING hnsw (embedding vector_cosine_ops);

14.2 — Closing the two gaps: payload contracts & the ingest dimension

14.3 — Planner v2: retrieve-then-compose + foundation-tier + dependency closure

The /build planner is rebuilt as a pipeline. Crucially, semantic retrieval alone is insufficient for cross-cutting concerns: a user who types "a financial accounting system" never says "login," so the embedding of the intent is nowhere near the embedding of sdk-identity. Two deterministic resolvers run between retrieve and compose to guarantee the auth/AIM foundation always surfaces.

14.4 — The agent hot path: no-latency tiers

An interactive coding agent must never round-trip to Postgres per query. The store is the durable source-of-truth and freshness signal; the hot path is an in-process index.

Vectors for "which," relational for "exact payload," in-memory for "fast," Postgres for "fresh + shared."

14.5 — Build phases (maps to the P9.2 delivery epics)