docs: add Proactive agents page (cron + integration + combined)

[khaliqgant]

Summary

Adds a single docs page documenting how to build a proactive agent — a persona with one or more listeners that fire without a human in the loop. There was nothing on the topic in the docs today; the workforce-side machinery has shipped but the surface was undocumented.

Covers:

• The three listener kinds (clock / radio / inbox) and the shared `onEvent` discrimination model.
• Concrete `persona.json` + `agent.ts` for each pattern: cron-only, integration-only, and combined.
• The `source` scope discriminator (`deployer_user` / `workspace` / `workspace_service_account`) — what each one resolves against and how to pick.
• Inputs, deploy, and memory in one screen each.

Filed under Advanced, after Workforce.

Test plan

• `pnpm typecheck` in `web/` clean for the three touched files (`docs-nav.ts`, `DocsNav.tsx`, the new `.mdx`)
• Slug routed via existing `getAllDocSlugs` (no static-generation changes needed — the new entry in `docsNav` is picked up automatically)
• Visual check of the rendered page + nav entry locally before merge

🤖 Generated with Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 5d923c1a-b921-4375-8808-aec227bf95fe

📥 Commits

Reviewing files that changed from the base of the PR and between b453a6f and abb81c5.

📒 Files selected for processing (1)

• web/content/docs/proactive-agents.mdx

---

📝 Walkthrough

Walkthrough

This PR adds comprehensive documentation for proactive agents—personas with automated listeners (clock/cron, integrations, inbox)—and integrates it into the docs navigation system with a Zap icon.

Changes

Proactive agents documentation and navigation

Layer / File(s)	Summary
Navigation wiring and icon web/components/docs/DocsNav.tsx, web/lib/docs-nav.ts	Import Zap icon from lucide-react and add proactive-agents entry to navIcons mapping and docsNav data, making the slug discoverable via getAllDocSlugs().
Proactive agents documentation web/content/docs/proactive-agents.mdx	Add MDX page with frontmatter and sections covering proactive agent definition, anatomy (persona.json + agent.ts), cron-based, integration-based, and combined listener examples, deploy-time inputs resolution, deployment commands/modes, persistent memory configuration and examples, and related docs links.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• AgentWorkforce/relay#865: Extends web/lib/docs-nav.ts to add a new doc entry (reference-broker-api) to the shared navigation structure.

Poem

A Zap of wisdom now lights the way, ⚡
Personas wake at night and day.
Cron and radio, inbox too,
A rabbit docs the steps for you.
Hopping knowledge — swift and true.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding a new documentation page for proactive agents with the three key listener patterns (cron, integration, combined).
Description check	✅ Passed	The description covers all required template sections (Summary and Test Plan) with comprehensive details about what was added, why it matters, test verification completed, and pending visual validation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/proactive-agents

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

web/content/docs/proactive-agents.mdx

Parsing error: Expression expected.

---

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.}

[github-actions]

Preview deployed!

Environment	URL
Web	https://d2nz9xnexak4qy.cloudfront.net

This preview will be cleaned up when the PR is merged or closed.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

web/content/docs/proactive-agents.mdx (1)

197-203: ⚡ Quick win

Consider explaining ttlDays before showing it.

Line 203 introduces ttlDays: 60 in the memory configuration example without prior explanation. While the field name is somewhat self-documenting, a brief note about memory retention/expiration would help readers understand when and why to configure it.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@web/content/docs/proactive-agents.mdx` around lines 197 - 203, Add a short
explanatory sentence about ttlDays immediately before the example so readers
know it controls memory retention/expiration (e.g., how long saved memories
persist and are eligible for recall), then present the JSON snippet with
"memory": { "enabled": true, "scopes": ["workspace"], "ttlDays": 60 }; reference
the memory.enabled, memory.scopes, and ttlDays fields so the reader can connect
the description to the example.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@web/content/docs/proactive-agents.mdx`:
- Around line 37-72: Clarify the "cron-based" vs "cron-only" terminology: update
the "Cron-based (clock listener)" section and the sentence that currently reads
"Cron-only personas get all integration fields as `undefined`" to explain that
integrations declared under the persona (the integrations object and entries in
schedules[]) serve two roles—(1) defining triggers (what events the persona
receives) and (2) making runtime clients available on ctx (e.g., ctx.slack!,
ctx.github). Explicitly state that a persona with schedules but with
integrations declared (as in the example using schedules and "integrations": {
github, slack }) will receive only cron events while still having client access,
whereas a true "cron-only" persona that omits any integrations entirely will
have those ctx.<provider> clients be undefined; reference the example's
schedules, integrations, event.source/event.name checks, and the
handler/ctx.slack! usage to guide placement of the clarifying note.

---

Nitpick comments:
In `@web/content/docs/proactive-agents.mdx`:
- Around line 197-203: Add a short explanatory sentence about ttlDays
immediately before the example so readers know it controls memory
retention/expiration (e.g., how long saved memories persist and are eligible for
recall), then present the JSON snippet with "memory": { "enabled": true,
"scopes": ["workspace"], "ttlDays": 60 }; reference the memory.enabled,
memory.scopes, and ttlDays fields so the reader can connect the description to
the example.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7e8979e6-d84d-4ffd-8180-6188209bf2ab

📥 Commits

Reviewing files that changed from the base of the PR and between eefe64b and b453a6f.

📒 Files selected for processing (3)

• web/components/docs/DocsNav.tsx
• web/content/docs/proactive-agents.mdx
• web/lib/docs-nav.ts

[cubic-dev-ai]

No issues found across 3 files

_{Re-trigger cubic}