@patimweb/pi-outline-wiki 1.0.0 → 1.1.1

package/README.md

@@ -29,6 +29,7 @@ outline_setup:
   name: work
   url: https://acme.getoutline.com
   apiKey: ol_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+  description: internal engineering wiki
 ```
 
 `outline_setup` verifies the connection immediately and reports the workspace and the authenticated user, so a typo in the URL or key surfaces right away.
@@ -41,10 +42,10 @@ The `url` is forgiving: a bare host, a trailing slash, a pasted `/api` base or t
 |------|-------------|
 | `outline_setup` | Configure workspace URL and API key. Must be called first. |
 | `outline_status` | Show configured profiles and verify the active key still works. |
-| `outline_profile` | List, switch, or delete workspace profiles (multi-workspace support). |
+| `outline_profile` | List, switch, or delete workspace profiles, with what each wiki holds. |
 | `outline_collections` | List collections with their ids. |
 | `outline_structure` | Show the nested document tree of one collection. |
-| `outline_search` | Full-text search with optional collection, status and date filters. |
+| `outline_search` | Full-text search with optional collection, status and date filters; can search all workspaces at once. |
 | `outline_list` | Browse documents: recent, by collection, by parent, or your drafts. |
 | `outline_read` | Read a document's markdown body, optionally with children or saved to a file. |
 | `outline_create` | Create a document in a collection or under a parent document. |
@@ -70,6 +71,16 @@ outline_search:
 
 Archived documents are excluded unless you ask for them via `statusFilter`.
 
+With several workspaces configured, `allProfiles: true` searches every one of them and labels each hit with the workspace it came from:
+
+```yaml
+outline_search:
+  query: postgres failover
+  allProfiles: true
+```
+
+`allProfiles` cannot be combined with `profile`, `collectionId` or `documentId` -- those are specific to a single workspace, and the tool rejects the combination rather than silently returning nothing.
+
 ### Reading
 
 `outline_read` takes the document id (uuid) or the slug from an Outline URL. Long pages are truncated at 20,000 characters by default so a single wiki page cannot eat the whole context window.
@@ -174,7 +185,34 @@ Credentials are persisted to `~/.pi/outline-config.json`, written atomically wit
 
 ### Multiple workspaces
 
-Every workspace is stored under a profile name. The first profile becomes active automatically; use `outline_profile` to list, switch, or delete profiles. Every read and write tool also accepts a one-off `profile` parameter.
+Several Outline wikis can be configured side by side -- call `outline_setup` once per wiki with a different `name`. The first profile becomes active automatically; later ones do not steal the active slot.
+
+```yaml
+outline_setup:
+  name: firma
+  url: https://acme.getoutline.com
+  apiKey: ol_api_xxx
+  description: internal engineering wiki
+
+outline_setup:
+  name: kunde-a
+  url: https://wiki.kunde-a.de
+  apiKey: ol_api_yyy
+  description: ACME client project docs
+```
+
+**Give every workspace a `description`.** It is shown by `outline_profile` and `outline_status`, and it is what lets the agent decide which wiki to search instead of guessing from a profile name. The bundled skills instruct the agent to check that list before searching, and to ask you rather than guess when a *write* could land in the wrong wiki.
+
+| Need | How |
+|------|-----|
+| See what is configured | `outline_profile` |
+| Switch the default | `outline_profile: { action: use, name: kunde-a }` |
+| One call against another wiki | any tool + `profile: kunde-a` |
+| Search everything at once | `outline_search` + `allProfiles: true` |
+
+Document ids are scoped to their workspace. A hit that a fan-out search reports as `profile kunde-a` must be read with `outline_read` and `profile: kunde-a` -- the same id means nothing in another wiki.
+
+If one workspace is unreachable or its key has expired, a fan-out search still returns the results from the others and reports the failure separately.
 
 ### Self-hosted instances
 

package/index.ts

@@ -91,7 +91,12 @@ export default function (pi: ExtensionAPI) {
       }
 
       pi.sendUserMessage(
-        `Search our Outline wiki for "${query}" using outline_search, read the most relevant document(s) with outline_read, and summarise what the wiki says. Cite each document by title and id, and say so plainly if the wiki has nothing on it.`,
+        [
+          `Search our Outline wiki for "${query}".`,
+          "If outline_profile shows more than one workspace, pick the one whose description fits, or search them all with outline_search allProfiles: true.",
+          "Then read the most relevant document(s) with outline_read, passing the same profile the hit came from, and summarise what the wiki says.",
+          "Cite each document by title and id (and workspace, if several are in play). Say so plainly if the wiki has nothing on it.",
+        ].join(" "),
         { deliverAs: "steer" },
       );
       ctx.ui.notify(`Searching the wiki for "${query}"...`, "info");
@@ -112,11 +117,12 @@ export default function (pi: ExtensionAPI) {
         [
           "Capture the durable knowledge from this session in our Outline wiki.",
           hint ? `Focus on: ${hint}.` : "",
-          "First use outline_search to check whether a page on this already exists.",
+          "If outline_profile shows more than one workspace, decide which one this belongs in first and pass profile explicitly on every call; ask me if it is not obvious.",
+          "Then use outline_search to check whether a page on this already exists.",
           "If it does, extend it with outline_update (mode append) instead of creating a duplicate.",
           "If it does not, use outline_collections to pick the right collection and create the page with outline_create.",
           "Write what a colleague would need in six months: the decision, why, and what was ruled out -- not a transcript.",
-          "Show me the page title and URL when you are done.",
+          "Show me the workspace, page title and URL when you are done.",
         ]
           .filter(Boolean)
           .join(" "),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patimweb/pi-outline-wiki",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Outline wiki extension for the pi coding agent. Search, read, write, organise and comment on Outline documents from your pi session.",
   "keywords": [
     "pi-package",
@@ -29,15 +29,17 @@
     "test:watch": "node --experimental-test-module-mocks --test --watch 'tests/**/*.test.ts'",
     "test:coverage": "node --experimental-test-module-mocks --experimental-test-coverage --test 'tests/**/*.test.ts'"
   },
-  "dependencies": {
-    "typebox": "^1.2.8"
+  "peerDependencies": {
+    "typebox": "*"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
     "@semantic-release/git": "^10.0.0",
-    "semantic-release": "^25.0.0"
+    "semantic-release": "^25.0.0",
+    "typebox": "^1.3.25",
+    "yaml": "^2.9.0"
   },
   "pi": {
     "extensions": [

package/skills/outline-doc-writing/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: outline-doc-writing
-description: Write and edit documents in the Outline wiki so they are findable, correct and safe to change. Use whenever creating a new wiki page, updating an existing one, restructuring a collection, or when the user asks to "document this in the wiki", "write it up in Outline", "update the runbook" or "add a page". Covers where a page belongs, how to structure it, how to update without destroying other people's work, and when to comment instead of edit.
-allowed-tools: outline_collections, outline_structure, outline_search, outline_list, outline_read, outline_create, outline_update, outline_move, outline_archive, outline_comment
+description: Write and edit documents in the Outline wiki so they are findable, correct and safe to change. Use whenever creating a new wiki page, updating an existing one, restructuring a collection, or when the user asks to "document this in the wiki", "write it up in Outline", "update the runbook" or "add a page". Covers which workspace and collection a page belongs in, how to structure it, how to update without destroying other people's work, and when to comment instead of edit.
+allowed-tools: outline_profile, outline_collections, outline_structure, outline_search, outline_list, outline_read, outline_create, outline_update, outline_move, outline_archive, outline_comment
 ---
 
 # Writing in the Outline wiki
@@ -9,10 +9,28 @@ allowed-tools: outline_collections, outline_structure, outline_search, outline_l
 A wiki page you write is read by people who were not in this session. Write
 for them.
 
+## Which workspace
+
+Writing into the wrong wiki is worse than reading the wrong one: it is
+visible to the wrong people and it is not obvious to anyone that it happened.
+So when more than one workspace is configured, settle this **before** the
+first write.
+
+1. `outline_profile` lists every workspace with what it holds, and marks the
+   active one.
+2. Pass `profile: <name>` explicitly on every write call. Do not rely on
+   whichever workspace happens to be active - that is a setting from an
+   earlier session.
+3. If it is not obvious which workspace the content belongs to, **ask the
+   user**. Client material in an internal wiki, or one client's material in
+   another client's wiki, is a confidentiality problem, not a filing mistake.
+4. Say which workspace you wrote to when you report back.
+
 ## Before you create anything
 
-1. `outline_search` for the topic. **Extending an existing page is almost
-   always better than adding a second one.** Duplicates are how wikis die.
+1. `outline_search` for the topic - in the workspace you settled on. **Extending
+   an existing page is almost always better than adding a second one.**
+   Duplicates are how wikis die.
 2. If nothing exists, `outline_collections` then `outline_structure` on the
    likely collection, so the new page lands where people will look for it.
 3. If the right home is ambiguous, ask the user which collection rather than
@@ -74,5 +92,6 @@ the content is fine but the location is wrong.
 
 ## Finish the job
 
-After writing, tell the user the page title, its id and its URL, and say in
-one line what you put there. If you created a draft, say that too.
+After writing, tell the user the workspace, the page title, its id and its
+URL, and say in one line what you put there. If you created a draft, say that
+too.

package/skills/outline-knowledge-capture/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: outline-knowledge-capture
 description: Turn what was worked out in a coding session into a durable Outline wiki page - architecture decisions, debugging findings, incident write-ups, setup and runbook steps, or gotchas that cost real time. Use when the user says "write this up", "document this decision", "capture this in the wiki", "add this to our docs", "so we don't hit this again", or after any session that produced knowledge which is not obvious from the code alone.
-allowed-tools: outline_collections, outline_structure, outline_search, outline_read, outline_create, outline_update, outline_comment
+allowed-tools: outline_profile, outline_collections, outline_structure, outline_search, outline_read, outline_create, outline_update, outline_comment
 ---
 
 # Capturing session knowledge in Outline
@@ -26,14 +26,20 @@ what you tried, or anything you would have to invent details for.
 
 ## Procedure
 
-1. **Check for an existing home.** `outline_search` with the system or
+1. **Pick the workspace.** If `outline_profile` shows more than one, decide
+   which wiki this belongs in before writing anything, and pass `profile`
+   explicitly on every call. Work done for a client belongs in that client's
+   workspace - never in the internal wiki or another client's, even when the
+   technical finding is general. If the session touched more than one context
+   and you cannot tell, ask.
+2. **Check for an existing home.** `outline_search` with the system or
    component name. A decision about the payments service belongs on or under
    the payments page, not in a new orphan document.
-2. **Extend before you create.** If a relevant page exists, `outline_read` it
+3. **Extend before you create.** If a relevant page exists, `outline_read` it
    and add a dated section with `outline_update` `mode: append`.
-3. **Otherwise create.** `outline_collections` -> `outline_structure` ->
+4. **Otherwise create.** `outline_collections` -> `outline_structure` ->
    `outline_create` under the right parent.
-4. **Report back** with the title, id and URL.
+5. **Report back** with the workspace, title, id and URL.
 
 ## What to write
 
@@ -48,7 +54,9 @@ Answer the four questions a future colleague will actually have:
   true.
 
 Include the concrete artefacts: the exact error message, the command that
-reproduces it, the file paths, the ticket or PR link. A page that says "we
+reproduces it, the file paths, the ticket or PR link. Leave out credentials,
+tokens and customer data - a wiki page is readable by everyone in that
+workspace. A page that says "we
 fixed a timeout issue" helps nobody.
 
 ## Templates

package/skills/outline-wiki/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: outline-wiki
-description: Research the team's Outline wiki before answering questions about internal systems, conventions, decisions, runbooks or onboarding. Use whenever a question is about "how we do it here" rather than about general knowledge or the code in front of you - for example architecture decisions, deployment steps, naming conventions, ownership, incident history, or anything the user refers to as "the wiki", "our docs", "Confluence-style notes" or Outline. Also use it to check whether the wiki already covers something before writing a new page.
-allowed-tools: outline_status, outline_collections, outline_structure, outline_search, outline_list, outline_read, outline_comments, outline_export
+description: Research the team's Outline wiki - or wikis - before answering questions about internal systems, conventions, decisions, runbooks or onboarding. Use whenever a question is about "how we do it here" rather than about general knowledge or the code in front of you - for example architecture decisions, deployment steps, naming conventions, ownership, incident history, or anything the user refers to as "the wiki", "our docs", "Confluence-style notes" or Outline. Also use it to check whether the wiki already covers something before writing a new page.
+allowed-tools: outline_status, outline_profile, outline_collections, outline_structure, outline_search, outline_list, outline_read, outline_comments, outline_export
 ---
 
 # Researching the Outline wiki
@@ -22,18 +22,43 @@ Use the wiki when the answer depends on this organisation:
 Do **not** use it for general programming questions, or for facts that the
 repository in front of you answers directly.
 
+## Which wiki
+
+More than one Outline workspace can be configured, and they are separate
+worlds: a document id from one is meaningless in another.
+
+**Start with `outline_profile`** when you have not already seen the list this
+session. It shows every configured workspace with a one-line description of
+what it holds, and marks the active one. Then decide:
+
+- The question clearly belongs to one workspace (the description names the
+  client, product or team): search that one with `profile: <name>`.
+- You do not know which workspace holds the answer: `outline_search` with
+  `allProfiles: true` searches all of them at once and labels each hit with
+  the workspace it came from.
+- Only one workspace is configured: ignore all of this and just search.
+
+After a fan-out, **carry the profile through**. A hit reported as
+`profile kunde-a` must be read with `outline_read` and `profile: "kunde-a"`,
+or you will get "document not found" from the wrong wiki.
+
+If a workspace has no description, say so once and suggest the user re-run
+`outline_setup` with one - without it you are guessing from the name.
+
 ## The loop
 
-1. **Search, do not browse.** `outline_search` with two or three distinctive
+1. **Pick the wiki** (above), if more than one is configured.
+2. **Search, do not browse.** `outline_search` with two or three distinctive
    nouns. "postgres failover" beats "how does our database failover work".
-2. **Read the top hits.** The search snippet is not the answer.
-   `outline_read` on the one or two most promising ids.
-3. **Follow the structure.** If a page looks like an index, use
+3. **Read the top hits.** The search snippet is not the answer.
+   `outline_read` on the one or two most promising ids - with the same
+   `profile` the hit came from.
+4. **Follow the structure.** If a page looks like an index, use
    `outline_read` with `includeChildren: true`, or `outline_structure` on its
    collection, to see what sits under it.
-4. **Answer with citations.** Name the document title and id you used, so the
-   user can open it. If several pages disagree, say so and give the update
-   dates - wikis rot.
+5. **Answer with citations.** Name the document title, id and - when several
+   workspaces are in play - the workspace you took it from. If several pages
+   disagree, say so and give the update dates: wikis rot.
 
 ## Search that actually finds things
 
@@ -43,14 +68,17 @@ repository in front of you answers directly.
   form before concluding the wiki is silent. Teams write "k8s" and
   "Kubernetes" in different pages.
 - Recent-work questions ("what changed lately?") are `outline_list`, not
-  `outline_search`.
+  `outline_search`. `outline_list` works on one workspace at a time.
+- `allProfiles` cannot be combined with `collectionId` or `documentId`: those
+  ids only exist in one workspace. Narrow the workspace first, then filter.
 - Something that existed but is gone is usually archived, not deleted:
   re-run the search with `statusFilter: ["published", "archived"]`.
 
 ## Ids
 
-Every tool takes a document id. Ids come from search, list or structure
-output - never invent one. An Outline URL like
+Every tool takes a document id, and ids are scoped to one workspace. They
+come from search, list or structure output - never invent one, and never
+carry one from one workspace to another. An Outline URL like
 `https://acme.getoutline.com/doc/runbook-deploy-aBc123XyZ` also works: pass
 the trailing `runbook-deploy-aBc123XyZ` slug as `id`.
 

