ref-tools · MatthewDailey · Jul 9, 2026 · Jul 9, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,37 @@
+# AGENTS.md
+
+## Cursor Cloud specific instructions
+
+This repository is the **Mintlify documentation site for Ref** (published at
+[docs.ref.tools](https://docs.ref.tools)). It contains only docs content: `.mdx`
+pages, images/logos, `docs.json` (Mintlify site config), `style.css`, and
+`modify.js`. There is **no application backend, no `package.json`, no database,
+and no test suite** in this repo — the actual products (the Ref MCP server and
+Ref Plans app) live in separate repositories.
+
+### Tooling
+
+- Docs are rendered by the **Mintlify CLI** (`mint`), installed globally by the
+  startup update script. Verify with `mint --version`.
+- The CLI is invoked from the repo root (where `docs.json` lives).
+
+### Run / preview
+
+- `mint dev` — serves the docs locally at `http://localhost:3000` (also binds a
+  network address). First launch shows `preparing local preview...` then
+  `preview ready`; give it a few seconds before curling the port.
+
+### Lint / test / build
+
+- There is **no lint step, no automated tests, and no local build/deploy step**.
+  Mintlify builds and deploys automatically on push via the hosted platform.
+- `mint broken-links` is the closest thing to a validation/lint check — it
+  reports broken internal links. Note there are pre-existing broken links in the
+  repo (e.g. `/resources`); a non-empty result is not necessarily caused by your
+  changes.
+
+### Non-obvious gotchas
+
+- The site's search bar is Ref's **authenticated** search ("Login into CLI to
+  enable search"), not standard Mintlify search — it will not return results
+  locally without CLI login. This is expected, not a bug.
diff --git a/docs.json b/docs.json
@@ -152,7 +152,8 @@
               "plans/integrations/linear",
               "plans/integrations/asana",
               "plans/integrations/github",
-              "plans/integrations/slack"
+              "plans/integrations/slack",
+              "plans/integrations/custom-launchers"
             ]
           },
           {

diff --git a/plans/integrations/custom-launchers.mdx b/plans/integrations/custom-launchers.mdx
@@ -0,0 +1,85 @@
+---
+title: "Custom Launchers"
+description: "Deep-link into Ref Plans from any tool that can construct a URL."
+---
+
+import GetHelp from '/snippets/get-help.mdx';
+
+Custom launchers let external tools open Ref Plans directly. Build a link to `https://plan.ref.tools/new`, optionally include starting content or a first agent prompt, and send users into a new plan.
+
+## URL pattern
+
+Use the `/new` route with optional URL-encoded query parameters:
+
+```text
+https://plan.ref.tools/new?content=<urlencoded>&prompt=<urlencoded>
+```
+
+| Parameter | Description |
+| --- | --- |
+| `content` | Seeds the new plan's initial markdown content. |
+| `prompt` | Sends the first chat message immediately after the plan is created. This starts an agent thread, and the plan opens focused on that thread. |
+
+Both parameters are optional. If you omit both, Ref creates a blank untitled plan, the same as clicking **New Plan** in the UI.
+
+## Examples
+
+Create a blank plan:
+
+```text
+https://plan.ref.tools/new
+```
+
+Create a plan with initial markdown content:
+
+```text
+https://plan.ref.tools/new?content=%23%20API%20cleanup%0A%0A-%20%5B%20%5D%20Audit%20legacy%20endpoints%0A-%20%5B%20%5D%20Draft%20migration%20plan
+```
+
+Create a plan with initial content and immediately ask Ref to research it:
+
+```text
+https://plan.ref.tools/new?prompt=Research%20this%20request%20and%20draft%20an%20implementation%20plan&content=%23%20Checkout%20performance%20issue%0A%0AUsers%20report%20slow%20checkout%20after%20the%20latest%20release.%0A%0Ahttps%3A%2F%2Flinear.app%2Facme%2Fissue%2FENG-123%2Fcheckout-performance
+```
+
+## Worked example: Linear
+
+You can wire this pattern into any tool that can construct a URL. For Linear, add a custom link, automation, or internal workflow that builds a Ref URL from the ticket title and ticket link.
+
+For example, start with:
+
+```text
+prompt=Research this ticket and draft a plan
+content=# ENG-123: Checkout performance
+
+https://linear.app/acme/issue/ENG-123/checkout-performance
+```
+
+URL-encode those values and append them to `/new`:
+
+```text
+https://plan.ref.tools/new?prompt=Research+this+ticket+and+draft+a+plan&content=%23%20ENG-123%3A%20Checkout%20performance%0A%0Ahttps%3A%2F%2Flinear.app%2Facme%2Fissue%2FENG-123%2Fcheckout-performance
+```
+
+When the user opens the link, Ref creates a new plan with the ticket title and link already in the document. It also sends the prompt as the first chat message, so the plan opens directly into an agent thread researching the ticket.
+
+If your automation can run code, build the URL with your platform's URL encoder instead of hand-encoding strings:
+
+```js
+const url = new URL('https://plan.ref.tools/new');
+url.searchParams.set('prompt', 'Research this ticket and draft a plan');
+url.searchParams.set(
+  'content',
+  `# ${ticket.identifier}: ${ticket.title}
+
+${ticket.url}`
+);
+```
+
+## Requirements
+
+- The user must be logged in to [plan.ref.tools](https://plan.ref.tools)
+- The new plan is created in the user's currently selected workspace, whether personal or team
+- Both `content` and `prompt` should be URL-encoded before they are added to the link
+
+<GetHelp/>
diff --git a/plans/integrations/linear.mdx b/plans/integrations/linear.mdx
@@ -30,4 +30,8 @@ When you attach a Linear ticket, the agent can:
 - You can attach multiple tickets to a single plan if they're related
 - The agent can update Linear based on progress, keeping your project management in sync
 
+<Tip>
+  Want a Ref plan to open automatically from a Linear ticket? See [Custom Launchers](/plans/integrations/custom-launchers) for the `/new?prompt&content` URL pattern.
+</Tip>
+
 <GetHelp/>
diff --git a/plans/integrations/overview.mdx b/plans/integrations/overview.mdx
@@ -48,6 +48,10 @@ Pull context from your project management and development tools into your plans:
 | [GitHub Issues & PRs](/plans/integrations/github) | Attach GitHub issues and PRs; track PRs linked to plans |
 | [Slack](/plans/integrations/slack) | Create and update plans from Slack threads via @mention |
 
+## Custom Launchers
+
+Use [Custom Launchers](/plans/integrations/custom-launchers) to deep-link into Ref from any tool that can construct a URL. The `/new` URL can seed plan content and optionally start an agent thread immediately.
+
 <CardGroup cols={2}>
   <Card title="Cursor Background Agents" icon="arrow-pointer" href="/plans/integrations/cursor">
     Launch Cursor background agents from your plans.
@@ -73,4 +77,7 @@ Pull context from your project management and development tools into your plans:
   <Card title="Slack" icon="slack" href="/plans/integrations/slack">
     Create and update plans from Slack threads.
   </Card>
+  <Card title="Custom Launchers" icon="link" href="/plans/integrations/custom-launchers">
+    Deep-link into Ref from any tool.
+  </Card>
 </CardGroup>