@lanes-sh/link 0.7.2 → 0.8.0

package/src/cli/commands/identity.ts

@@ -1,4 +1,4 @@
-import type { IdentityEntry, ProfileSelection, Resolution } from '#profile';
+import { CONNECTIONS_FILE, type IdentityEntry, type ProfileSelection, type Resolution } from '#profile';
 import { ConfigDocument } from '../config-edit.ts';
 import { ensureIdentityConnection, repairLines, repaired } from '../config-repair.ts';
 import { announce, announceProfile, emit, ok, print, style, table, warn } from '../output.ts';
@@ -51,14 +51,20 @@ function covers(rules: ReadonlyArray<{ capability: string }>): boolean {
  * misleading thing this command could print.
  */
 function readable(config: {
-  connections: ReadonlyArray<{ provider: string }>;
-  policy: { allow: ReadonlyArray<{ capability: string }>; deny: ReadonlyArray<{ capability: string }> };
+  grants: ReadonlyArray<{
+    connection: string;
+    allow: ReadonlyArray<{ capability: string }>;
+    deny: ReadonlyArray<{ capability: string }>;
+  }>;
 }): boolean {
-  return (
-    config.connections.some((connection) => connection.provider === 'identity') &&
-    covers(config.policy.allow) &&
-    !covers(config.policy.deny)
-  );
+  // One row now rather than a connection and a rule that had to agree
+  // (ADR-058). The old shape could say "declared but not granted" and
+  // "granted but not declared", and both served nothing while reading like
+  // configuration that worked; neither is expressible here.
+  const grant = config.grants.find((row) => row.connection.startsWith('identity.'));
+  if (grant === undefined) return false;
+
+  return covers(grant.allow) && !covers(grant.deny);
 }
 
 /**
@@ -96,7 +102,13 @@ export async function addIdentity(
   const entry: IdentityEntry = { kind, value, ...(options.note ? { note: options.note } : {}) };
   document.addTo(['identity'], entry, { inline: true });
 
-  const repair = ensureIdentityConnection(document);
+  // The identity *connection* is the workspace's, like every other (ADR-057),
+  // so provisioning the surface on first use touches two files. Both saves, or
+  // neither: a grant naming a connection that does not exist is refused at load,
+  // so writing the profile alone would leave one that no longer opens.
+  const connections = await ConfigDocument.openKey(resolution.workspaceRoot, CONNECTIONS_FILE);
+  const repair = ensureIdentityConnection(connections, document);
+  await connections.save();
   await document.save();
 
   return {

package/src/cli/commands/knowledge/index.ts

@@ -1,4 +1,5 @@
 import {
+  soleGrantFor,
   ConfigError,
   KNOWLEDGE_LAYOUT,
   knowledgeTargetSchema,
@@ -23,7 +24,6 @@ import {
   removeLocal,
   summarise,
 } from './migrate.ts';
-
 /**
  * `lanes link knowledge` — where this profile's memory and skills are kept.
  *
@@ -65,78 +65,6 @@ export interface KnowledgeFlags extends GlobalFlags {
   readonly fetch?: FetchLike | undefined;
 }
 
-export async function knowledgeShow(flags: KnowledgeFlags): Promise<void> {
-  const runtime = await openRuntime(flags, { fetch: flags.fetch });
-  try {
-    if (!flags.json) announce(runtime.resolution);
-
-    const profile = runtime.config.instance.profile;
-    const selection = ` --profile ${runtime.resolution.profile} --target ${runtime.target}`;
-    const skills = (await runtime.skills.list()).length;
-    const memory = (await runtime.storage.list(`${KNOWLEDGE_LAYOUT.memory}/`)).length;
-    const entities = (await runtime.storage.list(`${KNOWLEDGE_LAYOUT.entities}/`)).length;
-    const where = runtime.knowledge?.describe;
-
-    if (flags.json) {
-      print(
-        JSON.stringify(
-          { target: runtime.target, where: where ?? 'local', memory, skills, entities },
-          null,
-          2,
-        ),
-      );
-      return;
-    }
-
-    heading('Knowledge');
-    table([
-      // The memory *directory*, not the blob root it sits in. `layout.blobs`
-      // is `data/<profile>`, which is where every provider's namespace lives —
-      // printing it here would name a directory that is mostly not memory.
-      [
-        '  memory',
-        where ? `${where}/${KNOWLEDGE_LAYOUT.memory}` : `${layout.blobs(profile)}/${KNOWLEDGE_LAYOUT.memory}`,
-        style.dim(`${memory} file${memory === 1 ? '' : 's'}`),
-      ],
-      [
-        '  skills',
-        where ? `${where}/${KNOWLEDGE_LAYOUT.skills}` : layout.skills(profile),
-        style.dim(`${skills} file${skills === 1 ? '' : 's'}`),
-      ],
-      // The count includes the derived `_index.json`, deliberately: it is a
-      // file in that directory and it is committed with the rest, so a number
-      // that quietly excluded it would not match what a person sees there.
-      [
-        '  entities',
-        where
-          ? `${where}/${KNOWLEDGE_LAYOUT.entities}`
-          : `${layout.blobs(profile)}/${KNOWLEDGE_LAYOUT.entities}`,
-        style.dim(`${entities} file${entities === 1 ? '' : 's'}`),
-      ],
-    ]);
-
-    print('');
-    print(
-      style.dim(
-        `  The vault, the credential store, runtime state and the audit log stay in target "${runtime.target}".`,
-      ),
-    );
-    // Complete commands, not shapes. Every one of these is pasted, and with
-    // nothing left to fall back on (ADR-037) a line missing either flag is a
-    // line that refuses — `emitted.test.ts` states the rule for the templates
-    // reachable without a runtime, and this is the same rule where there is one.
-    print(
-      style.dim(
-        where
-          ? `  Bring them back with: lanes link knowledge use local --migrate${selection}`
-          : `  Keep them in a repository with: lanes link knowledge use github --repo <owner/name>${selection}`,
-      ),
-    );
-  } finally {
-    await runtime.close();
-  }
-}
-
 export async function knowledgeUse(where: string | undefined, flags: KnowledgeFlags): Promise<void> {
   if (where === 'local') return useLocal(flags);
   if (where === 'github') return useGithub(flags);
@@ -172,7 +100,7 @@ async function useGithub(flags: KnowledgeFlags): Promise<void> {
   const runtime = await openRuntime(flags, { fetch: flags.fetch });
   try {
     announce(runtime.resolution);
-    const selection = ` --profile ${runtime.resolution.profile} --target ${runtime.target}`;
+    const selection = ` --profile ${runtime.resolution.profile} --workspace ${runtime.target}`;
 
     if (runtime.knowledge) {
       print(style.dim(`  This profile already reads ${runtime.knowledge.describe}.`));
@@ -206,7 +134,16 @@ async function useGithub(flags: KnowledgeFlags): Promise<void> {
       ['  token', viewer, style.dim('can write')],
     ]);
 
-    const movable = await localContents(runtime.storage, runtime.skills, knowledge);
+    // Which instances this profile grants, so `memory/` and `entities/` reach
+    // only its own and not every profile's (ADR-059).
+    const instances = grantedInstances(runtime.config);
+
+    const movable = await localContents(
+      runtime.storage,
+      runtime.skills ?? null,
+      knowledge,
+      instances,
+    );
     const moving = await decideMigration(movable.length > 0, flags);
 
     if (moving) {
@@ -225,7 +162,7 @@ async function useGithub(flags: KnowledgeFlags): Promise<void> {
       if (flags.keep) {
         print(style.dim('  --keep: the local copies are still there, and are no longer read.'));
       } else {
-        await removeLocal(runtime.storage, runtime.skills, movable);
+        await removeLocal(runtime.storage, runtime.skills ?? null, movable, instances);
         print(ok('removed the local copies'));
       }
     } else if (movable.length > 0) {
@@ -280,7 +217,13 @@ async function useLocal(flags: KnowledgeFlags): Promise<void> {
       flags.migrate ??
       (await agreedTo(flags, `Copy everything in ${knowledge.repo} back onto this target's storage?`))
     ) {
-      const moved = await moveOut(repository, knowledge, local.storage, local.skills);
+      const moved = await moveOut(
+        repository,
+        knowledge,
+        local.storage,
+        local.skills,
+        grantedInstances(runtime.config),
+      );
       print(
         ok(
           `wrote back ${moved.memory} memory entr${moved.memory === 1 ? 'y' : 'ies'}, ` +
@@ -314,7 +257,7 @@ async function useLocal(flags: KnowledgeFlags): Promise<void> {
  */
 async function openLocalStores(
   runtime: Runtime,
-): Promise<{ storage: BlobStore; skills: BlobStore }> {
+): Promise<{ storage: BlobStore; skills: BlobStore | null }> {
   const { openStorage } = await import('#deployments/target.ts');
   const declared = runtime.declared;
 
@@ -327,7 +270,13 @@ async function openLocalStores(
     },
     runtime.credentials,
   );
-  return { storage: factory(), skills: factory(layout.skills(runtime.config.instance.profile)) };
+  // The *granted* connection, not the profile name. `layout.skills` changed
+  // meaning without changing arity at ADR-059, so the compiler was silent.
+  const skillsConnection = soleGrantFor(runtime.config, 'skills');
+  return {
+    storage: factory(),
+    skills: skillsConnection === undefined ? null : factory(layout.skills(skillsConnection)),
+  };
 }
 
 /**
@@ -386,3 +335,21 @@ async function agreedTo(flags: KnowledgeFlags, question: string): Promise<boolea
   if (!yes) print(style.dim('  cancelled'));
   return yes;
 }
+
+/**
+ * The memory and entities instances one profile grants.
+ *
+ * `main` where a profile grants none, which is what a profile that predates the
+ * owner layer looks like and is also where a fresh one puts them. The point is
+ * that this is never the *surface* — `memory/` alone matches every profile's
+ * notes now that the blob root is the workspace's.
+ */
+function grantedInstances(config: Parameters<typeof soleGrantFor>[0]): {
+  memory: string;
+  entities: string;
+} {
+  return {
+    memory: soleGrantFor(config, 'memory') ?? 'main',
+    entities: soleGrantFor(config, 'entities') ?? 'main',
+  };
+}

