@lanes-sh/link 0.3.2 → 0.4.0

package/README.md

@@ -110,17 +110,25 @@ One command per account. Run it again to add a second mailbox, a second calendar
 | Linear | `lanes link connect linear` |
 | GitHub | `lanes link connect github` |
 | Slack | `lanes link connect slack` |
+| Reddit | `lanes link connect reddit` |
+| Discord | `lanes link connect discord` |
 | Gmail (IMAP, app password) | `lanes link connect gmail_imap` |
 | Gmail (Google MCP) | `lanes link connect gmail_mcp` |
 | Drive (Google MCP) | `lanes link connect drive_mcp` |
+| bunq | `lanes link connect bunq` |
 
 Three things worth knowing up front. `lanes link connect icloud` sets up Mail, Calendar, and
-Contacts together, because one app-specific password covers all three. Google and Slack need no
+Contacts together, because one app-specific password covers all three. Reddit is the one that does
+need an app of your own — it rate-limits per client id, so a shared client would mean strangers
+spending your budget. Google and Slack need no
 OAuth client of your own: both authorise against the one Lanes operates, so there is no console to
 visit — for Google, add `--own-client` if you would rather register your own, or take a service
 account key or an app password over IMAP where you would rather nothing expired. And GitHub takes a
-token you paste rather than a browser sign-in, because it will not register a client for us; that
-is the one console visit left here.
+token you paste rather than a browser sign-in, because it will not register a client for us. And
+bunq — which wants a key from inside its app rather than a console at all — is the one that can move
+money, and it says so: its payment tool executes immediately and is not reversible. Set a spending
+limit on the API key while you are in there, and read
+[docs/detailed/setup/bunq.md](docs/detailed/setup/bunq.md) before connecting it.
 
 Full guide — what each one gives your agent, what it needs, and adding your own:
 **[docs/connect.md](docs/connect.md)**.

package/instructions/agents/lanes-link-scout.md

@@ -56,8 +56,8 @@ to every future session.
 stops a write is policy on the endpoint:
 
 ```console
-$ lanes link policy deny memory.write
-$ lanes link policy list
+$ lanes link policy deny memory.write --profile <name> --target <name>
+$ lanes link policy list --profile <name>
 ```
 
 If you are running against a profile that grants writes, that is the owner's

package/instructions/skills/lanes-link/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lanes-link
-description: Use when the user refers to their own accounts, knowledge, procedures, or secrets through Lanes Link — "check my mail", "what do I know about X", "remember this", "which profile am I in" — or asks to connect, register, or set up their Lanes Link MCP server with this agent. Also covers what to do when a Lanes Link call is refused, or when the endpoint is not running.
+description: Use when the user refers to their own accounts, knowledge, procedures, or secrets through Lanes Link — "check my mail", "what do I know about X", "remember this", "which profile am I in" — or asks to connect, register, or set up their Lanes Link MCP server with this agent. Also covers operating the workspace from a shell — adding or removing a profile, checking what a target serves, deploying an endpoint or recovering a lost deployment — and what to do when a Lanes Link call is refused, or when the endpoint is not running.
 ---
 
 # Lanes Link
@@ -24,12 +24,32 @@ is listed first.** Quietly picking one crosses the line the profile exists to
 draw. There is no "current profile" to switch — the choice is made per call, and
 `lanes link profile list` shows what exists.
 
