@b1-road/integrate

The Road integration skill — a distributed, self-verifying agent that takes a partner's app from zero to a working, verified Road integration without a Road engineer in the loop. It routes by stack, scaffolds the BFF + permission checks the Dev Portal doesn't generate, and refuses to claim success until a real login round-trip passes against the live sandbox.

This is not a published wire SDK. It carries no wire types and is not part of the sdk-sync / SDK-version gates (those guard road-types, road-react, road-nestjs). It is a sibling artifact: the SDKs are what a partner installs; this is the agent that wires them in correctly. The canonical design lives in docs/plans/19-road-integration-skill.md.

What's here

road-integrate/
├── README.md            ← this file (the package)
├── package.json         ← @b1-road/integrate — the npx wrapper (no build step)
├── bin/
│   └── integrate.mjs    ← the CLI: drops skill/ into a repo + pre-seeds context
└── skill/               ← the bundle dropped into a partner repo as .claude/skills/road-integration/
    ├── SKILL.md         ← the brain: detect → route → pre-compute → scaffold → VERIFY → hand off
    ├── VERSION          ← bundle version, for the self-staleness check
    ├── references/      ← stack recipes + the seams the SKILL routes to
    │   ├── nestjs.md · react.md · laravel.md
    │   ├── portal-handoff.md   ← the provisioning seam (guided + Playwright co-drive; the Tier-2 request)
    │   ├── verify.md           ← the hard verification gate
    │   ├── brownfield.md       ← detect existing auth (v1 stops); the v2 migration shape
    │   └── sources.md          ← sources of truth (live OpenAPI, types, installed SDK) + canonical Road URLs
    └── context/
        └── platform.example.json  ← the pre-seed descriptor shape the install fills (never the clientSecret)

Why a skill and not a doc

A SKILL.md that restated how to integrate would be a third copy of knowledge that already lives in the SDK READMEs and the docs site — and a third thing to drift. This skill refuses that. It distributes a live generator: it reads shapes from the installed SDK and the live OpenAPI (current by construction), not from baked-in snippets. The orchestration — the portal handoff and the verification gate — is the part a doc can't do. See skill/references/sources.md.

It is held to the same bar as the SDKs: standards/SDK_DX_BAR.md. The imperative is the DX bar applied to the integration act itself: authenticated + authorized + calling Road in minutes, from the partner's own repo.

Using it (CLI)

npx @b1-road/integrate                 # install the skill into this repo
npx @b1-road/integrate plat_7f3a…      # install + pre-seed from your platform id

| Option | Effect | | --- | --- | | plat_… (positional) | Platform id from the Dev Portal; pre-seeds context/platform.json. | | --api <url> | Road API base (default https://api.road-sandbox.b1.app). | | --dir <path> | Target repo root (default: cwd). | | -y, --yes | Overwrite an existing install without asking. | | -v, --version · -h, --help | Bundle version · usage. |

It's a dependency-free Node 18+ script — npx runs it with zero install and the partner can read every line. With a platform id it derives the issuer from the one public endpoint and writes the non-secret descriptor; the clientSecret is never written to a file or a command line.

Distribution (v1)

The npx @b1-road/integrate <platformId> above drops the skill/ bundle into the partner's repo as .claude/skills/road-integration/ — IDE-agnostic files that Claude Code, Cursor, and Windsurf all read. Two doorways:

• Dev Portal install card (primary) — renders the one-liner with the platform id baked in, so the dropped skill starts knowing the partner's permission catalog, client id, and issuer (from the public descriptor). Secrets never go through argv — the clientSecret is shown once in the portal and pasted into .env by the human.
• Generic npx — the same run by hand for partners not coming through the portal.

A managed Claude Code plugin / marketplace (auto-update, discovery) is the v2 distribution path; v1 stays an inspectable, re-runnable npx drop. The bundle self-checks its VERSION against the latest published package and advises a re-run when behind (non-blocking) — see skill/SKILL.md → Staying current.

Headless pre-seed

The install pre-fills context/platform.json from two public, unauthenticated reads, so the dropped skill starts knowing the partner's platform without a session:

• GET /api/alpha/platforms/:publicId/descriptor → { data: { id, name, slug, status, clientId, permissionTemplate, roleTemplate } } — the platform's public descriptor (added in this PR; see apps/api/.../registry/controllers/public-platform.controller.ts).
• GET /api/alpha/iam/identity/auth/config → { data: { issuer, projectId } } — the global issuer.

What still needs the human: the clientSecret (shown once in the portal, pasted into .env — never on argv or in a file) and, if the install ran before a credential was issued, the clientId. The redirect URI the skill computes itself. The descriptor deliberately omits redirectUris (they live at the Auth Server and would force an outbound call on an unauthenticated endpoint) — out of scope, not a gap.

Developing the bundle

The bundle is plain Markdown + JSON — no build step. Keep it grounded:

• Recipes mirror the current SDK READMEs (apps/sdks/road-{nestjs,react,laravel}/README.md). When an SDK README changes a public snippet, re-check the matching recipe.
• Shapes and URLs belong in references/sources.md, sourced from the live OpenAPI and @b1-road/types — don't scatter hardcoded shapes through recipes.
• Bump skill/VERSION (and the package version) when the orchestration changes, so the self-staleness check fires for partners on an older drop.

Honor the same guardrails the bundle enforces: refer to the identity provider only as the Auth Server (never its underlying product name), keep Road's internal and experimental modules out entirely, and reflect the { data } envelope / camelCase / cursor pagination / action:Subject algebra.