@patimweb/pi-outline-wiki 1.0.0

package/.node-version

@@ -0,0 +1 @@
+26.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Weppelmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# pi-outline-wiki
+
+![pi.dev connected to Outline](screenshot.png)
+
+Outline wiki extension for the [pi coding agent](https://github.com/earendil-works/pi).
+
+Search, read, write, organise and comment on documents in your [Outline](https://www.getoutline.com/) knowledge base directly from your pi session. Credentials are stored locally in `~/.pi/outline-config.json`.
+
+Works with Outline cloud (`yourteam.getoutline.com`) and with self-hosted installations.
+
+## Installation
+
+```bash
+# Install from npm
+pi install npm:@patimweb/pi-outline-wiki
+
+# Install from local path during development
+pi install /path/to/pi-outline-wiki
+```
+
+## Quick Start
+
+1. In Outline, go to **Settings -> API & Apps** and create an API key (it starts with `ol_api_`).
+2. Configure the workspace with the `outline_setup` tool.
+3. Ask pi anything about your wiki, or use `/wiki <topic>`.
+
+```
+outline_setup:
+  name: work
+  url: https://acme.getoutline.com
+  apiKey: ol_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+`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.
+
+The `url` is forgiving: a bare host, a trailing slash, a pasted `/api` base or the `/mcp` endpoint from Outline's MCP docs are all normalised to the workspace root.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `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_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_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. |
+| `outline_update` | Replace, append to, or prepend to a document; rename it; publish a draft. |
+| `outline_move` | Move a document into another collection or under another parent. |
+| `outline_archive` | Archive, restore, or unpublish a document. |
+| `outline_delete` | Move a document to the trash, or delete it permanently. |
+| `outline_comments` | Read comment threads on a document, nested by reply. |
+| `outline_comment` | Post a comment or reply on a document. |
+| `outline_export` | Export a document or a whole collection to local markdown files. |
+
+### Searching
+
+`outline_search` runs Outline's full-text search and returns matching documents with a snippet and their ids. Read the full body with `outline_read`.
+
+```yaml
+outline_search:
+  query: postgres failover
+  # collectionId: <id>              # restrict to one collection
+  # statusFilter: [published, archived]
+  # dateFilter: month               # only recently updated documents
+```
+
+Archived documents are excluded unless you ask for them via `statusFilter`.
+
+### 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.
+
+```yaml
+outline_read:
+  id: deploy-runbook-aBc123XyZ
+  # maxChars: 0                     # 0 = no truncation
+  # includeChildren: true           # also list child documents
+  # saveDir: ./docs                 # additionally write the full page to a .md file
+```
+
+### Writing
+
+`outline_create` publishes into a collection by default. Pass `parentDocumentId` to nest a page, or `publish: false` to keep it as a personal draft.
+
+```yaml
+outline_create:
+  title: Payment service failover
+  collectionId: <id>
+  text: |
+    Summary of what this page is for.
+
+    ## Steps
+    1. ...
+```
+
+Do not repeat the title as a top-level heading in `text` -- Outline renders the title separately.
+
+### Updating without losing content
+
+`outline_update` defaults to `mode: replace`, which overwrites the whole body. Use `append` or `prepend` to add to a page without reading and re-sending it.
+
+```yaml
+# Add a dated entry to a decision log
+outline_update:
+  id: <id>
+  mode: append
+  text: |
+    ## Switched to connection pooling - 2026-09-02
+    ...
+```
+
+`mode: prepend` is the right choice for newest-first logs and for adding a notice at the top of a page.
+
+### Retiring pages
+
+`outline_archive` keeps a page searchable and restorable; it is the reversible option and should be preferred over deleting.
+
+```yaml
+outline_archive:
+  id: <id>
+  # action: archive | restore | unpublish
+```
+
+`outline_delete` moves a page to the trash (restore it with `outline_archive` action `restore`). `permanent: true` erases it and cannot be undone.
+
+### Exporting into your repository
+
+`outline_export` writes markdown files directly to disk, which is far cheaper than reading page after page through the model.
+
+```yaml
+outline_export:
+  targetDir: ./docs/wiki
+  collectionId: <id>        # or documentId: <id>
+  # includeChildren: true   # with documentId
+  # limit: 50
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/wiki <topic>` | Search the wiki and summarise what it says, with citations. |
+| `/wiki-capture [focus]` | Write the durable knowledge from this session into the wiki. |
+
+## Skills
+
+The package ships three skills that teach the agent how to use the wiki well, not just which tools exist:
+
+| Skill | Purpose |
+|-------|---------|
+| `outline-wiki` | Research the wiki before answering questions about internal systems, conventions and decisions. |
+| `outline-doc-writing` | Where a page belongs, how to structure it, and how to update it without destroying other people's work. |
+| `outline-knowledge-capture` | Turn what was worked out in a session into a durable page: decision records, incident findings, gotchas. |
+
+## Configuration
+
+Credentials are persisted to `~/.pi/outline-config.json`, written atomically with mode `0600`. The `outline_setup` tool creates the file. You can also write it by hand:
+
+```json
+{
+  "profiles": {
+    "work": {
+      "url": "https://acme.getoutline.com",
+      "apiKey": "ol_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+    }
+  },
+  "activeProfile": "work"
+}
+```
+
+### 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.
+
+### Self-hosted instances
+
+Point `url` at your installation, e.g. `https://wiki.example.com` or `http://localhost:3000`. If your instance uses a self-signed certificate, set `insecureTls: true` in `outline_setup`. This disables certificate validation for the whole pi process, so only use it when you have no alternative -- `outline_status` warns while it is active.
+
+### Permissions
+
+The extension acts as the user who owns the API key. It can only see and change what that user can see and change in Outline, so scoping access is a matter of which account the key belongs to.
+
+## Development
+
+```bash
+npm install
+npm test
+npm run test:coverage
+```
+
+The code follows a data-oriented layout: plain immutable data in `src/types.ts`, all HTTP isolated in `src/clients/outline-client.ts`, pure display functions in `src/formatting/formatters.ts`, and one module per tool in `src/tools/`.
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,128 @@
+/**
+ * pi Outline Wiki Extension
+ *
+ * Gives pi read and write access to an Outline wiki
+ * (https://www.getoutline.com) through Outline's REST API.
+ *
+ * Tools:
+ *   - outline_setup: Configure workspace URL and API key
+ *   - outline_status: Show configuration and verify the connection
+ *   - outline_profile: List, switch or delete workspace profiles
+ *   - outline_collections: List collections with their ids
+ *   - outline_structure: Show the nested document tree of a collection
+ *   - outline_search: Full-text search across the wiki
+ *   - outline_list: Browse documents, children or drafts
+ *   - outline_read: Read a document's markdown body
+ *   - outline_create: Create a new document
+ *   - outline_update: Replace, append to or prepend to a document
+ *   - outline_move: Re-file a document into another collection or parent
+ *   - outline_archive: Archive, restore or unpublish a document
+ *   - outline_delete: Trash or permanently delete a document
+ *   - outline_comments: Read comment threads on a document
+ *   - outline_comment: Post a comment or reply
+ *   - outline_export: Save documents to local markdown files
+ *
+ * Data-oriented design:
+ *   - All domain data is represented as plain immutable interfaces (types.ts)
+ *   - I/O is isolated in the client module (clients/)
+ *   - Pure formatting functions convert data to display strings (formatting/)
+ *   - Each tool is a single-responsibility module (tools/)
+ *   - Configuration is managed as mutable state with file persistence (config.ts)
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { loadConfig, getConfig } from "./src/config.ts";
+import { OutlineSetupTool } from "./src/tools/outline-setup.ts";
+import { OutlineStatusTool } from "./src/tools/outline-status.ts";
+import { OutlineProfileTool } from "./src/tools/outline-profile.ts";
+import { OutlineCollectionsTool } from "./src/tools/outline-collections.ts";
+import { OutlineStructureTool } from "./src/tools/outline-structure.ts";
+import { OutlineSearchTool } from "./src/tools/outline-search.ts";
+import { OutlineListTool } from "./src/tools/outline-list.ts";
+import { OutlineReadTool } from "./src/tools/outline-read.ts";
+import { OutlineCreateTool } from "./src/tools/outline-create.ts";
+import { OutlineUpdateTool } from "./src/tools/outline-update.ts";
+import { OutlineMoveTool } from "./src/tools/outline-move.ts";
+import { OutlineArchiveTool } from "./src/tools/outline-archive.ts";
+import { OutlineDeleteTool } from "./src/tools/outline-delete.ts";
+import { OutlineCommentsTool } from "./src/tools/outline-comments.ts";
+import { OutlineCommentTool } from "./src/tools/outline-comment.ts";
+import { OutlineExportTool } from "./src/tools/outline-export.ts";
+
+const NOT_CONFIGURED =
+  "Outline not configured. Use the outline_setup tool with your workspace URL and an API key.";
+
+export default function (pi: ExtensionAPI) {
+  // Load saved config on startup
+  loadConfig();
+
+  // Register all tools
+  pi.registerTool(OutlineSetupTool);
+  pi.registerTool(OutlineStatusTool);
+  pi.registerTool(OutlineProfileTool);
+  pi.registerTool(OutlineCollectionsTool);
+  pi.registerTool(OutlineStructureTool);
+  pi.registerTool(OutlineSearchTool);
+  pi.registerTool(OutlineListTool);
+  pi.registerTool(OutlineReadTool);
+  pi.registerTool(OutlineCreateTool);
+  pi.registerTool(OutlineUpdateTool);
+  pi.registerTool(OutlineMoveTool);
+  pi.registerTool(OutlineArchiveTool);
+  pi.registerTool(OutlineDeleteTool);
+  pi.registerTool(OutlineCommentsTool);
+  pi.registerTool(OutlineCommentTool);
+  pi.registerTool(OutlineExportTool);
+
+  // Look something up in the wiki without spelling out the tool call
+  pi.registerCommand("wiki", {
+    description: "Search the Outline wiki and summarise what it says",
+    handler: async (args, ctx) => {
+      if (!getConfig()) {
+        ctx.ui.notify(NOT_CONFIGURED, "error");
+        return;
+      }
+
+      const query = args.trim();
+      if (!query) {
+        ctx.ui.notify("Usage: /wiki <what you are looking for>", "info");
+        return;
+      }
+
+      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.`,
+        { deliverAs: "steer" },
+      );
+      ctx.ui.notify(`Searching the wiki for "${query}"...`, "info");
+    },
+  });
+
+  // Write the session's outcome back into the wiki
+  pi.registerCommand("wiki-capture", {
+    description: "Write what we worked out in this session into the Outline wiki",
+    handler: async (args, ctx) => {
+      if (!getConfig()) {
+        ctx.ui.notify(NOT_CONFIGURED, "error");
+        return;
+      }
+
+      const hint = args.trim();
+      pi.sendUserMessage(
+        [
+          "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 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.",
+        ]
+          .filter(Boolean)
+          .join(" "),
+        { deliverAs: "steer" },
+      );
+      ctx.ui.notify("Asking the agent to write this up in the wiki...", "info");
+    },
+  });
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@patimweb/pi-outline-wiki",
+  "version": "1.0.0",
+  "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",
+    "pi-extension",
+    "outline",
+    "wiki",
+    "knowledge-base",
+    "documentation"
+  ],
+  "author": "Patrick Weppelmann",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=26.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Smotherer007/pi-outline-wiki.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Smotherer007/pi-outline-wiki/issues"
+  },
+  "scripts": {
+    "build": "echo 'No build step defined'",
+    "test": "node --experimental-test-module-mocks --experimental-test-coverage --test 'tests/**/*.test.ts'",
+    "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"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@semantic-release/git": "^10.0.0",
+    "semantic-release": "^25.0.0"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "image": "https://raw.githubusercontent.com/Smotherer007/pi-outline-wiki/main/screenshot.png"
+  }
+}