-**Every `lanes link` command names its profile and its target.** Both are required
-flags with no default, no environment variable, and nothing in a config file
-behind them, so a command missing either refuses rather than acting somewhere
-else. When you write one out for the owner, either fill both in or leave them as
-`<name>` for them to complete — never drop them. `lanes link target list
---profile <name>` shows what a profile declares.
+**What a command must be told is never inferred — but it is not always both.**
+Nothing resolves from an environment variable or a config default, so a command
+missing what it needs refuses rather than acting somewhere else. Passing a flag a
+command does not read is refused too, which makes "add both to be safe" its own
+failure. Four levels:
+
+- **Neither.** `lanes link profile list`, `lanes link mcp list`,
+  `lanes link version`.
+- **`--profile` alone.** `lanes link check`, `lanes link config show`,
+  `lanes link policy list`, `lanes link target list --profile <name>`,
+  `lanes link identity list`. Each is target-independent — one declaration in the
+  YAML that applies wherever the profile runs.
+- **`--target`, with the profiles derived from it.** `lanes link status`,
+  `lanes link deploy` and `lanes link sync targets` act on one endpoint serving
+  every profile that declares that target. `--profile` is accepted and *narrows*
+  the answer; it does not choose the subject.
+- **Both.** Everything acting on one account: `lanes link connect`,
+  `lanes link token rotate`, `lanes link secrets set`, `lanes link policy allow`,
+  `lanes link memory list`, `lanes link mcp add`.
+
+`lanes link profile add` and `lanes link profile remove` **reject** `--profile`.
+Both name their profile positionally, so a flag naming a second one could only
+disagree with it.
+
+When you write a command out for the owner, fill in what that command needs or
+leave it as `<name>` for them to complete — never drop a required one.
 
 A `connection` names an account within that profile. One profile may hold
 several of the same kind, and naming a connection belonging to a *different*
@@ -162,8 +182,101 @@ the line.
 **Never pass `--accept-broad-scopes` yourself.** When a provider asks for more than
 it needs, print the scopes and let the owner add the flag. Deciding that is theirs.
 
-A new connection is not served until the endpoint restarts, so a `setup_overview`
-straight after connecting will still not show it. Say so rather than retrying.
+**A new connection is served at once; the tools you were handed are not.**
+Connecting publishes the config to wherever that target's endpoint reads it and
+asks the endpoint to re-read it, so a `setup_overview` straight after connecting
+*does* show the account. What has not changed is the set of tools this session
+was given when it connected — the endpoint does not announce that its tools
+changed, so a capability for a freshly connected account is not callable until
+the client reconnects. Say that, rather than reporting the connection as missing
+or asking them to connect again.
+
+One exception, and it is the one that matters here: the authenticator is built
+once at boot and is not re-read, so a `lanes link token rotate` does need the
+endpoint restarted before the new token opens anything.
+
+## Operating the workspace
+
+If you have a shell, the commands that only *read* are yours to run without
+asking: `lanes link status`, `lanes link check`, `lanes link plan`,
+`lanes link doctor`, `lanes link profile list`, `lanes link target list`,
+`lanes link target show`, `lanes link tools`, `lanes link config show` and
+`lanes link audit tail`. None writes config, opens a browser, or costs anything,
+and running one beats asking the owner to paste its output back. Give each what
+its own level requires — they are not all the same, and the four levels are at
+the top of this file.
+
+**A command that writes runs `--dry-run` first, where it has one.** Show what it
+reported and wait for an answer. `lanes link deploy`, `lanes link sync targets`,
+`lanes link profile remove`, `lanes link secrets push` and `lanes link mcp add`
+all take it. For a write with no dry run — `lanes link token rotate`,
+`lanes link policy allow`, `lanes link secrets set` — say in one sentence what it
+will change, then let them decide. Never a browser sign-in: that belongs to
+whoever owns the account, as above.
+
+**`--json` is not everywhere.** It parses on every command and is read by only
+some, so one that ignores it prints its ordinary output and gives you nothing to
+key on — do not treat the absence of JSON as a failure. `status`, `doctor`,
+`tools`, `outputs`, `sync targets`, `target list`, `target show`, `profile list`,
+`connect` and `setup plan` implement it. `deploy`, `check`, `plan`,
+`config show`, `audit tail` and every `mcp` subcommand do not.
+
+**A profile is created and removed, never switched.** `lanes link profile add
+<name>` writes a new one and takes `--target <name>`, repeated once per target it
+should declare. `lanes link profile remove <name>` takes `--dry-run` and then
+`--yes`; given a `--target` it decommissions that one target's stores and leaves
+the profile file in place. Neither reads `--profile`.
+
+There is no current profile and no default target. `lanes link profile default`
+and `lanes link target use` are gone and now refuse with an explanation — if you
+meet one of those refusals, it is not a broken install, and there is no
+replacement to find. The choice is made per command, on purpose.
+
+## Deploying, and what it decides
+
+`lanes link deploy` builds an image and rolls a revision. Its subject is a
+**target**, and the profiles behind it are every profile declaring that target,
+so one deploy serves all of them — there is no per-profile deploy to run and no
+reason to loop over them.
+
+**Always `--dry-run` first, and show what it printed.** It creates cloud
+resources that cost money, it implements no `--json` to inspect instead, and that
+plan is the only place the consequences are visible while they are still
+avoidable.
+
+Two things it refuses to guess, and both are the owner's to answer:
+
+- **Whose bearer token opens the endpoint.** One token reaches every profile
+  behind that target, so this decides who gets in. With several candidates and
+  nothing recorded, it refuses and prints the command that names one.
+- **A first deploy.** A target no profile declares yet has no set to derive from,
+  so `--profile` is required there. It may be repeated, and the first one named
+  is the primary.
+
+**Never pass `--yes`, `--non-interactive`, `--access public` or
+`--service-account` yourself.** Each settles a question about who can reach their
+accounts. Print what the flag would decide and let them add it — the same rule
+this file already applies to `--accept-broad-scopes`.
+
+Deploying is how new code reaches the endpoint. It is not how an account gets
+connected and not how a config change lands; both of those publish themselves.
+
+## When the workspace and the endpoint disagree
+
+A deployment records where it lives, and a workspace can lose that record — a new
+machine, a reinstall, a profile file restored from something older. The endpoint
+is still serving; what went missing is the config that describes it. The symptom
+is a `lanes link status` that reports nothing deployed for a target you know is
+up.
+
+`lanes link sync targets` reconciles the two. `--discover` looks for a deployment
+the workspace has no record of, `--from <location>` names one directly, and
+`--dry-run` reports what it would merge without merging it. Run the dry run and
+show it.
+
+**`--prefer local` or `--prefer remote` is their answer, not yours.** It decides
+which side wins where the two disagree, and the losing value is the one nobody
+was asked about. Report what differs and let them pick.
 
 ## Registering it, and re-registering it
 
