@lanes-sh/link 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,144 @@
+# Lanes Link
+
+**One secure endpoint between your AI agents and your real accounts, knowledge, and secrets.**
+
+Connect your mail, calendar, files, and notes once, and add the memory and skills that only you
+have. Every agent you use — Claude, ChatGPT, and anything else that speaks MCP — reaches them
+through a single MCP endpoint that you own and run. Open source, self-hosted, no vendor sitting in
+the middle of your data.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/lanes-link-dark.svg">
+  <img alt="Claude, ChatGPT, and any MCP client reach one Lanes Link endpoint, which you run on your own machine or your own cloud. The profiles it serves sit inside that boundary: Work, holding Gmail, Calendar, and Docs; and Personal, holding Gmail, Memory, and Skills." src="docs/images/lanes-link-light.svg">
+</picture>
+
+## Why
+
+- **Connect once, use everywhere.** No per-agent integrations, no re-authorising every new tool.
+- **You decide what agents can touch.** Permissions default to deny, and the runtime enforces
+  them — it does not ask the model to behave.
+- **Work and personal never mix.** Separate profiles, separate credentials, separate stores.
+- **Every call is recorded.** An append-only log of what was reached, and what was refused.
+
+## What people use it for
+
+- **A personal assistant on your phone.** A deployment is a URL, so the claude.ai or ChatGPT app
+  reaches your mail, calendar, and files from anywhere — "what's on tomorrow", "reply to Ana's
+  thread", "find the invoice from March". This is the case that needs [your own
+  cloud](#run-it-anywhere); everything below works on your machine.
+- **Inbox triage you sign off on.** An agent searches, reads, labels, and composes — and saves a
+  draft for you to send rather than sending it, until you decide otherwise.
+- **Coding agents that start from your context.** Claude Code and Codex reach the same Linear
+  issues, Notion pages, and notes you do, so a session begins from what you already know instead
+  of an empty prompt.
+- **One set of notes behind every agent.** What you have Claude Code write down, claude.ai reads
+  back later — your accumulated context follows you between tools instead of being trapped in
+  whichever one recorded it.
+- **Your own procedures, followed rather than guessed.** How a standup update reads, where an
+  invoice gets filed, who gets cc'd on a contract — written down once, and every agent you use
+  follows the same one.
+
+## Quickstart
+
+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
+ok    serving http://127.0.0.1:7337/mcp
+      profiles: personal
+```
+
+Then, in another shell:
+
+```console
+$ lanes link mcp add                           # every agent installed; or name one: claude, codex
+ok    registered lanes-link with Claude Code (user scope)
+ok    registered lanes-link with Codex
+```
+
+Your agents can now use it. Memory, skills, and the vault hold your own material rather than an
+account, so switching them on costs nothing — one command each, no credentials, no browser. Mail and
+calendar are the next step. **[Full quickstart →](docs/quickstart.md)**
+
+## What your agent gets
+
+| | | Manage it with |
+|---|---|---|
+| **Connections** | your external accounts — mail, calendar, files, issues | `lanes link connect` |
+| **Memory** | what you want remembered between sessions | `lanes link memory` |
+| **Skills** | your own procedures, handed to an agent as instructions | `lanes link skills` |
+| **Vault** | passwords and API keys, released only where you allow it | `lanes link vault` |
+
+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`.
+
+## Connect an account
+
+One command per account. Run it again to add a second mailbox, a second calendar, a second anything.
+
+| | Connect with |
+|---|---|
+| Gmail | `lanes link connect gmail` |
+| Google Drive | `lanes link connect drive` |
+| Google Sheets | `lanes link connect sheets` |
+| Google Docs | `lanes link connect docs` |
+| Google Calendar | `lanes link connect calendar` |
+| Google Tasks | `lanes link connect tasks` |
+| Google Contacts | `lanes link connect contacts` |
+| iCloud Mail | `lanes link connect icloud_mail` |
+| iCloud Calendar | `lanes link connect icloud_calendar` |
+| iCloud Contacts | `lanes link connect icloud_contacts` |
+| iCloud Drive | `lanes link connect icloud_drive` |
+| Notion | `lanes link connect notion` |
+| Linear | `lanes link connect linear` |
+| Gmail (Google MCP) | `lanes link connect gmail_mcp` |
+| Drive (Google MCP) | `lanes link connect drive_mcp` |
+
+Two things worth knowing up front: `lanes link connect icloud` sets up Mail, Calendar, and Contacts
+together, because one app-specific password covers all three. And 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.
+
+Full guide — what each one gives your agent, what it needs, and adding your own:
+**[docs/connect.md](docs/connect.md)**.
+
+## Run it anywhere
+
+The same code, the same config, in all three. Only the storage adapters change.
+
+| | **Local** | **Your own cloud** | **Lanes Cloud** |
+|---|---|---|---|
+| Runs on | your machine | your GCP project, on Cloud Run | managed for you |
+| Needs | Bun, nothing else | a Google Cloud billing account | — |
+| Set up with | `lanes link start` | `lanes link deploy` | [join the waitlist](https://lanes.sh/forms/f/a46d8b45-4759-485b-841c-d117a823b645) |
+| Reachable from | that machine | anywhere, including your phone | anywhere |
+| Status | ready | ready | **coming soon** |
+
+**Local** is the fastest way to start, and where most people stay. **Your own cloud** is what you
+want if you need to reach it from claude.ai, ChatGPT, or a phone — `lanes link deploy` creates the
+project, the bucket, the service account, and the revision on its first run. **Lanes Cloud** is the
+managed version; because it is the same data model, a workspace you build today moves across rather
+than being rebuilt.
+[Join the waitlist](https://lanes.sh/forms/f/a46d8b45-4759-485b-841c-d117a823b645) to hear when it opens.
+
+## Docs
+
+- **[Quickstart](docs/quickstart.md)** — from nothing to a working endpoint
+- **[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
+- **[Full reference](docs/detailed/)** — architecture, configuration, the CLI, the security model,
+  writing a provider, and the decision records
+
+## Security
+
+Lanes Link holds live credentials to your email and documents. The
+[security model](docs/detailed/security.md) states its limits plainly rather than implying
+guarantees the code does not deliver — read it before you trust it with an account. To report a
+vulnerability, see [`SECURITY.md`](SECURITY.md); please do not open a public issue.
+
+## License
+
+[Apache-2.0](LICENSE)

package/bin/lanes

@@ -0,0 +1,42 @@
+#!/bin/sh
+#
+# The `lanes` command, as installed from npm.
+#
+# `src/cli/lanes.ts` carries `#!/usr/bin/env bun`, and pointing package.json's
+# `bin` straight at it was the obvious thing — until a machine without Bun
+# installs cleanly and then answers every invocation with
+# `env: bun: No such file or directory`, which names neither this project nor
+# the thing it is missing. A `#!/usr/bin/env node` shim inverts the problem for
+# anyone who has Bun and not Node. `/bin/sh` is the one interpreter present in
+# both cases, so the check lives here.
+#
+# This is also what `bun link` puts on the PATH during development, so the
+# installed path and the contributor path are one path rather than two.
+
+set -e
+
+# npm and bun both install a bin as a symlink in a global directory, so "$0" is
+# the link rather than this file, and "$(dirname "$0")/.." is that directory's
+# parent rather than the package. `readlink -f` would resolve it in one call and
+# does not exist on macOS, which is where most of these installs land.
+self=$0
+while [ -L "$self" ]; do
+  link=$(readlink "$self")
+  case $link in
+    /*) self=$link ;;
+    *) self=$(dirname "$self")/$link ;;
+  esac
+done
+root=$(cd "$(dirname "$self")/.." && pwd)
+
+if ! command -v bun >/dev/null 2>&1; then
+  echo "lanes needs Bun 1.3.11+ to run — it is not on your PATH." >&2
+  echo "" >&2
+  echo "  curl -fsSL https://bun.sh/install | bash" >&2
+  echo "  brew install bun" >&2
+  echo "" >&2
+  echo "Then run this command again. Nothing else is needed." >&2
+  exit 1
+fi
+
+exec bun run "$root/src/cli/lanes.ts" "$@"

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

@@ -0,0 +1,73 @@
+---
+name: lanes-link-scout
+description: Use when answering a question needs a wide read across someone's Lanes Link context — searching their memory, mail, files, and issues for the same thing and reporting back what is there. Good for "have I discussed X anywhere", "find everything about this client", "what do we already know about Y". Not for acting on what it finds: this agent reads and reports, and every write stays in the main thread.
+---
+
+# Lanes Link scout
+
+You search one person's own context through the `lanes-link` MCP server and
+report what you found. A wide sweep across mail, files, notes, and issues costs
+a lot of reading, and the point of doing it here is that only the answer goes
+back — not the forty results you rejected on the way.
+
+## What you return
+
+A digest, not a transcript. For each thing you found that matters: what it is,
+where it is (the profile, the connection, and the identifier — a message id, a
+file name, a memory entry id), and the one or two lines that make it relevant.
+Enough that the main thread can open any of them directly without searching
+again.
+
+Say what you did **not** find, and where you looked. "Nothing in memory or mail
+about this" is a real answer and is often the useful one. So is "the endpoint
+serves a `work` profile I did not search, because you asked about personal."
+
+Quote sparingly. You are reading someone's mail and notes; pull the sentence
+that answers the question, not the surrounding thread.
+
+## How to search
+
+Ask the endpoint what it has rather than assuming. Its instructions name the
+profiles and connections that are actually reachable.
+
+**Start with memory.** It is the only source that is already the owner's own
+distillation, and it is small enough to search several ways cheaply. Substring
+matching, not ranked relevance — so try the obvious phrasing, then a synonym,
+then a narrower fragment, before concluding something is not there.
+
+**Then the accounts,** narrowing by whatever the provider gives you — a date
+range, a label, a folder. A broad query returning two hundred results and a
+narrow one returning none are both failures; move between them deliberately
+rather than retrying the same shape.
+
+**One profile unless told otherwise.** Profiles are how someone separates work
+from personal. If the question does not say which, search the one the
+conversation is about and name the other in your report rather than reaching
+into it.
+
+## Read, do not write
+
+Report what you found and stop. Do not send, move, label, delete, or store
+anything, and do not write a memory entry to "save" what you learned — the main
+thread decides what is worth keeping, and an entry written here is served back
+to every future session.
+
+**This instruction is guidance, and guidance is not a boundary.** What actually
+stops a write is policy on the endpoint:
+
+```console
+$ lanes link policy deny memory.write
+$ lanes link policy list
+```
+
+If you are running against a profile that grants writes, that is the owner's
+configuration and this file does not override it — so hold the line yourself,
+and say plainly in your report if you were asked to do something that would have
+needed one.
+
+## When a call is refused
+
+It was refused on purpose. Only permitted capabilities are visible at all, so a
+missing tool was not granted and retrying will not reveal it. Note the refusal in
+your report and carry on with the sources you can reach — do not look for another
+route to the same data.

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

@@ -0,0 +1,187 @@
+---
+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.
+---
+
+# Lanes Link
+
+A self-hosted gateway to one person's own context: the accounts they have
+connected, the knowledge they have accumulated, the procedures they have
+written down, and their secrets. One endpoint serves every profile in a
+workspace under one token, and each call names which profile it means.
+
+The endpoint describes its own live state when you connect — which profiles
+exist, what is reachable in each. This file is the part that does not change:
+how to behave with it.
+
+## Profiles are a boundary, not a setting
+
+Every tool takes `profile` and `connection`. Profiles are how someone keeps work
+and personal apart; they share no database and no credential store.
+
+**Ask which profile is meant when it is ambiguous. Do not default to whichever
+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.
+
+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.
+
+## Reach for memory before answering from nothing
+
+`memory.search` before concluding you do not know something about this person or
+their work. It is a substring search over their own notes, not a ranked index —
+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.
+
+## Skills are theirs, not yours
+
+A skill is a procedure the owner wrote down. They arrive as prompts — slash
+commands — and are selected by the person rather than chosen by the model. You
+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>`.
+
+## Vault values are credentials
+
+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.
+
+## Attachments are named, not carried
+
+Where a tool takes `attachments`, each entry names **one** source and the endpoint
+reads the bytes itself. Naming two is refused rather than resolved.
+
+```jsonc
+{ "path": "/Users/them/Downloads/invoice.pdf" }         // on the endpoint's own machine
+{ "url": "https://example.com/invoice.pdf" }            // fetched here, HTTPS only
+{ "message_id": "18f…", "attachment_id": "quote.pdf" }  // already on a message in that mailbox
+{ "handle": "att_01j7k…" }                              // staged out of band
+{ "data": "JVBERi0…", "filename": "invoice.pdf" }       // base64, and a last resort
+```
+
+`attachment_id` takes a filename, a position, or the vendor's own id, and can be
+omitted when the message has one attachment. `filename` and `content_type`
+override what the source implies.
+
+**Never encode a file into a call.** A 239 KB PDF is roughly 320,000 characters
+of base64 — more than you can write in one message — and the way that fails is a
+mail which mentions an attachment and does not have one. The other four sources
+exist so you never have to.
+
+**Forwarding something that arrived by mail is free.** Use `message_id` rather
+than fetching the attachment and passing its bytes along. Reading them is not
+offered anyway: the read tools report each attachment's name, type and size, not
+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
+handle to use instead.
+
+**`draft_only: true`** saves instead of sending, where they should see it before
+it goes out.
+
+Sent mail shows the account's own name when the connection sets `from_name`. If
+something you sent arrived as a bare address, say so — it is a one-line config
+fix, not a reason to write a signature into the body.
+
+Every send records each attachment's filename, size, type and digest, and where
+the bytes came from.
+
+## A refusal is the system working
+
+Only permitted capabilities are visible at all, so something missing was not
+granted, and retrying will not reveal it. A call that *is* refused was refused by
+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>`
+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`
+shows what was attempted, refusals included.
+
+## Setting something up
+
+Call `setup_overview` before answering any question about what you can reach, and
+before suggesting that anything be connected. It names the accounts reachable in a
+profile and the providers that are not connected yet. `setup_provider` then gives
+one provider's console steps, the values it will ask for, and the exact command.
+
+**Take the command from `setup_provider`; never compose one yourself.** It carries
+the right profile and, where the provider stores a credential per account, the
+`--id` it needs. A command you assembled is one the owner pastes and watches fail.
+
+You cannot do the setup. This endpoint writes no configuration and stores no
+credential — those are `lanes link` in a terminal, deliberately. What you can do is
+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.
+Anything with a browser sign-in belongs to whoever owns the account — give them
+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.
+
+## Registering it, and re-registering it
+
+`lanes link mcp add` 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
+a value rather than a command.
+
+**Never paste the token.** There is a right way and a wrong way, and the
+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)"
+
+# 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
+```
+
+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`.
+
+Prefer `lanes link mcp add` 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` 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.
+
+If you register Codex, tell the user to export the token — Codex stores only the
+variable name, so nothing works until it is set:
+
+```bash
+export LANES_LINK_TOKEN="$(lanes link token show --raw)"
+```
+
+One registration covers every profile. Do not add one per profile; they share a
+URL and a token.
+
+## When it is not running
+
+`lanes link start` 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.