package/src/formatting/formatters.ts

@@ -59,19 +59,99 @@ export function formatProfileStatus(
     return "No Outline workspace configured. Use outline_setup with your workspace URL and an API key from Settings -> API & Apps.";
   }
 
-  const lines = names.map((name) => {
+  const lines: string[] = [];
+  for (const name of names) {
     const config = profiles[name];
     const marker = name === active ? "*" : " ";
     const insecure = config.insecureTls ? " (TLS validation off)" : "";
-    return `${marker} ${name}: ${config.url} key ${maskApiKey(config.apiKey)}${insecure}`;
-  });
+    lines.push(
+      `${marker} ${name}: ${config.url} key ${maskApiKey(config.apiKey)}${insecure}`,
+    );
+    // The description is what tells the agent which wiki holds what, so it
+    // gets its own line rather than being truncated onto the end of the URL.
+    if (config.description) lines.push(`    ${config.description}`);
+  }
+
+  const footer =
+    names.length > 1
+      ? [
+          "",
+          "Target one workspace with the profile parameter, or set allProfiles: true on outline_search to search all of them at once.",
+        ]
+      : [];
 
   return [
-    `Outline profiles (${names.length}), * marks the active one:`,
+    `Outline workspaces (${names.length}), * marks the active one:`,
     ...lines,
+    ...footer,
   ].join("\n");
 }
 