@@ -192,7 +305,7 @@ substitution form. If you have already printed one by accident, say so and offer
 Prefer `lanes link mcp add --profile <name> --target <name>` to writing the command yourself: it checks the
 endpoint is reachable, refuses to silently shadow an existing registration, and
 cannot mistype the token. For a harness it does not know, take the command from
-`lanes link outputs` rather than writing it blind — that command checks whether
+`lanes link outputs --profile <name> --target <name>` rather than writing it blind — that command checks whether
 `lanes` resolves on this machine and prints a longer working form if it does
 not, where guessing gives you an empty substitution, a `Bearer ` header, and a
 401 that reads as a bad token.
@@ -207,9 +320,20 @@ export LANES_LINK_TOKEN="$(lanes link token show --raw --profile <name> --target
 One registration covers every profile. Do not add one per profile; they share a
 URL and a token.
 
+`lanes link mcp list` needs neither flag and reports whether the registration and
+this document are current, out of date, or absent. That is the cheap first
+question when behaviour does not match what this file describes — an out-of-date
+copy means the rules you are reading are not the ones that shipped.
+
+Claude Desktop cannot be handed a URL, so it spawns the endpoint over stdio
+instead. That one is named in the client's own config file rather than registered
+by a command, as `lanes link mcp stdio --profile <name> --target <name>`; both
+flags are required, and nothing may be written to stdout.
+
 ## When it is not running
 
-`lanes link start` runs in the foreground and serves until stopped. Tell the
+`lanes link start --profile <name> --target <name>` runs in the foreground and
+serves until stopped. Tell the
 user the command rather than backgrounding it silently on their behalf.
 Registration works while it is down — the harness simply cannot reach it yet,
 and the first symptom is a failed call much later.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lanes-sh/link",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "A self-hostable MCP gateway for all your connections, memory, skills, and secrets",
   "license": "Apache-2.0",
   "homepage": "https://lanes.sh/link",
