@lanes-sh/link 0.2.2 → 0.3.1

package/README.md

@@ -48,8 +48,8 @@ Needs [Bun](https://bun.com) 1.3.11+. Nothing else — no account anywhere.
 
 ```console
 $ bun install -g @lanes-sh/link                # puts `lanes` on your PATH
-$ lanes link profile add personal --default
-$ lanes link start
+$ lanes link profile add personal --target local
+$ lanes link start --profile personal --target local
 ok    serving http://127.0.0.1:7337/mcp
       profiles: personal
 ```
@@ -57,7 +57,7 @@ ok    serving http://127.0.0.1:7337/mcp
 Then, in another shell:
 
 ```console
-$ lanes link mcp add                           # every agent installed; or name one: claude, codex
+$ lanes link mcp add --profile personal --target local                           # every agent installed; or name one: claude, codex
 ok    registered lanes-link with Claude Code (user scope)
 ok    registered lanes-link with Codex
 ```
@@ -78,6 +78,17 @@ calendar are the next step. **[Full quickstart →](docs/quickstart.md)**
 Memory and skills are plain Markdown files, so a text editor and an agent reach the same bytes. All
 four belong to one profile: what you add under `work` is invisible under `personal`.
 
+Keep those two in a private GitHub repository instead of on this machine, and get history, diffs,
+and the same notes from anywhere you run this:
+
+```console
+$ lanes link knowledge use github --repo <owner/name> --migrate
+```
+
+It moves what you have already stored, in one commit, and `lanes link knowledge use local
+--migrate` brings it back. Nothing else moves — your credentials and your vault stay where they
+are, and there is no setting that would put them in a repository.
+
 ## Connect an account
 
 One command per account. Run it again to add a second mailbox, a second calendar, a second anything.
@@ -99,15 +110,17 @@ 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` |
+| 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` |
 
 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 needs no OAuth client
-of your own: `lanes link connect gmail` authorises against the one Lanes operates, so there is no
-Cloud console to visit — add `--own-client` if you would rather register your own. And GitHub and
-Slack take a token you paste rather than a browser sign-in, because neither will register a client
-for us; for Slack that means creating a Slack app once, which is the one console visit left here.
+Contacts together, because one app-specific password covers all three. 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.
 
 Full guide — what each one gives your agent, what it needs, and adding your own:
 **[docs/connect.md](docs/connect.md)**.
@@ -137,6 +150,7 @@ than being rebuilt.
 - **[Connect your accounts](docs/connect.md)** — every provider, and what each one needs
 - **[Add it to your agent](docs/clients.md)** — Claude Code, Codex, Claude Desktop, claude.ai, ChatGPT
 - **[Deploy to your own cloud](docs/deploy.md)** — five commands to a URL
+- **[Every command](docs/detailed/commands.md)** — arguments and flags, one entry each
 - **[Full reference](docs/detailed/)** — architecture, configuration, the CLI, the security model,
   writing a provider, and the decision records
 

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

@@ -24,6 +24,13 @@ 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.
+
 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*
 profile is refused rather than guessed at.
@@ -37,7 +44,7 @@ try more than one wording before deciding it is not there.
 Writing is a separate grant, and it should be. What you write is served back to
 every later session, including to a different agent, so **write when you are
 asked to remember something, not as a habit.** The owner reaches the same
-entries with `lanes link memory list` and a text editor.
+entries with `lanes link memory list --profile <name> --target <name>` and a text editor.
 
 ## Skills are theirs, not yours
 
@@ -47,7 +54,7 @@ cannot read a skill's body; that is deliberate, not a gap to work around.
 
 So when a task has a skill for it, **say the skill exists and let them invoke
 it** rather than improvising your own version of their procedure. They manage
-these with `lanes link skills list` and `lanes link skills show <name>`.
+these with `lanes link skills list --profile <name> --target <name>` and `lanes link skills show <skill> --profile <name> --target <name>`.
 
 ## Vault values are credentials
 
@@ -55,6 +62,27 @@ Use one to do the thing that needs it. Never quote it back, summarise it, echo
 it into a file, or paste it into a command whose output you will show. If a
 value has been printed by accident, say so.
 
+## Who you are writing as is declared, not inferred
+
+A profile may declare the names, addresses and handles its owner wants used when
+something is written as them. Call `identity_list` for the profile in play
+before signing a message, choosing an address to send from, or attributing work
+to a handle — **do not** read a name off the conversation, off a previous
+message's signature, or off the account label on a connection. That label is the
+identity a provider reports for a mailbox; it is not necessarily what they sign
+with.
+
+A profile may declare several of a kind on purpose. The first is the default and
+each carries a note saying when to prefer it, so read the notes rather than
+picking the first unconditionally. If none of them fits what you are doing, ask
+— do not combine two, and do not carry one profile's name into another. That
+crossing is the specific mistake this exists to prevent.
+
+If the tool is not there, the profile has declared nothing. Ask rather than
+inventing something; they add one with `lanes link identity add <kind> <value> --profile <profile>
+--target <target>` — both flags, because neither has a fallback.
+Nothing you can call writes here, deliberately.
+
 ## Attachments are named, not carried
 
 Where a tool takes `attachments`, each entry names **one** source and the endpoint
@@ -84,7 +112,7 @@ its content.
 
 **If the endpoint is not on the same machine as the file**, `path` names the
 *server's* filesystem rather than theirs, and will not find it. Ask them to run
-`lanes link attach <file> --connection <provider>.<account>`, which prints a
+`lanes link attach <file> --profile <name> --target <name> --connection <provider>.<account>`, which prints a
 handle to use instead.
 
 **`draft_only: true`** saves instead of sending, where they should see it before
@@ -104,9 +132,9 @@ granted, and retrying will not reveal it. A call that *is* refused was refused b
 policy on purpose.
 
 Report it plainly and let the owner decide whether to widen the grant —
-`lanes link policy list` shows the rules, `lanes link policy allow <capability>`
+`lanes link policy list --profile <name>` shows the rules, `lanes link policy allow <capability> --profile <name> --target <name>`
 changes them, and that is their call, not yours. **Do not look for another route
-to the same data.** Every call is audited either way; `lanes link audit tail`
+to the same data.** Every call is audited either way; `lanes link audit tail --profile <name> --target <name>`
 shows what was attempted, refusals included.
 
 ## Setting something up
@@ -125,9 +153,9 @@ credential — those are `lanes link` in a terminal, deliberately. What you can
 know exactly what to hand over, and say what it will ask for before they start.
 
 If you have a shell, you can run it yourself for anything that does *not* need a
-browser: `lanes link setup plan <provider> --json` lists what to store,
-`lanes link secrets set <ref>` takes the value on stdin, and
-`lanes link connect <provider> --id <name> --non-interactive --json` finishes.
+browser: `lanes link setup plan <provider> --profile <name> --target <name> --json` lists what to store,
+`lanes link secrets set <ref> --profile <name> --target <name>` takes the value on stdin, and
+`lanes link connect <provider> --profile <name> --target <name> --id <id> --non-interactive --json` finishes.
 Anything with a browser sign-in belongs to whoever owns the account — give them
 the line.
 
@@ -139,10 +167,10 @@ straight after connecting will still not show it. Say so rather than retrying.
 
 ## Registering it, and re-registering it
 
-`lanes link mcp add` runs each harness's own registration command and installs
+`lanes link mcp add --profile <name> --target <name>` runs each harness's own registration command and installs
 this skill where that harness keeps them. With no argument it does every harness
 installed; name one (`claude`, `codex`) to be specific. Run it again after
-`lanes link token rotate` — add `--force`, since Claude Code stores the token as
+`lanes link token rotate --profile <name> --target <name>` — add `--force`, since Claude Code stores the token as
 a value rather than a command.
 
 **Never paste the token.** There is a right way and a wrong way, and the
@@ -151,7 +179,7 @@ difference matters:
 ```bash
 # RIGHT — the token goes from the CLI to the harness. You never see it.
 claude mcp add --transport http lanes-link http://127.0.0.1:7337/mcp \
-  --header "Authorization: Bearer $(lanes link token show --raw)"
+  --header "Authorization: Bearer $(lanes link token show --raw --profile <name> --target <name>)"
 
 # WRONG — the token is now in your context, and in the transcript, forever.
 lanes link token show --show          # then copying the value into the command
@@ -159,9 +187,9 @@ lanes link token show --show          # then copying the value into the command
 
 The token reaches every account of every profile the endpoint serves. Use the
 substitution form. If you have already printed one by accident, say so and offer
-`lanes link token rotate`.
+`lanes link token rotate --profile <name> --target <name>`.
 
-Prefer `lanes link mcp add` to writing the command yourself: it checks the
+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
@@ -173,7 +201,7 @@ If you register Codex, tell the user to export the token — Codex stores only t
 variable name, so nothing works until it is set:
 
 ```bash
-export LANES_LINK_TOKEN="$(lanes link token show --raw)"
+export LANES_LINK_TOKEN="$(lanes link token show --raw --profile <name> --target <name>)"
 ```
 
 One registration covers every profile. Do not add one per profile; they share a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lanes-sh/link",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "A self-hostable MCP gateway for all your connections, memory, skills, and secrets",
   "license": "Apache-2.0",
   "homepage": "https://lanes.sh/link",

package/src/cli/argv.ts

@@ -1,5 +1,6 @@
 import type { GlobalFlags } from './runtime.ts';
 import type { OwnerFlags } from './commands/owner.ts';
+import type { KnowledgeFlags } from './commands/knowledge.ts';
 
 /**
  * Turning argv into a command path and a flag bag.
@@ -63,6 +64,32 @@ export function text(flags: Flags, name: string): string | undefined {
   return typeof value === 'string' ? value : undefined;
 }
 
+/**
+ * Every value given for a flag, in order.
+ *
+ * `profile add --target local --target cloud` is the one command where a flag
+ * legitimately repeats: it is declaring a list, not selecting one thing. The
+ * parser keeps the last value in `flags`, so this re-reads argv rather than
+ * changing that shape for every other flag's sake.
+ */
+export function all(argv: readonly string[], name: string): string[] {
+  const values: string[] = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i]!;
+    if (token === `--${name}`) {
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith('--')) values.push(next);
+      continue;
+    }
+    if (token.startsWith(`--${name}=`)) values.push(token.slice(name.length + 3));
+  }
+
+  // Comma-separated is the other spelling people reach for, and refusing it
+  // would be a refusal with no reason behind it.
+  return values.flatMap((value) => value.split(',').map((part) => part.trim())).filter(Boolean);
+}
+
 /** The flags every command accepts. */
 export function globalFlags(flags: Flags): GlobalFlags {
   return {
@@ -92,3 +119,26 @@ export function ownerFlags(flags: Flags): OwnerFlags {
     yes: flags['yes'] === true,
   };
 }
+
+/**
+ * `lanes link knowledge`'s flags.
+ *
+ * Here for the reason `ownerFlags` is: the kebab-case spellings belong in the
+ * one place that parses argv, so `--allow-public` is written once rather than
+ * once per reader.
+ */
+export function knowledgeFlags(flags: Flags): KnowledgeFlags {
+  return {
+    ...globalFlags(flags),
+    repo: text(flags, 'repo'),
+    branch: text(flags, 'branch'),
+    path: text(flags, 'path'),
+    // `--migrate`, `--no-migrate`, or neither — see `KnowledgeFlags.migrate`.
+    migrate: flags['migrate'] === true ? true : flags['no-migrate'] === true ? false : undefined,
+    keep: flags['keep'] === true,
+    allowPublic: flags['allow-public'] === true,
+    replace: flags['replace'] === true,
+    yes: flags['yes'] === true,
+    json: flags['json'] === true,
+  };
+}

package/src/cli/brand.ts

@@ -0,0 +1,178 @@
+/**
+ * The Lanes design tokens, and the pieces every page this repository serves is
+ * built from.
+ *
+ * Three surfaces render HTML — the authorization consent screen, the page a
+ * connect flow lands on, and the dashboard — and until this file existed each
+ * carried its own approximation of the brand. They had drifted: two greens and
+ * two ambers that are not tokens at all, nine different alphas standing in for
+ * one border colour, a destructive red with a dark variant the token does not
+ * have, and the system font stack where Geist belongs.
+ *
+ * Values are transcribed from https://lanes.sh/design/foundations. The rules
+ * they express, which the CSS below encodes rather than restates:
+ *
+ * - **Gold is the only accent.** "Gold for positive, neutral tokens otherwise."
+ *   That is why there is no green here: a connection that works is `positive`,
+ *   which is gold, and everything else is one of two neutrals. `--destructive`
+ *   is for errors, not for a state that merely needs attention.
+ * - **Two weights, 400 and 500.** Nothing else is available in the loaded faces,
+ *   so a heavier rule would silently synthesise.
+ * - **Lora heads, Geist speaks, Geist Mono for code and eyebrow labels.**
+ *
+ * `--border`, `--accent-gold` and `--destructive` are constant across themes.
+ * Only the five neutrals swap, which is why the dark block below is five lines
+ * rather than a second stylesheet.
+ */
+
+/**
+ * Escape text for an HTML body.
+ *
+ * `escapeXml` in `connectivity/transports/dav/xml.ts` would do, and `cli` is
+ * allowed to import `connectivity` — but a page renderer reaching into a DAV
+ * transport for a string function is a dependency nobody would defend. Five
+ * lines is cheaper than the coupling.
+ *
+ * Load-bearing: these pages render a provider's `manifest.name`, and a custom
+ * provider supplies that from a YAML file of its own.
+ */
+export function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/**
+ * One request for all three faces.
+ *
+ * `preconnect` to both hosts because the stylesheet and the font files it names
+ * are served from different origins, and the second lookup is otherwise not
+ * started until the first has parsed.
+ */
+export const FONTS =
+  '<link rel="preconnect" href="https://fonts.googleapis.com">\n' +
+  '<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>\n' +
+  '<link href="https://fonts.googleapis.com/css2?family=Geist+Mono:wght@400;500' +
+  '&amp;family=Geist:wght@400;500&amp;family=Lora:wght@400;500&amp;display=swap" rel="stylesheet">';
+
+/** The one-row footer, identical to the one the Lanes API's own pages carry. */
+export const FOOTER =
+  '<div class="footer"><p>Your unfair advantage in parallel AI coding. ' +
+  '<a href="https://lanes.sh/">lanes.sh</a></p></div>';
+
+/**
+ * The tokens, and the base every page shares.
+ *
+ * The background is **painted**, which reverses what these pages used to do.
+ * The old note read "nothing is painted" — a transparent body under
+ * `color-scheme: light dark` so the browser supplied its own canvas — and it
+ * was written to fix a hardcoded `#0d1117` that showed as a black rectangle on
+ * a light machine. The design system settles that differently: it names a
+ * background for each mode, so the fix is to paint the right one rather than
+ * none. `color-scheme` stays, because form controls and scrollbars still need
+ * to know which mode they are in.
+ */
+export const TOKENS = `
+:root {
+  color-scheme: light dark;
+  --background: #EBEAE7;
+  --card: #F0EFEC;
+  --muted: #E2E1DD;
+  --foreground: #171717;
+  --muted-foreground: #202329;
+  --border: rgba(120,113,108,0.2);
+  --accent-gold: #A1845A;
+  --destructive: #A06060;
+  /* The two tints the badge variants need. Spelled as rgba rather than
+     color-mix because the consent screen opens in whatever browser a phone
+     happens to use, and both accents are constant across themes anyway. */
+  --gold-fill: rgba(161,132,90,0.1);
+  --gold-ring: rgba(161,132,90,0.25);
+  --destructive-fill: rgba(160,96,96,0.1);
+  --destructive-ring: rgba(160,96,96,0.25);
+  --sans: "Geist", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  --serif: "Lora", Georgia, "Times New Roman", serif;
+  --mono: "Geist Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --background: #171717;
+    --card: #292524;
+    --muted: #202329;
+    --foreground: #EBEAE7;
+    --muted-foreground: #A8A29E;
+  }
+}
+* { box-sizing: border-box; }
+body { margin: 0; font-family: var(--sans); font-weight: 400;
+       background: var(--background); color: var(--foreground); }
+h1, h2, h3 { font-family: var(--serif); font-weight: 500; letter-spacing: -0.01em; margin: 0; }
+h1 { font-size: 28px; line-height: 1.3; }
+code, .mono { font-family: var(--mono); }
+a { color: inherit; }
+
+/* Eyebrow: 11px, uppercase, wide tracking, muted — and mono, which is where the
+   design system puts label type. */
+.eyebrow { font-family: var(--mono); font-size: 11px; font-weight: 400;
+           letter-spacing: 0.09em; text-transform: uppercase; color: var(--muted-foreground);
+           opacity: 0.75; }
+
+/* Surfaces are dashed and 10px; controls are 6px; pills are round. */
+.surface { background: var(--card); border: 1px dashed var(--border); border-radius: 10px; }
+
+/* The four badge variants, as the design system defines them: gold for
+   positive, neutral tokens otherwise, destructive for an error only. The ring
+   is an inset shadow so it costs no layout, exactly as \`ring-inset\` does. */
+.pill { display: inline-flex; align-items: center; flex: none; white-space: nowrap;
+        font-size: 11px; font-weight: 500; letter-spacing: 0.02em;
+        padding: 2px 8px; border-radius: 999px; box-shadow: inset 0 0 0 1px var(--border); }
+.pill.positive { background: var(--gold-fill); color: var(--accent-gold);
+                 box-shadow: inset 0 0 0 1px var(--gold-ring); }
+.pill.neutral { background: var(--muted); color: var(--muted-foreground); }
+.pill.quiet { background: transparent; color: var(--muted-foreground); opacity: 0.7; }
+.pill.negative { background: var(--destructive-fill); color: var(--destructive);
+                 box-shadow: inset 0 0 0 1px var(--destructive-ring); }
+
+/* Ghost is the variant every button on these pages is: muted until it is
+   wanted, and never gold, because gold is reserved for saying a thing is good. */
+.btn { font: inherit; font-size: 12px; font-weight: 500; line-height: 1;
+       padding: 6px 9px; border-radius: 6px; cursor: pointer;
+       background: transparent; color: var(--muted-foreground);
+       border: 1px solid var(--border); }
+.btn:hover, .btn:focus-visible { color: var(--foreground); background: var(--muted); }
+
+.footer { margin: 40px 0 0; text-align: center; }
+.footer p { margin: 0; font-size: 12px; line-height: 1.5; color: var(--muted-foreground); opacity: 0.75; }
+.footer a { text-decoration: underline; }
+`.trim();
+
+/**
+ * What every page these modules serve loads, and nothing else.
+ *
+ * The font stylesheet and the faces it names are the only two origins any of
+ * them reaches; `default-src 'none'` closes the rest. No `script-src`, because
+ * these pages have no script — the dashboard, which has one listener, extends
+ * this rather than replacing it.
+ */
+export const PAGE_CSP =
+  "frame-ancestors 'none'; default-src 'none'; " +
+  "style-src 'unsafe-inline' https://fonts.googleapis.com; " +
+  'font-src https://fonts.gstatic.com';
+
+/**
+ * Headers every page here answers with.
+ *
+ * `frame-ancestors` in both spellings: one of these pages asks for the endpoint
+ * token and another lists the owner's accounts, and framing either is the cheap
+ * half of a UI-redress attack. The URLs carry a `client_id`, a `redirect_uri`,
+ * or a one-time key, none of which belongs in a Referer.
+ */
+export const PAGE_HEADERS: Readonly<Record<string, string>> = {
+  'content-type': 'text/html; charset=utf-8',
+  'content-security-policy': PAGE_CSP,
+  'x-frame-options': 'DENY',
+  'referrer-policy': 'no-referrer',
+};