package/src/cli/commands/knowledge/migrate.ts

@@ -43,16 +43,71 @@ export interface Movable {
  * it once means `localContents`, `removeLocal` and `moveOut` each became a loop
  * over this rather than a branch on a literal.
  */
-type LocalArea = { readonly store: BlobStore; readonly prefix: string };
+/**
+ * One area's local home: where to look, and what of that key is the repository's.
+ *
+ * Two prefixes rather than one, and the difference is the whole fix. `scope` is
+ * what is listed — `memory/<instance>/`, so a profile sees only the instance it
+ * grants. `prefix` is what is stripped to get the repository path, which stays
+ * `memory/<instance>/<file>` because that is the layout ADR-041 documents and
+ * what makes two profiles' notes distinguishable in one repository.
+ *
+ * Collapsing them listed every profile's memory and then wrote it flat.
+ */
+type LocalArea = {
+  readonly store: BlobStore;
+  readonly scope: string;
+  readonly prefix: string;
+};
 
-function localAreas(storage: BlobStore, skills: BlobStore): Record<KnowledgeArea, LocalArea> {
+/** The connection ids this profile's memory and entities live under. */
+export interface Instances {
+  readonly memory: string;
+  readonly entities: string;
+}
+
+function localAreas(
+  storage: BlobStore,
+  skills: BlobStore | null,
+  /** Which instance of each surface this profile grants (ADR-059). */
+  instances: Instances,
+): Record<KnowledgeArea, LocalArea> {
   return {
-    memory: { store: storage, prefix: `${KNOWLEDGE_LAYOUT.memory}/` },
-    skills: { store: skills, prefix: '' },
-    entities: { store: storage, prefix: `${KNOWLEDGE_LAYOUT.entities}/` },
+    // Scoped to the instance this profile grants, not to the surface.
+    //
+    // `layout.blobs()` is the whole workspace since contract 3, so a prefix of
+    // `memory/` matched every profile's memory — and `knowledge use github
+    // --migrate --profile personal` therefore committed `work`'s notes to
+    // personal's repository and then deleted them locally, leaving `work`
+    // reading an empty store with no knowledge block of its own. `skills` was
+    // already connection-scoped, which is why it alone was correct.
+    memory: {
+      store: storage,
+      scope: `${KNOWLEDGE_LAYOUT.memory}/${instances.memory}/`,
+      prefix: `${KNOWLEDGE_LAYOUT.memory}/`,
+    },
+    // Null becomes an empty area rather than a refusal: a profile granting no
+    // skills connection has none to move, and `knowledge use` should still move
+    // its memory and entities rather than failing on the one area that is empty
+    // by construction (ADR-059).
+    skills: { store: skills ?? EMPTY_AREA, scope: '', prefix: '' },
+    entities: {
+      store: storage,
+      scope: `${KNOWLEDGE_LAYOUT.entities}/${instances.entities}/`,
+      prefix: `${KNOWLEDGE_LAYOUT.entities}/`,
+    },
   };
 }
 
+/** Nothing to list, nothing to delete. See `localAreas`. */
+const EMPTY_AREA: BlobStore = {
+  get: async () => null,
+  put: async () => {},
+  has: async () => false,
+  delete: async () => {},
+  list: async () => [],
+};
+
 const AREAS = ['memory', 'skills', 'entities'] as const;
 
 /**
@@ -66,16 +121,18 @@ const AREAS = ['memory', 'skills', 'entities'] as const;
  */
 export async function localContents(
   storage: BlobStore,
-  skills: BlobStore,
+  /** Null when the profile grants no skills connection (ADR-059). */
+  skills: BlobStore | null,
   knowledge: KnowledgeConfig,
+  instances: Instances,
 ): Promise<Movable[]> {
-  const areas = localAreas(storage, skills);
+  const areas = localAreas(storage, skills, instances);
   const found: Movable[] = [];
 
   for (const area of AREAS) {
-    const { store, prefix } = areas[area];
+    const { store, scope, prefix } = areas[area];
 
-    for (const entry of await store.list(prefix)) {
+    for (const entry of await store.list(scope)) {
       const data = await store.get(entry.key);
       if (data === null) continue; // Listed then deleted; not worth failing over.
 
@@ -128,10 +185,12 @@ export async function moveIn(
 /** Remove what has been verified elsewhere. Never called before `moveIn`. */
 export async function removeLocal(
   storage: BlobStore,
-  skills: BlobStore,
+  /** Null when the profile grants no skills connection (ADR-059). */
+  skills: BlobStore | null,
   movable: readonly Movable[],
+  instances: Instances,
 ): Promise<void> {
-  const areas = localAreas(storage, skills);
+  const areas = localAreas(storage, skills, instances);
 
   for (const item of movable) {
     const { store, prefix } = areas[item.area];
@@ -152,10 +211,12 @@ export async function moveOut(
   repository: GithubRepository,
   knowledge: KnowledgeConfig,
   storage: BlobStore,
-  skills: BlobStore,
+  /** Null when the profile grants no skills connection (ADR-059). */
+  skills: BlobStore | null,
+  instances: Instances,
 ): Promise<Record<KnowledgeArea, number>> {
   const { entries } = await repository.entries();
-  const areas = localAreas(storage, skills);
+  const areas = localAreas(storage, skills, instances);
   const counts: Record<KnowledgeArea, number> = { memory: 0, skills: 0, entities: 0 };
 
   for (const entry of entries.values()) {

package/src/cli/commands/knowledge/show.ts

@@ -0,0 +1,92 @@
+import { KNOWLEDGE_LAYOUT, layout, soleGrantFor } from '#profile';
+import { announce, emit, heading, print, style, table } from '../../output.ts';
+import { openRuntime } from '../../runtime.ts';
+import type { KnowledgeFlags } from './index.ts';
+
+/**
+ * `lanes link knowledge show` — where memory, skills and entities actually are.
+ *
+ * Split from `knowledge use` so `index.ts` stays inside the size budget, on the
+ * seam the two commands already have: this one opens stores and counts, and
+ * never writes. That difference is why `show` can answer for a repository `use`
+ * would refuse to touch.
+ */
+
+export async function knowledgeShow(flags: KnowledgeFlags): Promise<void> {
+  const runtime = await openRuntime(flags, { fetch: flags.fetch });
+  try {
+    if (!flags.json) announce(runtime.resolution);
+
+    const profile = runtime.config.instance.profile;
+    const selection = ` --profile ${runtime.resolution.profile} --target ${runtime.target}`;
+    const skills = runtime.skills ? (await runtime.skills.list()).length : 0;
+    const memory = (await runtime.storage.list(`${KNOWLEDGE_LAYOUT.memory}/`)).length;
+    const entities = (await runtime.storage.list(`${KNOWLEDGE_LAYOUT.entities}/`)).length;
+    const where = runtime.knowledge?.describe;
+    // Null when no skills connection is granted (ADR-059). The row still prints,
+    // saying so: a missing row reads as "there are none", not "not granted".
+    const skillsConnection = soleGrantFor(runtime.config, 'skills');
+
+    if (flags.json) {
+      print(
+        JSON.stringify(
+          { target: runtime.target, where: where ?? 'local', memory, skills, entities },
+          null,
+          2,
+        ),
+      );
+      return;
+    }
+
+    heading('Knowledge');
+    table([
+      // The memory *directory*, not the blob root it sits in. `layout.blobs`
+      // is `data/`, which is where every provider's namespace lives —
+      // printing it here would name a directory that is mostly not memory.
+      [
+        '  memory',
+        where ? `${where}/${KNOWLEDGE_LAYOUT.memory}` : `${layout.blobs()}/${KNOWLEDGE_LAYOUT.memory}`,
+        style.dim(`${memory} file${memory === 1 ? '' : 's'}`),
+      ],
+      [
+        '  skills',
+        where
+          ? `${where}/${KNOWLEDGE_LAYOUT.skills}`
+          : skillsConnection
+            ? layout.skills(skillsConnection)
+            : style.dim('not granted'),
+        style.dim(`${skills} file${skills === 1 ? '' : 's'}`),
+      ],
+      // The count includes the derived `_index.json`, deliberately: it is a
+      // file in that directory and it is committed with the rest, so a number
+      // that quietly excluded it would not match what a person sees there.
+      [
+        '  entities',
+        where
+          ? `${where}/${KNOWLEDGE_LAYOUT.entities}`
+          : `${layout.blobs()}/${KNOWLEDGE_LAYOUT.entities}`,
+        style.dim(`${entities} file${entities === 1 ? '' : 's'}`),
+      ],
+    ]);
+
+    print('');
+    print(
+      style.dim(
+        `  The vault, the credential store, runtime state and the audit log stay in workspace "${runtime.target}".`,
+      ),
+    );
+    // Complete commands, not shapes. Every one of these is pasted, and with
+    // nothing left to fall back on (ADR-037) a line missing either flag is a
+    // line that refuses — `emitted.test.ts` states the rule for the templates
+    // reachable without a runtime, and this is the same rule where there is one.
+    print(
+      style.dim(
+        where
+          ? `  Bring them back with: lanes link knowledge use local --migrate${selection}`
+          : `  Keep them in a repository with: lanes link knowledge use github --repo <owner/name>${selection}`,
+      ),
+    );
+  } finally {
+    await runtime.close();
+  }
+}

package/src/cli/commands/knowledge.ts

@@ -7,4 +7,5 @@
  * the grammar that puts them in order.
  */
 
-export { knowledgeShow, knowledgeUse, type KnowledgeFlags } from './knowledge/index.ts';
+export { knowledgeUse, type KnowledgeFlags } from './knowledge/index.ts';
+export { knowledgeShow } from './knowledge/show.ts';

package/src/cli/commands/mcp/harnesses.ts

@@ -17,12 +17,31 @@ import { join } from 'node:path';
  * command, write the file where it does not. A skill is content in a documented
  * location, not a config format we would be guessing at, and the directory
  * written is named after this project.
+ *
+ * **No registration carries a token any more** (ADR-062). Every endpoint runs
+ * the authorization flow, discovery is served ahead of the auth gate on
+ * loopback as well as deployed, and a client pointed at a bare URL finds
+ * `/.well-known/oauth-protected-resource`, signs its owner in at lanes.sh, and
+ * comes back with a token of its own. What that removes is worth stating: the
+ * registration no longer contains a credential, so a config file synced to a
+ * dotfiles repository is no longer a leak, and a rotation does not invalidate
+ * every harness at once.
+ *
+ * The exception is `tokenEnv`, which survives for the one caller that has no
+ * browser — see `token show`, which is now documented as a CI command.
  */
 
 export interface AddInput {
   readonly name: string;
   readonly url: string;
-  readonly token: string;
+  /**
+   * The endpoint's static token, for a harness that cannot run a browser.
+   *
+   * Nothing passes this in the ordinary path. It is here because
+   * `--headless` exists for CI, where there is no browser to complete an
+   * authorization in and a pasted credential is the only thing that works.
+   */
+  readonly token?: string | undefined;
   readonly tokenEnv: string;
   readonly scope: string;
   /**
@@ -44,11 +63,12 @@ export interface Harness {
   /** Whether `--scope` means anything here. Codex config is global. */
   readonly scoped: boolean;
   /**
-   * Whether the token is handed to the harness at all.
+   * Whether a credential reaches the harness's config at all.
    *
-   * Codex stores the *name* of an environment variable and reads it when it
-   * launches, so the secret never reaches its config file and a rotation is
-   * picked up without re-registering. Claude Code stores the header value.
+   * Both are `false` in the ordinary path now — the client authorises itself.
+   * This still distinguishes what a `--headless` registration would write:
+   * Claude Code would hold the header value, and Codex stores only the *name*
+   * of an environment variable it reads at launch.
    */
   readonly storesToken: boolean;
   /**
@@ -99,8 +119,10 @@ export const HARNESSES: readonly Harness[] = [
       'http',
       name,
       url,
-      '--header',
-      `Authorization: Bearer ${token}`,
+      // Only when there is no browser to sign in with. Registering the bare URL
+      // is the ordinary path: Claude Code discovers the protected-resource
+      // document and runs the authorization itself.
+      ...(token ? ['--header', `Authorization: Bearer ${token}`] : []),
       '--scope',
       scope,
     ],
@@ -142,7 +164,7 @@ export const HARNESSES: readonly Harness[] = [
       // anywhere else: an unresolvable substitution yields the empty string, the
       // header becomes "Bearer ", and the only symptom is a 401 that reads as a
       // bad token rather than a command that refused.
-      `    export ${tokenEnv}="$(lanes link token show --raw --profile ${profile} --target ${target})"`,
+      `    export ${tokenEnv}="$(lanes link token show --raw --profile ${profile} --workspace ${target})"`,
       '',
       'Add that to your shell profile. This is the better half of the bargain: the token never',
       'reaches ~/.codex/config.toml, and a "lanes link token rotate" is picked up on next launch',

package/src/cli/commands/mcp/onboarding.ts

@@ -0,0 +1,86 @@
+import { print } from '../../output.ts';
+
+/**
+ * `lanes link mcp install-instructions` — the block a client should be told once.
+ *
+ * A registration points a client at this endpoint. It does not tell the *model*
+ * anything, and the model is what decides whether to look here at all. The
+ * common failure is not a client that cannot reach the endpoint; it is one that
+ * can and answers from nothing anyway, because reaching for a tool is a habit
+ * and no habit is installed by adding a server to a config file.
+ *
+ * So this prints a short block for a person to paste into whatever their client
+ * treats as durable instruction — a project file, a custom instruction, a
+ * memory. It says where things are and what to read first, and nothing else:
+ * the full account lives at `lanes://instructions` and is served by the
+ * endpoint, so it can be corrected without anybody pasting anything again.
+ *
+ * **Printed rather than written.** Every client keeps this somewhere different
+ * and several keep it somewhere a person curates by hand. Writing into one of
+ * those is the class of thing ADR-016 puts on the other side of the line from
+ * `mcp add`: delegate where the harness owns a command, write the file only
+ * where it does not, and where neither is true, hand over the text.
+ */
+
+/** What each client calls the place this belongs, so the hint is actionable. */
+const WHERE: Record<string, string> = {
+  claude: 'CLAUDE.md in your project, or ~/.claude/CLAUDE.md for every project',
+  chatgpt: "Settings → Personalization → Custom instructions, under 'anything else'",
+  codex: 'AGENTS.md in your project, or ~/.codex/AGENTS.md',
+  cursor: '.cursor/rules/ in your project',
+};
+
+export interface InstallInstructionsFlags {
+  readonly client?: string | undefined;
+}
+
+export function installInstructions(flags: InstallInstructionsFlags = {}): void {
+  const client = flags.client?.toLowerCase();
+
+  if (client !== undefined && !(client in WHERE)) {
+    throw new Error(
+      `Unknown client "${client}". Known: ${Object.keys(WHERE).join(', ')}.\n` +
+        '  Omit --client for the block on its own.',
+    );
+  }
+
+  if (client !== undefined) {
+    // To stderr, so the block on stdout stays pasteable. Somebody piping this
+    // into a file wants the text and not the advice about where to put it.
+    process.stderr.write(`Paste this into ${WHERE[client]}:\n\n`);
+  }
+
+  print(BLOCK);
+}
+
+/**
+ * The block itself.
+ *
+ * Deliberately short and deliberately not a copy of the endpoint's own
+ * instructions. It exists to establish one habit — look here before answering
+ * from nothing — and to name the document that carries the rest. A longer block
+ * pasted into a project file is one that goes stale in a place nobody will
+ * think to update.
+ *
+ * No vendor names and no account details, for the same reason nothing under
+ * `server/` may carry one: what the owner connected is theirs.
+ */
+const BLOCK = `## Lanes Link
+
+Lanes Link is the route to my accounts, my memory, my notes, my saved procedures
+and my contacts. It is an MCP endpoint, and it is already connected.
+
+- Before saying you do not know something about me or my work, search memory.
+- Before using anyone's address or handle, look them up in entities. It returns
+  every match and never picks one; if there is more than one, ask me.
+- A thing for me to do is a task, not a memory. Tasks have a status.
+- If I have a saved procedure for something, tell me it exists and let me run it
+  rather than improvising your own version.
+- Before telling me something cannot be reached or that an account is missing,
+  ask the setup surface. It reports what exists and gives the exact command for
+  what does not. Run nothing yourself: every change here is mine to make.
+- Read \`lanes://instructions\` before your first call for the full account of
+  how routing, profiles and refusals work.
+
+Every tool takes a profile. A profile is how I keep things apart, so when it is
+ambiguous which one I mean, ask rather than picking the first.`;

package/src/cli/commands/mcp/register.ts

@@ -32,6 +32,17 @@ export interface McpAddOptions extends GlobalFlags {
   readonly force?: boolean | undefined;
   /** Register only; leave the skill and the agent alone. */
   readonly noSkill?: boolean | undefined;
+  /**
+   * Write the endpoint token into the registration, for a machine with no browser.
+   *
+   * The ordinary path registers a bare URL and the client authorises itself
+   * against lanes.sh (ADR-062), which is both safer and less to get wrong. This
+   * is the CI escape hatch, and it is a flag rather than a fallback because the
+   * difference has to be a decision somebody made: a registration that quietly
+   * embedded a credential when a browser was unavailable is one nobody would
+   * notice had done so.
+   */
+  readonly headless?: boolean | undefined;
 }
 
 export async function mcpAdd(target: string | undefined, options: McpAddOptions): Promise<void> {
@@ -71,17 +82,20 @@ export async function mcpAdd(target: string | undefined, options: McpAddOptions)
   const runtime = await openRuntime(options);
 
   try {
+    // Minted either way. The endpoint needs one to serve at all, and `outputs`
+    // prints it; what `--headless` decides is whether it is written into
+    // somebody's agent config.
     const { token } = await ensureProfileToken(runtime.credentials, runtime.config.auth.token_ref);
 
     // The target's own address, not the local one. This built
-    // `http://<host>:<port>/mcp` unconditionally, so `mcp add --target cloud`
+    // `http://<host>:<port>/mcp` unconditionally, so `mcp add --workspace cloud`
     // registered loopback with the agent: a registration that reports success,
     // names the right server, and points at a port with nothing behind it.
     const url = await endpointUrl(runtime.config, runtime.declared);
     const input: AddInput = {
       name,
       url,
-      token,
+      ...(options.headless === true ? { token } : {}),
       tokenEnv,
       scope,
       profile: runtime.resolution.profile,

package/src/cli/commands/mcp.ts

@@ -20,3 +20,4 @@ export { harnessCommands } from './mcp/harnesses.ts';
 export { mcpList } from './mcp/list.ts';
 export { mcpAdd, type McpAddOptions } from './mcp/register.ts';
 export { mcpStdio } from './mcp/stdio.ts';
+export { installInstructions, type InstallInstructionsFlags } from './mcp/onboarding.ts';