@@ -49,6 +49,8 @@
     "typecheck": "tsc --noEmit",
     "lanes": "bun run ./src/cli/lanes.ts",
     "audit": "bun pm scan",
+    "vendor:bunq": "bun run ./src/providers/bunq/specs/vendor.ts",
+    "vendor:discord": "bun run ./src/providers/discord/specs/vendor.ts",
     "vendor:google": "bun run ./src/providers/google/specs/vendor.ts"
   },
   "imports": {

package/src/cli/argv.ts

@@ -1,6 +1,7 @@
 import type { GlobalFlags } from './runtime.ts';
 import type { OwnerFlags } from './commands/owner.ts';
 import type { KnowledgeFlags } from './commands/knowledge.ts';
+import type { CustomFlags } from './commands/connect/custom/spec.ts';
 
 /**
  * Turning argv into a command path and a flag bag.
@@ -142,3 +143,54 @@ export function knowledgeFlags(flags: Flags): KnowledgeFlags {
     json: flags['json'] === true,
   };
 }
+
+/**
+ * `lanes link connect custom`'s flags.
+ *
+ * Here for the reason `ownerFlags` and `knowledgeFlags` are: the kebab-case
+ * spellings belong in the one place that parses argv. The list flags go through
+ * `all(argv, …)` rather than through `flags`, because `parseArgv` keeps only the
+ * last value of a repeated flag — so `--scopes a --scopes b` would silently
+ * become `b`, and a scope quietly dropped is a token that works until it does
+ * not.
+ *
+ * Which of these are read at all depends on the connectivity type and the
+ * credential type chosen; that is `custom/spec.ts`'s to know. This only spells
+ * them.
+ */
+export function customFlags(flags: Flags, argv: readonly string[]): CustomFlags {
+  return {
+    connector: text(flags, 'connector'),
+    auth: text(flags, 'auth'),
+    name: text(flags, 'name'),
+    description: text(flags, 'description'),
+    endpoint: text(flags, 'endpoint'),
+    baseUrl: text(flags, 'base-url'),
+    openapi: text(flags, 'openapi'),
+    operations: all(argv, 'operations'),
+    service: text(flags, 'service'),
+    host: text(flags, 'host'),
+    port: text(flags, 'port'),
+    smtpHost: text(flags, 'smtp-host'),
+    smtpPort: text(flags, 'smtp-port'),
+    root: text(flags, 'root'),
+    exclude: all(argv, 'exclude'),
+    header: all(argv, 'header'),
+    authHeader: text(flags, 'auth-header'),
+    authQuery: text(flags, 'auth-query'),
+    scopes: all(argv, 'scopes'),
+    authorizeUrl: text(flags, 'authorize-url'),
+    tokenUrl: text(flags, 'token-url'),
+    clientApp: text(flags, 'client-app'),
+    registration: text(flags, 'registration'),
+    redirectUri: text(flags, 'redirect-uri'),
+    authorizeParam: all(argv, 'authorize-param'),
+    strategy: text(flags, 'strategy'),
+    strategyOption: all(argv, 'strategy-option'),
+    identityUrl: text(flags, 'identity-url'),
+    identityField: text(flags, 'identity-field'),
+    setupDocs: text(flags, 'setup-docs'),
+    replaceManifest: flags['replace-manifest'] === true,
+    yes: flags['yes'] === true,
+  };
+}

package/src/cli/commands/connect/authorise.ts

@@ -283,6 +283,11 @@ async function authoriseDirect(input: {
       ...(client.kind === 'brokered' && client.config.redirectUri
         ? { relayRedirect: client.config.redirectUri }
         : {}),
+      // The other spelling of the same need, for a vendor that takes a loopback
+      // redirect but matches it exactly. The manifest owns this URL because the
+      // vendor's console does — it has to be the string registered there, and
+      // `defineProvider` refuses a manifest declaring both this and a broker.
+      ...(manifest.auth.redirect_uri ? { fixedRedirect: manifest.auth.redirect_uri } : {}),
       scopes,
       connectionLabel: manifest.name,
       ...(manifest.auth.authorize_params

package/src/cli/commands/connect/custom/ask.ts

@@ -0,0 +1,167 @@
+import { style } from '../../../output.ts';
+import type { Prompter } from '../../../prompt.ts';
+import { parseAuthMethod, parseConnectorKind, refuseIllegalPair } from './derive.ts';
+import {
+  AUTH_FIELDS,
+  AUTH_METHODS,
+  CONNECTOR_FIELDS,
+  CONNECTOR_KINDS,
+  camel,
+  titleCase,
+  type CustomAnswers,
+  type CustomFlags,
+  type FieldSpec,
+} from './spec.ts';
+
+/**
+ * Collecting what the flags did not say.
+ *
+ * Every value has a flag, so the whole command is scriptable — but the fields
+ * differ per connectivity type and per credential type, and nobody holds thirty
+ * flag names in their head to declare one provider. So a missing required value
+ * is asked for, in a fixed order, and the answers are indistinguishable from
+ * having been typed.
+ *
+ * Under `--non-interactive` nothing is asked and *everything* missing is named
+ * at once, with the command to re-run. One round trip rather than one refusal
+ * per flag, because the caller there is usually a script or an agent and each
+ * refusal costs it a whole run.
+ */
+
+/** Named, not asked: nothing can be collected until the two lists are picked. */
+export interface Blocked {
+  readonly missing: readonly string[];
+  readonly command: string;
+}
+
+export async function collect(
+  id: string,
+  flags: CustomFlags,
+  prompter: Prompter,
+  /** How to spell the re-run, when there is nothing to ask. */
+  commandFor: (missing: readonly string[]) => string,
+): Promise<CustomAnswers | Blocked> {
+  const missing: string[] = [];
+
+  const connector = flags.connector
+    ? parseConnectorKind(flags.connector)
+    : prompter.interactive
+      ? parseConnectorKind(await choose(prompter, 'How is this service reached?', CONNECTOR_KINDS))
+      : (missing.push('connector'), undefined);
+
+  const auth = flags.auth
+    ? parseAuthMethod(flags.auth)
+    : prompter.interactive
+      ? parseAuthMethod(await choose(prompter, 'How does it authenticate?', AUTH_METHODS))
+      : (missing.push('auth'), undefined);
+
+  // Which fields exist at all depends on the two answers above, so a
+  // non-interactive run missing either cannot list the rest yet. Saying so beats
+  // guessing at a list that would be wrong.
+  if (!connector || !auth) return { missing, command: commandFor(missing) };
+
+  // Before a single field is asked for. The pair is decided by the two answers
+  // above, so a combination that cannot work is knowable here — and asking six
+  // questions about a mailbox that will be refused for its credential type is
+  // worse than refusing straight away.
+  refuseIllegalPair(connector, auth);
+
+  const fields = [...CONNECTOR_FIELDS[connector], ...AUTH_FIELDS[auth], ...EXTRA];
+  const values: Record<string, string | readonly string[]> = {};
+
+  for (const field of fields) {
+    const given = flags[camel(field.flag) as keyof CustomFlags];
+
+    if (Array.isArray(given)) {
+      if (given.length > 0) values[field.flag] = given;
+      continue;
+    }
+    if (typeof given === 'string' && given.length > 0) {
+      values[field.flag] = given;
+      continue;
+    }
+    if (!field.required) continue;
+
+    if (!prompter.interactive) {
+      missing.push(field.flag);
+      continue;
+    }
+
+    const answer = field.choices
+      ? await choose(prompter, field.label, field.choices)
+      : await askFor(prompter, field);
+
+    if (answer.length > 0) values[field.flag] = answer;
+    else missing.push(field.flag);
+  }
+
+  if (missing.length > 0) return { missing, command: commandFor(missing) };
+
+  const name = flags.name ?? (prompter.interactive ? await askName(prompter, id) : titleCase(id));
+
+  return {
+    id,
+    name,
+    ...(flags.description ? { description: flags.description } : {}),
+    connector,
+    auth,
+    values,
+  };
+}
+
+/**
+ * Fields that belong to no single kind.
+ *
+ * All optional, so a non-interactive run is never blocked on one — and none is
+ * prompted for, because a question nobody needs to answer is worse than a flag
+ * nobody types. `derive.ts` refuses the combinations that do not work.
+ */
+const EXTRA: readonly FieldSpec[] = [
+  { flag: 'identity-url', label: 'Identity URL', required: false },
+  { flag: 'identity-field', label: 'Identity field', required: false },
+  { flag: 'setup-docs', label: 'Where to get the credential', required: false },
+];
+
+async function askFor(prompter: Prompter, field: FieldSpec): Promise<string> {
+  if (field.hint) print(style.dim(`  ${field.hint}`));
+  return (await prompter.ask(`${field.label}: `)).trim();
+}
+
+async function askName(prompter: Prompter, id: string): Promise<string> {
+  const suggested = titleCase(id);
+  const answer = (await prompter.ask(`Display name [${suggested}]: `)).trim();
+  return answer.length > 0 ? answer : suggested;
+}
+
+/**
+ * A closed set, offered as a numbered list.
+ *
+ * The same shape `chooseAuthMethod` uses for a provider with more than one way
+ * in, for the same reason: these are the members of a union, and typing one from
+ * memory is how somebody discovers a name is `api-key` and not `apikey` by
+ * being refused.
+ */
+async function choose(
+  prompter: Prompter,
+  question: string,
+  options: readonly string[],
+): Promise<string> {
+  print('');
+  print(question);
+  options.forEach((option, index) => print(`  ${index + 1}. ${option}`));
+
+  const answer = (await prompter.ask(`Choose 1-${options.length}: `)).trim();
+  const index = Number(answer);
+
+  // A name is accepted too. Somebody who already knows it should not have to
+  // count, and the numbers exist for somebody who does not.
+  if (options.includes(answer)) return answer;
+  if (Number.isInteger(index) && index >= 1 && index <= options.length) return options[index - 1]!;
+
+  throw new Error(`"${answer}" is not one of: ${options.join(', ')}.`);
+}
+
+/** Prompts and their hints go to stderr, so `--json` leaves stdout clean. */
+function print(line: string): void {
+  process.stderr.write(`${line}\n`);
+}

package/src/cli/commands/connect/custom/credential.ts

@@ -0,0 +1,143 @@
+import { AUTH_KIND, type CustomAnswers } from './spec.ts';
+import { many, one, pairs } from './values.ts';
+
+/**
+ * The credential block, and the OAuth rules the schema does not carry.
+ *
+ * Split from `derive.ts` because it fails for a different reason. That file is
+ * about a connectivity type's fields, which are either given or defaulted; this
+ * one is about arrangements that *validate* and then cannot run — an
+ * authorization server with nowhere to send the browser, a client nobody
+ * registered, a header the transport will not read. Each of those surfaces after
+ * a credential has been stored or a consent screen approved, so each is refused
+ * here.
+ */
+
+export function authBlock(answers: CustomAnswers): Record<string, unknown> {
+  const method = answers.auth;
+  const kind = AUTH_KIND[method];
+  const header = one(answers, 'auth-header');
+  const query = one(answers, 'auth-query');
+
+  if (method === 'none' || method === 'basic') return { kind };
+
+  if (method === 'bearer') {
+    if (header && answers.connector === 'mcp') {
+      throw new Error(
+        'An mcp connector always sends its token as "Authorization: Bearer", so --auth-header ' +
+          `("${header}") could not be honoured — the transport never reads the resolved credential, ` +
+          'only the token, and the header would be dropped in silence.\n' +
+          '  Drop the flag, or reach this service with --connector http.',
+      );
+    }
+    return { kind, ...(header ? { header } : {}) };
+  }
+
+  if (method === 'header') {
+    if (query) {
+      throw new Error(
+        '--auth-query is only meaningful for --auth api-key, which may put its key in the query ' +
+          'string. A "header" credential is sent in a header of its own and nothing forwards a query ' +
+          'parameter, so this would be dropped in silence.',
+      );
+    }
+    return { kind, header };
+  }
+
+  if (method === 'strategy') {
+    // Whether the name resolves is the registry's to answer, not this file's: a
+    // strategy travels on a provider's definition, and `strategyFor` looks first
+    // at this manifest's own and then at every other registered provider's.
+    // `refuseStrategy` is what says a name reaches nothing, and it can list what
+    // does — which is why this does not try to.
+    const named = one(answers, 'strategy');
+    const options = pairs(answers, 'strategy-option');
+
+    return {
+      kind,
+      strategy: named,
+      ...(options ? { options } : {}),
+    };
+  }
+
+  if (method === 'api-key') {
+    if (header && query) {
+      throw new Error(
+        '--auth-header and --auth-query contradict: a key goes in a header or in the query string, ' +
+          'and declaring both leaves which one is sent up to whichever the transport reads last.',
+      );
+    }
+    return { kind, ...(header ? { header } : {}), ...(query ? { query } : {}) };
+  }
+
+  return oauthBlock(answers);
+}
+
+/**
+ * The one credential type with rules the schema does not carry.
+ *
+ * Each of these produces a manifest `defineProvider` accepts and `authorise`
+ * cannot run, which is worse than an invalid one: the operator finds out after
+ * approving a consent screen, or not until the first call.
+ */
+function oauthBlock(answers: CustomAnswers): Record<string, unknown> {
+  const scopes = many(answers, 'scopes');
+  const authorizeUrl = one(answers, 'authorize-url');
+  const tokenUrl = one(answers, 'token-url');
+  const app = one(answers, 'client-app');
+  const declared = one(answers, 'registration');
+  const redirect = one(answers, 'redirect-uri');
+  const authorizeParams = pairs(answers, 'authorize-param');
+
+  if (Boolean(authorizeUrl) !== Boolean(tokenUrl)) {
+    throw new Error(
+      'OAuth endpoints are declared together or not at all. `authorise` takes the direct path only ' +
+        'when both are present, so half a pair is ignored on an mcp connector and fatal on an http ' +
+        'one.\n  Add the missing one of --authorize-url / --token-url, or drop both.',
+    );
+  }
+
+  // A REST API has no MCP metadata document to discover from, so a client has
+  // to come from somewhere the manifest names.
+  const registration =
+    declared ?? (answers.connector === 'mcp' && !authorizeUrl && !app ? 'dynamic' : 'manual');
+
+  if (registration === 'dynamic' && answers.connector === 'http') {
+    throw new Error(
+      'Dynamic client registration is something an authorization server offers, and a REST API ' +
+        'publishes no registration endpoint — there would be no client to authorise with.\n' +
+        '  Register a client with the vendor and drop --registration, which then defaults to manual.',
+    );
+  }
+
+  if (registration === 'dynamic' && authorizeUrl) {
+    throw new Error(
+      'Declaring both endpoints is what takes an mcp connector off the SDK\'s own OAuth path and onto ' +
+        'ours, and ours needs a client to present (ADR-040). Registration cannot be dynamic there.\n' +
+        '  Drop --registration dynamic, or drop the two endpoint URLs and let the SDK register.',
+    );
+  }
+
+  if (registration === 'manual' && answers.connector === 'http' && !authorizeUrl) {
+    throw new Error(
+      'An http connector has no metadata document to discover an authorization server from: a REST ' +
+        'API is a base URL, and where consent happens is not something it announces.\n' +
+        '  Add --authorize-url and --token-url.',
+    );
+  }
+
+  return {
+    kind: 'oauth',
+    registration,
+    ...(registration === 'manual' ? { app: app ?? answers.id } : {}),
+    scopes,
+    ...(authorizeUrl ? { authorize_url: authorizeUrl } : {}),
+    ...(tokenUrl ? { token_url: tokenUrl } : {}),
+    ...(redirect ? { redirect_uri: redirect } : {}),
+    // Google needs `access_type=offline` and `prompt=consent`, without which it
+    // returns an access token and no refresh token — so the connection works for
+    // an hour and then dies, which is a miserable thing to debug. Any vendor can
+    // have one of these, and nothing but the vendor's own docs will say so.
+    ...(authorizeParams ? { authorize_params: authorizeParams } : {}),
+  };
+}