feat: add agent docs and make oauth app docs more beginner friendly

[Prashant-Surya]

Description

• Re-write build plane app docs to make it more beginner friendly
• Add docs for building agents in plane

Type of Change

• Feature (non-breaking change which adds functionality)
• Improvement (change that would cause existing functionality to not work as expected)

Summary by CodeRabbit

• Documentation

  • Added comprehensive Agents docs: Overview, step‑by‑step build guide, best practices, and signals/content payload reference with runnable examples.
  • Heavily reworked "Build a Plane App" with clearer OAuth flows, webhook security guidance, token handling, SDK examples (Node/Python), and local dev tips.
  • Expanded Dev Tools navigation to expose Agents content and added visual workflow diagrams.

• New Features

  • Site now renders Mermaid diagrams for improved sequence and flow visualization.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
developer-docs	Ready	Preview, Comment	Jan 30, 2026 11:19am

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds comprehensive Plane Agents documentation (overview, building guide, best practices, signals/content payload), rewrites the Build a Plane App OAuth guide with detailed flows and examples, and integrates Mermaid support into VitePress plus navigation updates and new devDependencies.

Changes

Cohort / File(s)	Summary
VitePress config & tooling docs/.vitepress/config.mts, package.json	Wraps the default export with withMermaid(defineConfig(...)), adds mermaid plugin/config and expands optimizeDeps, and adds mermaid and vitepress-plugin-mermaid to devDependencies. Navigation updated to expose Agents submenu under /dev-tools/.
Agents docs — overview & concepts docs/dev-tools/agents/overview.md	New overview describing Plane Agents, lifecycle, states, and a high-level Mermaid sequence diagram.
Agents docs — building guide docs/dev-tools/agents/building-an-agent.md	New step-by-step guide for creating agents: OAuth app setup (bot/user flows), webhook events, activity payload types, SDK usage, and runnable Node.js/Python examples.
Agents docs — signals & payloads docs/dev-tools/agents/signals-content-payload.md	New reference for signals (continue, stop, auth_request, select) and content payload types (thought, action, response, elicitation, error, prompt) with schemas and multi-language examples.
Agents docs — best practices docs/dev-tools/agents/best-practices.md	New best-practices guide covering immediate acknowledgements, stop-signal handling, progress updates, error handling, context management, rate/timeouts, and example patterns (TS/Python).
OAuth & app integration (rewrite) docs/dev-tools/build-plane-app.md	Major rewrite: reorganized intro, explicit Bot Token and User Token flows, detailed token exchange/refresh, webhook signature verification, SDK mapping, local dev guidance (ngrok), and full Express/Flask example implementations and API payloads.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 I hopped through docs both near and far,

diagrams glitter like a tiny star,
OAuth paths and signals neatly penned,
agents ready—on them I depend,
hop on, build, and ship with a happy heart!

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the two main changes: adding agent documentation and improving OAuth app documentation for beginners.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/oauth-agent-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 10

🤖 Fix all issues with AI agents

In `@docs/.vitepress/config.mts`:
- Around line 1-29: The Vite config in the withMermaid(defineConfig(...)) call
is missing an ssr.noExternal setting which can cause unreliable Mermaid
rendering; update the vite object (alongside optimizeDeps in the exported
config) to include ssr: { noExternal: ['mermaid'] } so the mermaid package is
treated as non-external during SSR, ensuring withMermaid/mermaid behave
correctly.