+/** Search results gathered from several workspaces in one call. */
+export interface ProfileSearchResult {
+  readonly profile: string;
+  readonly description?: string;
+  readonly hits: ReadonlyArray<SearchHit>;
+  readonly error?: string;
+}
+
+export function formatMultiSearchResults(
+  results: ReadonlyArray<ProfileSearchResult>,
+  query: string,
+): string {
+  const withHits = results.filter((result) => result.hits.length > 0);
+  const failed = results.filter((result) => result.error);
+  const total = withHits.reduce((sum, result) => sum + result.hits.length, 0);
+
+  const sections: string[] = [];
+
+  if (total === 0) {
+    sections.push(
+      `No documents match "${query}" in any of the ${results.length} configured workspace(s).`,
+    );
+  } else {
+    sections.push(
+      `Search "${query}" across ${results.length} workspace(s) -- ${total} result(s).`,
+      "Ids are only valid within their own workspace: pass that workspace as the profile parameter to outline_read.",
+    );
+  }
+
+  for (const result of withHits) {
+    const label = result.description
+      ? `${result.profile} (${result.description})`
+      : result.profile;
+    const lines = result.hits.map((hit, index) => {
+      const context = hit.context.replace(/\s+/g, " ").trim();
+      return [
+        `  ${index + 1}. ${hit.document.title}${statusMarkers(hit.document)}`,
+        `     id ${hit.document.id} | profile ${result.profile} | updated ${shortDate(hit.document.updatedAt)}`,
+        context ? `     ${context.slice(0, 300)}` : "",
+      ]
+        .filter(Boolean)
+        .join("\n");
+    });
+    sections.push(`\n[${label}] ${result.hits.length} result(s):\n${lines.join("\n")}`);
+  }
+
+  const empty = results.filter(
+    (result) => !result.error && result.hits.length === 0,
+  );
+  if (empty.length > 0 && total > 0) {
+    sections.push(
+      `\nNo matches in: ${empty.map((result) => result.profile).join(", ")}.`,
+    );
+  }
+
+  if (failed.length > 0) {
+    sections.push(
+      `\n${failed.length} workspace(s) could not be searched:`,
+      ...failed.map((result) => `- ${result.profile}: ${result.error}`),
+    );
+  }
+
+  return sections.join("\n");
+}
+
 export function formatWorkspaceInfo(info: WorkspaceInfo): string {
   const lines = [
     `Workspace: ${info.teamName ?? "(unknown)"}`,

package/src/tools/outline-search.ts

@@ -3,9 +3,13 @@
  */
 
 import { Type } from "typebox";
-import { resolveConfig } from "../config.ts";
+import { getProfiles, resolveConfig } from "../config.ts";
 import { searchDocuments } from "../clients/outline-client.ts";
-import { formatSearchResults } from "../formatting/formatters.ts";
+import {
+  formatMultiSearchResults,
+  formatSearchResults,
+  type ProfileSearchResult,
+} from "../formatting/formatters.ts";
 
 const VALID_STATUS = new Set(["draft", "archived", "published"]);
 const VALID_DATE = new Set(["day", "week", "month", "year"]);
@@ -14,7 +18,7 @@ export const OutlineSearchTool = {
   name: "outline_search",
   label: "Outline Search",
   description:
-    "Full-text search across the Outline wiki. Returns matching documents with a snippet and their ids; read the full text with outline_read. Prefer two or three distinctive keywords over long sentences.",
+    "Full-text search across the Outline wiki. Returns matching documents with a snippet and their ids; read the full text with outline_read. Prefer two or three distinctive keywords over long sentences. With several workspaces configured, target one with 'profile' or set allProfiles to search all of them at once.",
   parameters: Type.Object({
     query: Type.String({
       description: "Search keywords. Distinctive nouns work better than full questions.",
@@ -45,6 +49,13 @@ export const OutlineSearchTool = {
     profile: Type.Optional(
       Type.String({ description: "Outline profile to use. Defaults to the active one." }),
     ),
+    allProfiles: Type.Optional(
+      Type.Boolean({
+        description:
+          "Search every configured workspace instead of just one, and report which workspace each hit came from. Use it when you do not know which wiki holds the answer. Default false.",
+        default: false,
+      }),
+    ),
   }),
 
   async execute(
@@ -58,6 +69,7 @@ export const OutlineSearchTool = {
       statusFilter?: string[];
       dateFilter?: string;
       profile?: string;
+      allProfiles?: boolean;
     },
     signal: AbortSignal,
   ) {
@@ -78,30 +90,88 @@ export const OutlineSearchTool = {
       );
     }
 
+    const query = params.query.trim();
+    const criteria = {
+      query,
+      limit: params.limit,
+      offset: params.offset,
+      collectionId: params.collectionId,
+      documentId: params.documentId,
+      statusFilter: params.statusFilter,
+      dateFilter: params.dateFilter,
+    };
+
+    if (params.allProfiles) {
+      if (params.profile) {
+        throw new Error(
+          "profile and allProfiles contradict each other: pick one workspace, or search all of them.",
+        );
+      }
+      // Collection and document filters are ids that only exist in one
+      // workspace, so a fan-out with them set would silently return nothing
+      // for every other wiki.
+      if (params.collectionId || params.documentId) {
+        throw new Error(
+          "collectionId and documentId are specific to one workspace and cannot be combined with allProfiles. Search that workspace with the profile parameter instead.",
+        );
+      }
+
+      const profiles = getProfiles();
+      const names = Object.keys(profiles);
+      if (names.length === 0) {
+        throw new Error(
+          "No Outline workspace configured. Use outline_setup first.",
+        );
+      }
+
+      // One slow or broken workspace must not sink the whole search, so each
+      // failure is reported alongside the results from the others.
+      const results: ProfileSearchResult[] = await Promise.all(
+        names.map(async (name) => {
+          try {
+            const { hits } = await searchDocuments(profiles[name], criteria, signal);
+            return { profile: name, description: profiles[name].description, hits };
+          } catch (err) {
+            return {
+              profile: name,
+              description: profiles[name].description,
+              hits: [],
+              error: (err as Error).message,
+            };
+          }
+        }),
+      );
+
+      return {
+        content: [
+          { type: "text" as const, text: formatMultiSearchResults(results, query) },
+        ],
+        details: {
+          query,
+          searchedProfiles: names,
+          count: results.reduce((sum, result) => sum + result.hits.length, 0),
+          failedProfiles: results.filter((r) => r.error).map((r) => r.profile),
+          documents: results.flatMap((result) =>
+            result.hits.map((hit) => ({
+              id: hit.document.id,
+              title: hit.document.title,
+              profile: result.profile,
+            })),
+          ),
+        },
+      };
+    }
+
     const config = resolveConfig(params.profile);
-    const { hits, pagination } = await searchDocuments(
-      config,
-      {
-        query: params.query.trim(),
-        limit: params.limit,
-        offset: params.offset,
-        collectionId: params.collectionId,
-        documentId: params.documentId,
-        statusFilter: params.statusFilter,
-        dateFilter: params.dateFilter,
-      },
-      signal,
-    );
+    const { hits, pagination } = await searchDocuments(config, criteria, signal);
 
     return {
       content: [
-        {
-          type: "text" as const,
-          text: formatSearchResults(hits, params.query.trim(), pagination),
-        },
+        { type: "text" as const, text: formatSearchResults(hits, query, pagination) },
       ],
       details: {
-        query: params.query.trim(),
+        query,
+        profile: params.profile ?? null,
         count: hits.length,
         documents: hits.map((hit) => ({
           id: hit.document.id,

package/src/tools/outline-setup.ts

@@ -29,6 +29,12 @@ export const OutlineSetupTool = {
     apiKey: Type.String({
       description: "Outline API key from Settings -> API & Apps (starts with ol_api_).",
     }),
+    description: Type.Optional(
+      Type.String({
+        description:
+          "One line on what this wiki contains, e.g. 'internal engineering wiki' or 'ACME client project docs'. Strongly recommended when several workspaces are configured: it is how the agent decides which wiki to search.",
+      }),
+    ),
     insecureTls: Type.Optional(
       Type.Boolean({
         description:
@@ -41,6 +47,7 @@ export const OutlineSetupTool = {
     const config: OutlineConfig = {
       url: normalizeBaseUrl(params.url),
       apiKey: params.apiKey.trim(),
+      ...(params.description && { description: params.description.trim() }),
       ...(params.insecureTls !== undefined && { insecureTls: params.insecureTls }),
     };
 

package/src/types.ts

@@ -15,6 +15,12 @@ export interface OutlineConfig {
   readonly url: string;
   /** Personal API key, starts with `ol_api_`. */
   readonly apiKey: string;
+  /**
+   * What this wiki is for, in one line ("internal engineering wiki",
+   * "client ACME project docs"). With several workspaces configured this is
+   * what lets the agent pick the right one instead of guessing from a name.
+   */
+  readonly description?: string;
   /**
    * Skip TLS certificate validation. Only for self-hosted instances behind a
    * self-signed certificate. Disables validation process-wide, so it is off
@@ -126,6 +132,7 @@ export interface SetupParams {
   readonly name: string;
   readonly url: string;
   readonly apiKey: string;
+  readonly description?: string;
   readonly insecureTls?: boolean;
 }