create-rakomi-app 0.1.1 → 0.2.0

package/README.md

@@ -3,6 +3,16 @@
 Scaffold a [Rakomi](https://rakomi.com) quickstart app in seconds. Rakomi is EU-native
 authentication as a service.
 
+## Ask your agent
+
+Add the Rakomi MCP server to your coding agent, then ask it directly:
+
+```sh
+claude mcp add --transport http rakomi https://mcp.rakomi.com/mcp
+```
+
+"List the AI agents connected to my Rakomi tenant."
+
 ## Getting started
 
 ```sh
@@ -35,6 +45,8 @@ npm create @rakomi/rakomi-app@latest -- --template nextjs my-app
 | `--tenant-id <value>`     | your tenant id                                     |
 | `--template-source <url>` | override the archive base (mirror / offline)       |
 | `--yes`                   | accept defaults, never prompt (non-interactive)    |
+| `--connect`               | print next steps for connecting an AI agent (the `rakomi` CLI) |
+| `--no-mcp`                | skip scaffolding `.mcp.json` / `AGENTS.md` (written by default) |
 | `-h`, `--help`            | show help                                          |
 | `-V`, `--version`         | print the version                                  |
 
@@ -43,6 +55,11 @@ local `.env` in the new project. Value precedence is: flag > environment variabl
 default. In a non-interactive context (a pipe, a continuous-integration job, or `--yes`) it never
 blocks — it uses flags / environment values / defaults and leaves the rest for you to fill in.
 
+A project-scope `.mcp.json` and an `AGENTS.md` briefing are scaffolded alongside your new app by
+default, so it is agent-ready on first run — open it in Claude Code and run `claude mcp login rakomi`
+to finish sign-in, or point any other AI coding agent at `AGENTS.md` for the same information (the
+MCP server URL, the connect step, and where credentials live). Pass `--no-mcp` to skip both files.
+
 `RAKOMI_REGION` defaults to `eu-central` — a visible data-residency stance, not a mandate. Override
 it with `--region` or the `RAKOMI_REGION` environment variable for any other region.
 

package/SECURITY.md

@@ -9,8 +9,8 @@ While these packages remain pre-1.0 (`0.x`), they carry **no stability or suppor
 (SemVer 2.0.0 §4); the latest `0.x` line receives security updates on a best-effort basis.
 
 From version **1.0** onward, Rakomi maintains the current (N) and previous (N-1) MAJOR in parallel, with N-1 receiving
-security-only fixes. The CRA support period for each MAJOR is determined in accordance with
-**CRA Art. 13(8)** — at least five years, or the product's expected use time where shorter. The authoritative, machine-readable support windows are published at
+security-only fixes. For each MAJOR version of the Rakomi SDKs, CRE8EVE commits to a CRA support period of
+**at least five years (60 months)**, meeting the support-period requirement of **CRA Art. 13(8)**. The authoritative, machine-readable support windows are published at
 [`https://api.rakomi.com/.well-known/sdk-support.json`](https://api.rakomi.com/.well-known/sdk-support.json)
 and rendered for humans on the [SDK Support & Lifecycle page](https://rakomi.com/sdk-support). This
 document points at that single source rather than re-typing dated rows.

package/dist/agent-context.js

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: MIT
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { RAKOMI_SERVER_NAME } from './client-registry.generated.js';
+import { ENV_KEYS } from './env.js';
+import { CLAUDE_CODE_CLIENT, MCP_URL } from './mcp-config.js';
+/** The agent-context filename this module writes, at the project root. */
+export const AGENT_CONTEXT_FILENAME = 'AGENTS.md';
+/**
+ * `{{MCP_URL}}` and `{{SERVER_NAME}}` are the registry's own placeholder tokens (`mcp-clients.json`)
+ * — substituted here, never baked into the generated module, so one registry entry serves every
+ * environment's MCP URL. The scaffolder always writes the default server name, so that is what the
+ * rendered instruction names. Mirrors `packages/cli/src/commands/connect.ts`'s helper and contract.
+ */
+function withMcpUrl(instruction, mcpUrl) {
+    return instruction.replaceAll('{{MCP_URL}}', mcpUrl).replaceAll('{{SERVER_NAME}}', RAKOMI_SERVER_NAME);
+}
+/**
+ * Render `AGENTS.md`'s full body for a freshly scaffolded project. Pure and deterministic (no
+ * timestamps, no random ids, no directory/template name) so the golden-content test can assert
+ * byte-for-byte output regardless of which template or target directory the scaffold used.
+ */
+export function agentContextMarkdown() {
+    const envKeyList = ENV_KEYS.map((k) => `\`${k}\``).join(', ');
+    return ([
+        '# Rakomi integration',
+        '',
+        'This project is wired to a Rakomi MCP server, so an AI coding agent working in this repository',
+        'can read and manage this tenant on your behalf, once you connect it.',
+        '',
+        '## MCP server',
+        '',
+        `- URL: \`${MCP_URL}\``,
+        '- Config: `.mcp.json` (already scaffolded in this project root)',
+        '',
+        '## Connect',
+        '',
+        withMcpUrl(CLAUDE_CODE_CLIENT.finishInstruction, MCP_URL),
+        '',
+        '## Credentials',
+        '',
+        `Tenant credentials live in \`.env\` (${envKeyList}) — never in this file, never in chat, and`,
+        'never committed (`.env` is not tracked by version control). An agent reading this project',
+        'should read values from `.env`, not ask you to paste them.',
+        '',
+        '## Ask your agent',
+        '',
+        '> "Connect to my Rakomi tenant using .mcp.json and show me my current users."',
+        '',
+    ].join('\n') + '\n');
+}
+/**
+ * Write `AGENTS.md` into the freshly scaffolded project root. Always writes unconditionally when
+ * called (gated by the same `--no-mcp` opt-out as `.mcp.json` at the call site, `index.ts`) — a
+ * fresh quickstart template never ships its own `AGENTS.md` (verified by
+ * `test/agent-context.test.ts`'s manifest scan), so there is nothing to merge and nothing to
+ * clobber. LF-terminated, the same convention every other writer in this package uses.
+ */
+export async function writeAgentContext(targetDir) {
+    await writeFile(join(targetDir, AGENT_CONTEXT_FILENAME), agentContextMarkdown(), 'utf8');
+}

package/dist/client-registry.generated.js

@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: MIT
+export const RAKOMI_SERVER_NAME = "rakomi";
+export const CLIENT_REGISTRY = [
+    {
+        id: "claude-code",
+        displayName: "Claude Code",
+        tier: "written",
+        status: "verified",
+        finishInstruction: "1. Run `claude` in this directory and approve the \"{{SERVER_NAME}}\" project server when prompted.\n2. Then run `claude mcp login {{SERVER_NAME}}` to finish sign-in in your browser (or use `/mcp` inside that session).",
+        config: {
+            scope: "project",
+            pathTemplate: ".mcp.json",
+            serialization: "json",
+            topLevelKey: "mcpServers",
+            remoteUrlField: "url",
+            extraFields: { "type": "http" },
+        },
+        evidenceUrl: "https://code.claude.com/docs/en/mcp",
+    },
+    {
+        id: "vscode",
+        displayName: "VS Code",
+        tier: "written",
+        status: "documented-shape-only",
+        finishInstruction: "Open the Command Palette and run \"MCP: List Servers\", or the Extensions view — VS Code starts the OAuth flow automatically the first time it connects.",
+        config: {
+            scope: "project",
+            pathTemplate: ".vscode/mcp.json",
+            serialization: "json",
+            topLevelKey: "servers",
+            remoteUrlField: "url",
+            extraFields: { "type": "http" },
+        },
+        evidenceUrl: "https://code.visualstudio.com/docs/agents/reference/mcp-configuration",
+    },
+    {
+        id: "cursor",
+        displayName: "Cursor",
+        tier: "written",
+        status: "documented-shape-only",
+        finishInstruction: "Open Cursor's MCP settings and connect — for a server that supports OAuth, Cursor completes the flow for you (or accepts static client credentials in mcp.json instead of dynamic client registration).",
+        config: {
+            scope: "project",
+            pathTemplate: ".cursor/mcp.json",
+            serialization: "json",
+            topLevelKey: "mcpServers",
+            remoteUrlField: "url",
+            extraFields: {},
+        },
+        evidenceUrl: "https://cursor.com/docs/mcp",
+    },
+    {
+        id: "antigravity",
+        displayName: "Google Antigravity",
+        tier: "written",
+        status: "documented-shape-only",
+        finishInstruction: "Open the MCP Store or your MCP settings in Antigravity — it handles OAuth automatically for servers that support dynamic client registration (DCR).",
+        config: {
+            scope: "project",
+            pathTemplate: ".agents/mcp_config.json",
+            serialization: "json",
+            topLevelKey: "mcpServers",
+            remoteUrlField: "serverUrl",
+            extraFields: {},
+        },
+        evidenceUrl: "https://antigravity.google/docs/ide/mcp/",
+    },
+    {
+        id: "gemini-cli",
+        displayName: "Gemini CLI",
+        tier: "written",
+        status: "documented-shape-only",
+        finishInstruction: "Run `gemini mcp list`, or just start a session — the Gemini CLI supports OAuth 2.0 for remote MCP servers and negotiates it automatically.",
+        config: {
+            scope: "project",
+            pathTemplate: ".gemini/settings.json",
+            serialization: "json",
+            topLevelKey: "mcpServers",
+            remoteUrlField: "httpUrl",
+            extraFields: {},
+        },
+        evidenceUrl: "https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html",
+    },
+    {
+        id: "zed",
+        displayName: "Zed",
+        tier: "written",
+        status: "documented-shape-only",
+        finishInstruction: "Open Settings -> AI -> MCP Servers in Zed — when a remote server has no Authorization header configured, Zed prompts you to authenticate with the standard MCP OAuth flow.",
+        config: {
+            scope: "project",
+            pathTemplate: ".zed/settings.json",
+            serialization: "json",
+            topLevelKey: "context_servers",
+            remoteUrlField: "url",
+            extraFields: {},
+        },
+        evidenceUrl: "https://zed.dev/docs/ai/mcp",
+    },
+    {
+        id: "codex-cli",
+        displayName: "OpenAI Codex CLI",
+        tier: "written",
+        status: "documented-shape-only",
+        finishInstruction: "Run `codex mcp login {{SERVER_NAME}}` to finish sign-in in your browser.",
+        config: {
+            scope: "user",
+            pathTemplate: ".codex/config.toml",
+            serialization: "toml",
+            topLevelKey: "mcp_servers",
+            remoteUrlField: "url",
+            extraFields: {},
+        },
+        evidenceUrl: "https://learn.chatgpt.com/docs/extend/mcp?surface=cli",
+    },
+    {
+        id: "devin-desktop",
+        displayName: "Devin Desktop",
+        tier: "written",
+        status: "documented-shape-only",
+        finishInstruction: "Open Devin Desktop — it supports OAuth for each transport type and prompts you to connect the first time.",
+        config: {
+            scope: "user",
+            pathTemplate: ".codeium/windsurf/mcp_config.json",
+            serialization: "json",
+            topLevelKey: "mcpServers",
+            remoteUrlField: "serverUrl",
+            extraFields: {},
+        },
+        evidenceUrl: "https://docs.devin.ai/desktop/cascade/mcp",
+    },
+    {
+        id: "claude-desktop",
+        displayName: "Claude Desktop",
+        tier: "instructed",
+        status: "verified",
+        finishInstruction: "Claude Desktop connects to remote MCP servers through Connectors, configured from your Claude account rather than a local file — there is nothing for `rakomi connect` to write.\n\n1. Open Settings -> Connectors in Claude Desktop and add a custom connector.\n2. Enter Rakomi's MCP server URL: {{MCP_URL}}\n3. Click Connect. Claude Desktop opens your browser at accounts.rakomi.com — sign in and\n   approve the read-only consent screen.",
+        evidenceUrl: "https://support.claude.com/en/articles/11175166-about-custom-connectors-remote-mcp",
+    },
+    {
+        id: "chatgpt",
+        displayName: "ChatGPT",
+        tier: "instructed",
+        status: "documented-shape-only",
+        finishInstruction: "In ChatGPT, go to Workspace Settings -> Permissions & Roles -> Developer mode, then add {{MCP_URL}} as a remote server. ChatGPT starts an OAuth flow to your workspace's identity provider once it's added.",
+        evidenceUrl: "https://developers.openai.com/api/docs/mcp",
+    },
+    {
+        id: "jetbrains",
+        displayName: "JetBrains AI Assistant",
+        tier: "instructed",
+        status: "documented-shape-only",
+        finishInstruction: "In your JetBrains IDE, go to Settings -> Tools -> AI Assistant -> Model Context Protocol (MCP), click Add, and paste: {\"mcpServers\":{\"{{SERVER_NAME}}\":{\"url\":\"{{MCP_URL}}\"}}}\nJetBrains' own documentation does not state whether it drives OAuth for you — be ready to complete sign-in in whatever browser tab it opens.",
+        evidenceUrl: "https://www.jetbrains.com/help/ai-assistant/mcp.html",
+    },
+];
+export const KNOWN_CLIENTS = CLIENT_REGISTRY.map((c) => c.id);

package/dist/env.js

@@ -1,12 +1,86 @@
 // SPDX-License-Identifier: MIT
 import { writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-/** Keys the scaffolder collects, in written order. Names follow `RAKOMI_[A-Z0-9_]+`. */
-export const ENV_KEYS = ['RAKOMI_REGION', 'RAKOMI_TENANT_ID', 'RAKOMI_API_KEY'];
+/**
+ * Keys the scaffolder collects, in written order. Names follow `RAKOMI_[A-Z0-9_]+`.
+ * `RAKOMI_CLIENT_SECRET`/`RAKOMI_REDIRECT_URI` are collected ONLY for the `node` template — see
+ * `NODE_ONLY_KEYS` below; every other template's dev server never reads either.
+ */
+export const ENV_KEYS = [
+    'RAKOMI_REGION',
+    'RAKOMI_TENANT_ID',
+    'RAKOMI_API_KEY',
+    'RAKOMI_CLIENT_ID',
+    'RAKOMI_CLIENT_SECRET',
+    'RAKOMI_REDIRECT_URI',
+    'RAKOMI_ISSUER',
+];
 /** The default EU region — a visible, overridable data-residency stance, not a mandate. */
 export const DEFAULT_REGION = 'eu-central';
-/** Keys whose value is a credential and must never be echoed to stdout / logs / summaries. */
-export const SECRET_KEYS = new Set(['RAKOMI_API_KEY']);
+/** The node quickstart's own `.env.example` default — an OAuth client registered for local dev
+ * typically has this exact redirect URI, so it doubles as a working starting point. */
+export const DEFAULT_NODE_REDIRECT_URI = 'http://localhost:3000/callback';
+/**
+ * Keys whose value is a credential and must never be echoed to stdout / logs / summaries.
+ * `RAKOMI_CLIENT_ID` is deliberately absent — an OAuth client_id is a PUBLIC, publishable
+ * identifier (PKCE public clients ship it in bundled JS), not a secret.
+ */
+export const SECRET_KEYS = new Set(['RAKOMI_API_KEY', 'RAKOMI_CLIENT_SECRET']);
+/**
+ * The `node` quickstart is the only template whose OWN server performs a confidential-client
+ * OAuth code exchange (`examples/quickstarts/node/src/config.ts`) — `RAKOMI_REDIRECT_URI` is
+ * REQUIRED there (`loadConfig()` throws a `ConfigError` at boot without it: the scaffolder used
+ * to omit it entirely, so a freshly-scaffolded node app never started) and `RAKOMI_CLIENT_SECRET`
+ * is read for the confidential-client case node's own README instructs the user to set up
+ * (optional — an unset value degrades to a public/PKCE-only client, per that file's own comment).
+ * Every browser-based template (nextjs/react/expo) drives its OAuth flow through `@rakomi/react`
+ * client-side and never reads either var — collecting/writing them there would be a meaningless
+ * prompt and a dead `.env` line for those templates.
+ */
+const NODE_ONLY_KEYS = new Set(['RAKOMI_CLIENT_SECRET', 'RAKOMI_REDIRECT_URI']);
+/**
+ * `RAKOMI_ISSUER` — the issuer of the environment whose tokens the app accepts (every environment
+ * is its own issuer with its own signing keys). Read, and required at boot / per request, ONLY by
+ * the templates whose own server verifies access tokens: `node` (`src/config.ts`) and `nextjs`
+ * (`src/lib/server/config.ts`). The browser/mobile templates never verify a token themselves.
+ */
+const ISSUER_TEMPLATES = new Set(['node', 'nextjs']);
+/** The keys actually relevant to a given template — `ENV_KEYS` minus the `node`-only keys for
+ * every other template (or an absent/unknown slug — the conservative default), unchanged (full
+ * set) for `node` itself. Drives both what the wizard prompts for (`prompt.ts`'s `collectEnv`)
+ * and what `renderDotenv` writes. */
+export function keysForTemplate(templateSlug) {
+    if (templateSlug === 'node')
+        return ENV_KEYS;
+    return ENV_KEYS.filter((key) => !NODE_ONLY_KEYS.has(key) &&
+        (key !== 'RAKOMI_ISSUER' || (templateSlug !== undefined && ISSUER_TEMPLATES.has(templateSlug))));
+}
+/**
+ * Every scaffolded template reads `RAKOMI_REGION` / `RAKOMI_TENANT_ID` / `RAKOMI_API_KEY` under
+ * their canonical `RAKOMI_*` name — but each template's OWN `.env.example` names its OAuth
+ * `client_id` differently, following that framework's inline-at-build-time convention:
+ * Next.js `NEXT_PUBLIC_*`, Vite `VITE_*`, Expo `EXPO_PUBLIC_*`; a server-only Node app keeps the
+ * plain `RAKOMI_*` form. Writing the collected value under the WRONG name means the app never
+ * reads it and fails with a first-run "missing client" error despite a fully-filled `.env`
+ * (the incident this mapping exists to close). See `examples/quickstarts/{slug}/.env.example`
+ * for the source of truth this table mirrors.
+ */
+const CLIENT_ID_KEY_BY_TEMPLATE = {
+    nextjs: 'NEXT_PUBLIC_RAKOMI_CLIENT_ID',
+    react: 'VITE_RAKOMI_CLIENT_ID',
+    expo: 'EXPO_PUBLIC_RAKOMI_CLIENT_ID',
+    node: 'RAKOMI_CLIENT_ID',
+};
+/**
+ * Resolve the `.env` key NAME a given canonical `EnvKey` must be written under for a specific
+ * template. Only `RAKOMI_CLIENT_ID` varies by template today; every other key keeps its
+ * canonical `RAKOMI_*` name across every template.
+ */
+export function envKeyNameForTemplate(templateSlug, key) {
+    if (key !== 'RAKOMI_CLIENT_ID')
+        return key;
+    return CLIENT_ID_KEY_BY_TEMPLATE[templateSlug] ?? key;
+}
 const CONTROL_CHARS = /[\u0000-\u001F\u007F]/g;
 /**
  * Serialise a single `KEY=value` line in canonical dotenv form:
@@ -23,15 +97,18 @@ export function dotenvLine(key, rawValue) {
     return `${key}="${escaped}"`;
 }
 /**
- * Render a full `.env` body from collected values. Always LF-terminated, one key per line,
- * in `ENV_KEYS` order. A missing value is written as an empty assignment so the file lists
- * every key for the user to complete.
+ * Render a full `.env` body from collected values. Always LF-terminated, one key per line, in
+ * `ENV_KEYS` order restricted to `keysForTemplate(templateSlug)` — a key the given template never
+ * reads is never written at all, rather than left as a dead empty assignment. A missing value for
+ * a key the template DOES read is still written as an empty assignment so the file lists it for
+ * the user to complete. Each key is written under the NAME the given template actually reads
+ * (`envKeyNameForTemplate`) — not necessarily its canonical `RAKOMI_*` form.
  */
-export function renderDotenv(values) {
-    const lines = ENV_KEYS.map((key) => dotenvLine(key, values[key] ?? ''));
+export function renderDotenv(values, templateSlug) {
+    const lines = keysForTemplate(templateSlug).map((key) => dotenvLine(envKeyNameForTemplate(templateSlug, key), values[key] ?? ''));
     return lines.join('\n') + '\n';
 }
 /** Write the `.env` file into the target project directory. */
-export async function writeEnvFile(targetDir, values) {
-    await writeFile(join(targetDir, '.env'), renderDotenv(values), 'utf8');
+export async function writeEnvFile(targetDir, values, templateSlug) {
+    await writeFile(join(targetDir, '.env'), renderDotenv(values, templateSlug), 'utf8');
 }

package/dist/index.js

@@ -1,13 +1,15 @@
 #!/usr/bin/env node
 // SPDX-License-Identifier: MIT
-import { readFileSync } from 'node:fs';
+import { readFileSync, realpathSync } from 'node:fs';
 import { appendFile, readFile } from 'node:fs/promises';
 import { isAbsolute, join, relative, resolve } from 'node:path';
 import process from 'node:process';
 import { pathToFileURL } from 'node:url';
 import { parseArgs } from 'node:util';
+import { writeAgentContext } from './agent-context.js';
 import { writeEnvFile } from './env.js';
 import { CliError, EXIT, UsageError } from './errors.js';
+import { writeMcpConfig } from './mcp-config.js';
 import { collectEnv, createTtyAsk } from './prompt.js';
 import { assertTargetWritable, GithubCodeloadSource, materializeArchive } from './source.js';
 import { findTemplate, slugList } from './templates.js';
@@ -45,9 +47,11 @@ async function dispatch(args, deps) {
                 template: { type: 'string' },
                 region: { type: 'string' },
                 'tenant-id': { type: 'string' },
+                'client-id': { type: 'string' },
                 'template-source': { type: 'string' },
                 yes: { type: 'boolean' },
                 connect: { type: 'boolean' },
+                'no-mcp': { type: 'boolean' },
                 help: { type: 'boolean', short: 'h' },
                 version: { type: 'boolean', short: 'V' },
             },
@@ -82,15 +86,22 @@ async function dispatch(args, deps) {
         flags.RAKOMI_REGION = values.region;
     if (typeof values['tenant-id'] === 'string')
         flags.RAKOMI_TENANT_ID = values['tenant-id'];
+    if (typeof values['client-id'] === 'string')
+        flags.RAKOMI_CLIENT_ID = values['client-id'];
     const interactive = deps.isTTY && values.yes !== true && !deps.env.CI;
-    const envValues = await collectEnv({ flags, env: deps.env, interactive, ask: deps.ask });
+    const envValues = await collectEnv({ flags, env: deps.env, interactive, ask: deps.ask }, template.slug);
     const source = deps.source ?? makeDefaultSource(values, deps.env);
     const archive = await source.fetchArchive(template);
     await materializeArchive(archive, targetDir);
     await ensureEnvIgnored(targetDir);
-    await writeEnvFile(targetDir, envValues);
+    await writeEnvFile(targetDir, envValues, template.slug);
+    const mcpConfigWritten = values['no-mcp'] !== true;
+    if (mcpConfigWritten) {
+        await writeMcpConfig(targetDir);
+        await writeAgentContext(targetDir);
+    }
     const pm = detectPackageManager(deps.env.npm_config_user_agent);
-    deps.stdout.write(postInstallMessage(template.slug, rawTarget, pm));
+    deps.stdout.write(postInstallMessage(template.slug, rawTarget, pm, mcpConfigWritten));
     if (values.connect === true) {
         deps.stdout.write(connectInstructions());
     }
@@ -160,6 +171,23 @@ async function main() {
         ask: createTtyAsk(),
     });
 }
-if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+/**
+ * Whether this module is the process entry point. npm/npx invoke the bin through a symlink in
+ * `node_modules/.bin`, and `pathToFileURL` does not resolve symlinks — comparing against the raw
+ * `argv[1]` is false under npx, so the CLI exits 0 having done nothing. Resolve the real path
+ * first; fall back to the raw path when it cannot be resolved.
+ */
+function isProcessEntry(argv1) {
+    if (!argv1)
+        return false;
+    let real = argv1;
+    try {
+        real = realpathSync(argv1);
+    }
+    catch {
+    }
+    return import.meta.url === pathToFileURL(real).href || import.meta.url === pathToFileURL(argv1).href;
+}
+if (isProcessEntry(process.argv[1])) {
     void main();
 }

package/dist/mcp-config.js

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: MIT
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CLIENT_REGISTRY } from './client-registry.generated.js';
+import { CliError, EXIT } from './errors.js';
+/**
+ * The Rakomi MCP resource server's canonical URL. Byte-frozen: `https` scheme, lowercase host,
+ * no port, the `/mcp` Streamable-HTTP mount path. Never hand-type this literal a second time —
+ * import this constant.
+ */
+export const MCP_URL = 'https://mcp.rakomi.com/mcp';
+function mustFindClient(id) {
+    const entry = CLIENT_REGISTRY.find((c) => c.id === id);
+    if (!entry) {
+        throw new CliError(`client-registry.generated.ts is missing the "${id}" entry — run \`node scripts/gen-mcp-clients.mjs\` and commit the result.`, EXIT.FAIL);
+    }
+    return entry;
+}
+/**
+ * Claude Code's registry entry — the single source `mcpConfigJson()` and `agent-context.ts` derive
+ * the `.mcp.json` shape and the connect `finishInstruction` from. Never hand-duplicate either;
+ * import from here.
+ */
+export const CLAUDE_CODE_CLIENT = mustFindClient('claude-code');
+/**
+ * The exact content written to `.mcp.json` — matches the shape `claude mcp add --transport http`
+ * produces (topLevelKey `mcpServers`, remoteUrlField `url`, extraFields `{ type: "http" }`),
+ * DERIVED from `CLAUDE_CODE_CLIENT.config` rather than a second hand-typed literal. No
+ * `client_id` — CIMD discovery needs none.
+ */
+export function mcpConfigJson() {
+    const config = CLAUDE_CODE_CLIENT.config;
+    if (!config) {
+        throw new CliError('The claude-code registry entry carries no config block.', EXIT.FAIL);
+    }
+    const rakomiEntry = { ...config.extraFields, [config.remoteUrlField]: MCP_URL };
+    return { [config.topLevelKey]: { rakomi: rakomiEntry } };
+}
+/**
+ * Write `.mcp.json` into the freshly scaffolded project root. Always writes unconditionally — a
+ * fresh quickstart template never ships its own `.mcp.json` (verified by
+ * `test/mcp-config.test.ts`'s manifest scan), so there is nothing to merge and nothing to clobber.
+ * Pretty-printed, LF-terminated, the same convention every other writer in this package uses
+ * (`env.ts`'s `writeEnvFile`).
+ */
+export async function writeMcpConfig(targetDir) {
+    await writeFile(join(targetDir, '.mcp.json'), JSON.stringify(mcpConfigJson(), null, 2) + '\n', 'utf8');
+}

package/dist/prompt.js

@@ -1,21 +1,45 @@
 // SPDX-License-Identifier: MIT
 import { stdin, stdout } from 'node:process';
 import { createInterface } from 'node:readline/promises';
-import { DEFAULT_REGION, ENV_KEYS, SECRET_KEYS } from './env.js';
+import { DEFAULT_NODE_REDIRECT_URI, DEFAULT_REGION, ENV_KEYS, keysForTemplate, SECRET_KEYS } from './env.js';
 export const FIELDS = [
     { key: 'RAKOMI_REGION', label: 'Data region', defaultValue: DEFAULT_REGION },
     { key: 'RAKOMI_TENANT_ID', label: 'Tenant ID' },
     { key: 'RAKOMI_API_KEY', label: 'API key' },
+    { key: 'RAKOMI_CLIENT_ID', label: 'OAuth Client ID' },
+    { key: 'RAKOMI_CLIENT_SECRET', label: 'OAuth Client Secret (leave blank for a public/PKCE-only client)' },
+    { key: 'RAKOMI_REDIRECT_URI', label: 'Redirect URI', defaultValue: DEFAULT_NODE_REDIRECT_URI },
+    { key: 'RAKOMI_ISSUER', label: 'Issuer of your environment' },
 ];
+/**
+ * Extra guidance appended to a field's prompt line — where to GET a value the wizard cannot
+ * derive on its own, or a precondition the value itself carries. `RAKOMI_CLIENT_ID`: every tenant
+ * signup auto-provisions a default OAuth client at creation time, so the value already exists —
+ * find it rather than create it. `RAKOMI_API_KEY`: a signup's LIVE key (`akm_live_`) does not
+ * authenticate requests until the account owner verifies their e-mail — paste the TEST key
+ * (`akm_test_`) here to get this app running immediately, then swap in the live key once verified.
+ */
+const FIELD_HINTS = {
+    RAKOMI_API_KEY: 'paste the test key (akm_test_...) to start now — the live key needs email verification first',
+    RAKOMI_CLIENT_ID: 'from your Rakomi dashboard -> Settings -> Development credentials',
+    RAKOMI_ISSUER: 'the iss of your environment\'s tokens, e.g. https://api.rakomi.com/t/tn_.../test',
+};
 /**
  * Resolve all env values by precedence: explicit flag > `RAKOMI_*` env var > interactive
  * prompt > documented default. Never prompts in non-interactive mode (so a CI pipe never
  * hangs); there it falls back to env/flag/default, leaving the rest empty for the user.
- * Secret values are never echoed back.
+ * Secret values are never echoed back. `templateSlug` restricts which fields are even asked
+ * about — a key the given template never reads (see `keysForTemplate`) is skipped entirely,
+ * never prompted for and never present in the returned object; optional so every pre-existing
+ * caller/fixture (which meant "every canonical key applies") keeps compiling and behaving
+ * unchanged.
  */
-export async function collectEnv(deps) {
+export async function collectEnv(deps, templateSlug) {
+    const relevant = new Set(keysForTemplate(templateSlug));
     const out = {};
     for (const field of FIELDS) {
+        if (!relevant.has(field.key))
+            continue;
         const fromFlag = deps.flags[field.key];
         if (fromFlag !== undefined && fromFlag !== '') {
             out[field.key] = fromFlag;
@@ -38,8 +62,9 @@ export async function collectEnv(deps) {
 }
 function promptText(field) {
     const secret = SECRET_KEYS.has(field.key) ? ' (kept local, never sent anywhere)' : '';
+    const hint = FIELD_HINTS[field.key] ? ` (${FIELD_HINTS[field.key]})` : '';
     const dflt = field.defaultValue !== undefined ? ` [${field.defaultValue}]` : '';
-    return `${field.label}${secret}${dflt}: `;
+    return `${field.label}${secret}${hint}${dflt}: `;
 }
 /** A real-TTY prompt backed by `node:readline/promises`. */
 export function createTtyAsk() {

package/dist/usage.js

@@ -36,16 +36,22 @@ export function helpText() {
         '  --template <slug>        which quickstart to scaffold (required)',
         '  --region <value>         data region (default: eu-central)',
         '  --tenant-id <value>      your tenant id',
+        '  --client-id <value>      your OAuth client_id (dashboard -> Integration -> Applications)',
         '  --template-source <url>  override the archive base (mirror / offline)',
         '  --yes                    accept defaults, never prompt (non-interactive)',
         '  --connect                print next steps for connecting an AI agent (the rakomi CLI)',
+        "  --no-mcp                 don't scaffold .mcp.json / AGENTS.md (written by default — agent-ready on first run)",
         '  -h, --help               show this help and exit',
         '  -V, --version            print the version and exit',
         '',
         'Environment variables collected into the new project\'s .env:',
-        '  RAKOMI_REGION, RAKOMI_TENANT_ID, RAKOMI_API_KEY',
+        '  RAKOMI_REGION, RAKOMI_TENANT_ID, RAKOMI_API_KEY, RAKOMI_CLIENT_ID',
+        '  RAKOMI_ISSUER (node, nextjs: the issuer of your environment, e.g. https://api.rakomi.com/t/tn_...)',
         '  (RAKOMI_API_KEY is read from the prompt or the environment, never a flag,',
-        '   and is written only to your local .env — never transmitted.)',
+        '   and is written only to your local .env — never transmitted. RAKOMI_CLIENT_ID is',
+        "   written under the target template's own convention, e.g. NEXT_PUBLIC_RAKOMI_CLIENT_ID.",
+        '   Your tenant signup auto-provisions a default OAuth client for you — find its Client ID in',
+        '   your Rakomi dashboard: Settings -> Development credentials.)',
         '',
         `After scaffolding, the next-step walkthrough lives at ${PORTAL_HOST}/quickstart/<slug>.`,
         '',
@@ -60,18 +66,26 @@ export function usageLine() {
  * manager-aware command list. The install step is framed as the user's own next step that
  * depends on the public npm registry, not a guarantee. No color is emitted (NO_COLOR-safe by
  * construction) and the copy is stack-neutral so a tutorial can quote it verbatim.
+ *
+ * `mcpConfigWritten` (default `true`) reports whether `.mcp.json` + `AGENTS.md` were scaffolded
+ * into the new project (they are, unless `--no-mcp` was passed) — when they were, one extra line
+ * tells the user the project is already agent-ready and what to run to finish sign-in, plus a
+ * pointer to AGENTS.md for a fuller briefing.
  */
-export function postInstallMessage(slug, directory, pm) {
-    return [
+export function postInstallMessage(slug, directory, pm, mcpConfigWritten = true) {
+    const lines = [
         '',
         `Done. Your Rakomi ${slug} app is ready in ${directory}`,
         '',
         'Next steps:',
         `  1. cd ${directory}`,
-        `  2. ${installCommand(pm)}   (installs @rakomi/node from the public npm registry)`,
+        `  2. ${installCommand(pm)}   (installs the Rakomi SDK from the public npm registry)`,
         `  3. ${runCommand(pm)}`,
         '',
-        `Walkthrough: ${portalUrl(slug)}`,
-        '',
-    ].join('\n');
+    ];
+    if (mcpConfigWritten) {
+        lines.push('Agent-ready: .mcp.json points Claude Code at the Rakomi MCP server — run `claude mcp login rakomi` to finish sign-in.', 'See AGENTS.md for the full briefing any AI agent working in this project can read.', '');
+    }
+    lines.push(`Walkthrough: ${portalUrl(slug)}`, '');
+    return lines.join('\n');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-rakomi-app",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Scaffold a Rakomi quickstart app. EU-native auth-as-a-service. npx create-rakomi-app --template <slug>",
   "keywords": [
     "rakomi",
@@ -43,6 +43,6 @@
     "build": "tsc",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src/ test/ --max-warnings=0",
-    "test": "vitest run"
+    "test": "node ../../scripts/assert-not-story-agent-worktree.mjs test && node ../../scripts/ci/vitest-fork-crash-retry.mjs --results ./test-results.json -- vitest run"
   }
 }

package/sbom.cdx.json

@@ -26,10 +26,10 @@
     },
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/create-rakomi-app@0.1.1",
+      "bom-ref": "pkg:npm/create-rakomi-app@0.2.0",
       "name": "create-rakomi-app",
-      "version": "0.1.1",
-      "purl": "pkg:npm/create-rakomi-app@0.1.1",
+      "version": "0.2.0",
+      "purl": "pkg:npm/create-rakomi-app@0.2.0",
       "licenses": [
         {
           "license": {