In `@docs/dev-tools/agents/best-practices.md`:
- Around line 372-387: The checklist sections use bold text instead of proper
Markdown headings (MD036); update each bolded section title ("Responsiveness",
"Signal handling", "Error handling", "User experience") to an appropriate
heading level (e.g., "## Responsiveness") and leave their bullet lists intact so
the document uses heading syntax rather than **bold** to satisfy MD036; ensure
consistent heading level across all four sections and update any adjacent
formatting that relies on the old bold style.
- Around line 190-194: The markdown table under the "Signal | How to Handle"
header has misaligned pipes; normalize spacing so columns are vertically aligned
by padding each cell with spaces to match the widest cell in its column (ensure
the header row, separator row of dashes, and each data row use the same column
widths), e.g., align the `continue` and `stop` rows under the `Signal` and `How
to Handle` columns and adjust the separator row (`---`) to match those widths so
markdownlint MD060 passes; update the rows containing the symbols `continue` and
`stop` accordingly.
- Around line 8-10: Replace the bare email address "support@plane.so" in the
paragraph that starts "Plane Agents are currently in **Beta**." with a markdown
mailto link so markdownlint is satisfied; update the text to use a linked email
(make the displayed text the same address and the URL mailto:support@plane.so)
while preserving the surrounding sentence and emphasis.

In `@docs/dev-tools/agents/building-an-agent.md`:
- Around line 337-369: Update the "Error" activity description to match the
Ephemeral activities list: change the wording that currently says "Creates a
comment and sets run to `failed`" so it explicitly states that the `error`
activity is ephemeral (has `ephemeral: true`) and therefore does not create a
comment, and then clarify whether it still sets the run to `failed` (pick one
behavior and state it clearly). Reference the `error` activity, the `ephemeral:
true` flag, and the example JSON so the doc is consistent with the listed
ephemeral types (`thought`, `action`, `error`).

In `@docs/dev-tools/agents/signals-content-payload.md`:
- Around line 27-33: The table rows for the signals (`continue`, `stop`,
`auth_request`, `select`) violate the repo's markdownlint table-column-style;
normalize the pipe spacing so each cell has a single space padding on both sides
of content (e.g., "| Signal | Description | Use Case |") and ensure the header
separator row uses consistent pipes and dashes
("|--------|-------------|----------|"), then update all table rows to match
that exact spacing pattern to satisfy the linter.
- Around line 459-561: The docs currently contradict themselves about error
activities: the "Type: `error`" section and the ErrorContent example/state
(type: "error") claims it "creates a comment and sets the Agent Run status to
`failed`", but the "Automatically ephemeral types" list includes `error`; pick
one consistent behavior and update the text accordingly—either remove `error`
from the automatically ephemeral types list or change the "Type: `error`"
section (and the ErrorContent example/usage snippets such as the
TypeScript/Python create calls and the note about run status) to state that
error activities are ephemeral and do not create comment replies or change run
status; ensure references to ErrorContent, the JSON examples (type: "error"),
and the "Automatically ephemeral types" list are all updated to match.
- Around line 8-10: Replace the bare email address in the info block
("support@plane.so") with a Markdown mailto link so markdownlint is satisfied;
specifically update the text that currently reads "Please send any feedback to
support@plane.so." to use a mailto link format like
[support@plane.so](mailto:support@plane.so) within the same sentence.

In `@docs/dev-tools/build-plane-app.md`:
- Around line 481-490: The webhook handler currently passes potentially empty or
malformed signature buffers into crypto.timingSafeEqual causing a RangeError;
update the app.post('/webhook' ...) handler to validate the incoming signature
string before calling timingSafeEqual: check that the signature header (variable
signature) exists and is the expected hex length (e.g., 64 chars for sha256) and
contains only valid hex characters, return res.status(403) when it fails
validation, then compute expected and call
crypto.timingSafeEqual(Buffer.from(signature, 'hex'), Buffer.from(expected,
'hex')) only after the guard; refer to the variables and functions
app.post('/webhook', ...), signature, expected, WEBHOOK_SECRET, and
crypto.timingSafeEqual to locate and change the code.
- Around line 277-283: The verifySignature function uses crypto.timingSafeEqual
which will throw if the two Buffers differ in length; update verifySignature to
convert the signature and expected HMAC to Buffers (e.g., Buffer.from(...)) and
check bufA.length === bufB.length before calling crypto.timingSafeEqual,
returning false if lengths differ; apply the same length-guard pattern to the
Express webhook handler example (the webhook request signature comparison) so it
also compares buffer lengths and short-circuits to false rather than calling
timingSafeEqual when lengths differ.