1. Getting Started

Planning Cockroach is a web-based platform for revenue and sales planning. It connects to your CRM (Salesforce or Hubspot), lets you build interactive scenarios and forecasts, and gives you an AI assistant (“Aunt Roachie”) to ask questions about your data in plain language. Planning Cockroach exposes an MCP (Model Context Protocol) server, so you can connect your workspace data directly to AI tools like Claude, without needing the Planning Cockroach UI.

Core concepts:

• Workspace — your team’s shared environment; all connections, scenarios, and users live here.
• Scenario — a modeled version of your pipeline/forecast (e.g. “best case Q4”) that you can adjust and compare.
• Factory — where you build and configure your data model and automations.
• Playground — a sandbox to experiment with scenarios without affecting live data.

2. Setup & CRM Connection

1. Go to Settings → Connections in your workspace.
2. Choose your CRM (currently Salesforce; HubSpot support in progress).
3. Click Connect and authorize via OAuth — no credentials are shared directly with Planning Cockroach.
4. Once connected, configure field mapping so your CRM’s fields align with Planning Cockroach’s data model.
5. Trigger your first sync. Initial syncs may take a few minutes depending on data volume.

Good to know: Connections can expire (OAuth tokens have a validity period). Check Settings → Connections periodically, or watch for expiry notifications once available (see Notifications below).

3. Authentication

• Login is handled via our identity provider (Keycloak), supporting email/password and Google sign-in.
• Workspace admins can invite team members under Settings → Team. Invited users receive an email invite.
• Roles determine what a user can see and do — check with your workspace admin if you’re missing access to a feature.

4. How to Use Factory

Factory is where you configure the underlying data model that powers your scenarios and reports:

• Define how CRM data maps to your planning structure
• Set up custom fields, pipelines, and business rules
• Run audits to check data hygiene (e.g. missing fields, duplicate records)

Use Factory when you’re setting up or restructuring how your data flows into Planning Cockroach — not for day-to-day scenario work.

5. How to Use Playground

Playground is your sandbox for scenario modeling:

• Duplicate a live scenario or start fresh
• Adjust assumptions (deal velocity, win rates, headcount, etc.)
• Compare outcomes side-by-side without affecting your actual forecast

Use Playground when you want to explore “what if” questions before committing to a plan.

6. AI Assistant: “Aunt Roachie”

Aunt Roachie lets you ask questions about your pipeline in natural language, e.g.:

• “Which deals are at risk of slipping this quarter?”
• “Summarize rep performance for the EMEA team.”
• “What changed in my forecast since last week?”

Good to know:

• Aunt Roachie’s answers are generated based on your live CRM data — accuracy depends on your data quality (see Factory audits).
• By default, Anthropic powers Aunt Roachie; OpenAI can be selected as an alternative provider in settings.
• Aunt Roachie output does not constitute legal, tax, or financial advice, and should be reviewed before use in business decisions.

7. MCP & Integrations

Planning Cockroach exposes an MCP (Model Context Protocol) server, so you can connect your workspace data directly to AI tools like Claude — without needing the Planning Cockroach UI.

1. Go to Settings → Connectors → MCP.
2. Copy the connector URL.
3. Add it as a custom connector in your AI tool of choice, and authorize with your Planning Cockroach account.
4. Once connected, ask your AI assistant questions about your pipeline directly — it will use the same live data as the platform.

8. Notifications (planned)

Planning Cockroach will notify you and your team about key events — in-app, by email, or (soon) directly in Slack, so you don’t need to check the UI to stay on top of your pipeline. Planned notifications include: connection issues, sync failures, scenario updates, and team activity.

9. Troubleshooting / FAQ

My CRM sync hasn’t run / data looks stale. Check Settings → Connections — your connection may have expired and need to be re-authorized.

Aunt Roachie gives me an answer that looks wrong. Check your underlying data in Factory first — most inaccuracies trace back to data quality issues (missing fields, stale sync) rather than the AI itself.

I can’t see a feature/section. Check with your workspace admin — this may be a role/permission issue.

This documentation is a living draft. Sections marked “(planned)” describe features in development and are not yet live.