package/release.config.cjs

@@ -0,0 +1,16 @@
+module.exports = {
+    branches: ["main", { name: "next", prerelease: true }],
+    plugins: [
+        "@semantic-release/commit-analyzer",
+        "@semantic-release/release-notes-generator",
+        "@semantic-release/npm",
+        [
+            "@semantic-release/git",
+            {
+                assets: ["package.json", "package-lock.json"],
+                message: "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+            }
+        ],
+        "@semantic-release/github"
+    ]
+};

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

@@ -0,0 +1,78 @@
+---
+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
+---
+
+# Writing in the Outline wiki
+
+A wiki page you write is read by people who were not in this session. Write
+for them.
+
+## 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.
+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
+   picking one at random.
+
+## Where a page goes
+
+- A new topic in an existing area: `outline_create` with
+  `parentDocumentId` set to the area's index page.
+- A genuinely new area: `outline_create` with `collectionId` only.
+- Unsure, or the content is still rough: `publish: false` creates a private
+  draft. Tell the user it is a draft and how to publish it.
+
+## Structure that survives
+
+Outline renders the title separately, so **do not repeat the title as an H1**
+in the body. Start with a one- or two-sentence summary of what the page is
+for, then headings.
+
+Shapes that work:
+
+- **Reference / convention page:** summary, the rule, examples of right and
+  wrong, exceptions, who to ask.
+- **Runbook:** when to use it, prerequisites, numbered steps with the exact
+  commands, how to verify it worked, how to roll back, escalation contact.
+- **Decision record:** context, the decision, alternatives considered and why
+  they lost, consequences, date and participants.
+- **Overview / index:** what lives in this area, one line per child page,
+  links to them.
+
+Write plainly. Prefer short paragraphs and real commands in fenced code
+blocks over prose describing commands. Date anything time-sensitive
+explicitly ("as of 2026-09") so a future reader can judge its age.
+
+## Updating without collateral damage
+
+`outline_update` with the default `mode: replace` **overwrites the entire
+body**. Only replace after `outline_read`, and only when you are genuinely
+rewriting the page.
+
+- Adding a new section, entry or note: `mode: append`.
+- Adding a notice or a newest-first log entry: `mode: prepend`.
+- Fixing a typo in a long page: read it, then replace with the corrected
+  full text.
+
+Never silently rewrite someone else's page to say something different. If you
+disagree with existing content, or if a change is a judgement call the team
+should make, `outline_comment` on the page instead of editing it.
+
+## Retiring pages
+
+`outline_archive` is the right tool for a page that is obsolete - it stays
+searchable and can be restored. `outline_delete` is for pages that should
+never have existed, and permanent deletion only when the user explicitly asks
+for it.
+
+`outline_move` re-files a page and takes its children with it; use it when
+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.

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

@@ -0,0 +1,92 @@
+---
+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
+---
+
+# Capturing session knowledge in Outline
+
+Sessions produce two kinds of output: the change to the code, and the
+understanding that made the change possible. The second one is lost unless
+someone writes it down. That is what this is for.
+
+## What is worth capturing
+
+Write it up when the finding is **durable and non-obvious**:
+
+- a decision with alternatives that were rejected for reasons
+- a root cause that took real effort to find
+- an environment or setup step that is not in any README
+- a constraint that is invisible in the code ("the vendor API rate-limits
+  per organisation, not per key")
+- a workaround and the condition under which it can be removed
+
+Do not write up: routine changes the diff already explains, transcripts of
+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
+   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
+   and add a dated section with `outline_update` `mode: append`.
+3. **Otherwise create.** `outline_collections` -> `outline_structure` ->
+   `outline_create` under the right parent.
+4. **Report back** with the title, id and URL.
+
+## What to write
+
+Answer the four questions a future colleague will actually have:
+
+- **What was the situation?** One paragraph of context, with dates and
+  version or commit references where they matter.
+- **What did we decide or find?** The conclusion, stated plainly and up front.
+- **Why?** The reasoning, and what was ruled out. This is the part that
+  cannot be reconstructed from the repository later.
+- **What now?** Consequences, follow-ups, and how to tell if this stops being
+  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
+fixed a timeout issue" helps nobody.
+
+## Templates
+
+**Decision (append to the component's page, or a new child page)**
+
+```
+## <Decision> - <YYYY-MM-DD>
+
+**Context.** <what forced the choice>
+**Decision.** <what we chose>
+**Alternatives.** <option: why it lost>
+**Consequences.** <what this makes easy, what it makes hard, what to revisit>
+```
+
+**Debugging / incident finding**
+
+```
+## <Symptom> - <YYYY-MM-DD>
+
+**Symptom.** <what was observed, with the exact error>
+**Root cause.** <the actual mechanism>
+**Fix.** <what was changed, with paths or PR link>
+**How to spot it again.** <the signal that identifies this failure mode>
+```
+
+**Gotcha**
+
+```
+## <Short name>
+
+<One paragraph: what surprises people, and what to do instead.>
+```
+
+## Tone and honesty
+
+Write in the team's voice, not as a report about an AI session - drop
+"I asked", "the agent", "in this conversation". State facts you verified;
+mark anything uncertain as uncertain. If a conclusion is genuinely a
+judgement call the team still has to make, `outline_comment` the open
+question on the page rather than writing it up as settled.

package/skills/outline-wiki/SKILL.md

@@ -0,0 +1,70 @@
+---
+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
+---
+
+# Researching the Outline wiki
+
+The wiki is the team's memory. Code says what the system does; the wiki says
+why, who owns it, and what was already tried. Read it before guessing.
+
+## When to reach for it
+
+Use the wiki when the answer depends on this organisation:
+
+- "How do we deploy X?" / "What is our release process?"
+- "Why did we choose Y?" / "Is there a decision record for this?"
+- "Who owns service Z?"
+- "What is our convention for naming / branching / logging?"
+- The user mentions a page, a runbook, an ADR, or onboarding notes.
+
+Do **not** use it for general programming questions, or for facts that the
+repository in front of you answers directly.
+
+## The loop
+
+1. **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
+   `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.
+
+## Search that actually finds things
+
+- Start broad, then filter. Only add `collectionId` after
+  `outline_collections` told you which collection is relevant.
+- If a search returns nothing, try a synonym, an acronym, and the spelled-out
+  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`.
+- 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
+`https://acme.getoutline.com/doc/runbook-deploy-aBc123XyZ` also works: pass
+the trailing `runbook-deploy-aBc123XyZ` slug as `id`.
+
+## Honesty rules
+
+- If the wiki has nothing on the topic, say "the wiki does not cover this"
+  rather than filling the gap with plausible-sounding invention.
+- Distinguish what the wiki claims from what you verified in the code. A page
+  last updated two years ago is a hypothesis, not a fact.
+- Check `outline_comments` on a page before treating it as settled; open
+  questions and corrections often live in the comments, not the body.
+
+## Pulling content into the repo
+
+When the user wants wiki content available offline or in the repository, use
+`outline_export` with a `targetDir` instead of reading page after page
+through the model - it writes markdown files directly and costs no context.