Recommendation
Yes: map the product first, but keep the mapping lightweight and immediately useful. The goal is not to document every implementation detail before publishing. The goal is to create a trustworthy information architecture that lets us update the highest-impact pages first, then keep every new product surface connected to a maintained source of truth.Current state snapshot
| Area | What exists today | Gap to close |
|---|---|---|
| Product help | Feature pages for CRM, properties, communication, marketing, settings, and automation. | Pages need to be checked against the current app flows, screenshots, and Winnie/Agent OS positioning. |
| Developer docs | Internal getting started, webhooks, API reference stubs, and architecture pages exist. | Developer/API/architecture pages are not exposed in the main Mintlify navigation, so they are effectively hidden. |
| Agent OS docs | Deep specifications live in repository docs. | The docs app does not yet explain the customer-facing Agent OS promise, governance model, or implementation status. |
| Information architecture | Sidebar follows product areas. | Missing audience paths for agents, team admins, brokerage operators, developers, and support. |
| Content quality | Many pages have useful starting copy. | Some pages are likely stale, generic, or template-derived and need product verification. |
Documentation map
Use this map as the north star for the docs app.1. Agent and team buyer docs
These pages should help real estate professionals get value quickly.- Start here: quickstart, dashboard, people, deals, phone, SMS, email, tasks, notes, calendar.
- Core workflows: speed-to-lead, sphere nurture, deal follow-up, call prep, showing follow-up, listing launch, client portal handoff.
- Winnie guidance: what Winnie can draft, summarize, suggest, and update; what still requires agent approval.
- Trust guidance: consent, opt-outs, call recordings, client data, and team visibility.
2. Admin and brokerage operator docs
These pages should help teams roll Winnerr out safely.- Organization setup: members, roles, agent transfers, onboarding, billing.
- Governance: workspace isolation, permissions, audit trails, data retention, and AI approval settings.
- Operations: lead routing, team reporting, business pipelines, templates, phone/email setup.
- Rollout playbooks: pilot launch, team migration, training checklist, data import QA.
3. Developer and integration docs
These pages should help internal engineers, partners, and technical operators build confidently.- Local development and monorepo structure.
- Authentication between
apps/appandapps/api. - API reference, webhooks, Zapier, MCP, Twilio, Nylas, MLS, and storage policy.
- Event-driven systems: outbox, workflow handlers, webhook verification, idempotency, retries, and observability.
4. Agent OS and Winnie docs
These pages should translate the repository’s Agent OS work into user-facing and operator-facing documentation.- Agent OS overview: what it is, what it is not, and how it relates to the CRM.
- AiChangeProposal model: how agent-suggested actions become reviewable changes.
- Memory and consent: what is remembered, why, and how users control it.
- Guardrails: PII masking, opt-in transparency, approval gates, and workspace isolation.
- Rollout status: what is available now, what is in private beta, and what is planned.
Priority plan
Phase 0 — Make docs navigable
- Add a documentation roadmap page.
- Expose existing developer, API, architecture, and integration pages in
mint.json. - Remove or hide Mintlify template pages from the public sidebar unless they are intentionally kept as authoring guidance.
- Add a clear audience path from the introduction page.
Phase 1 — Verify the product surface
- Walk the live app sidebar and create a page inventory by route.
- For each page, record: route, owner, audience, current status, screenshots needed, and source-of-truth code paths.
- Mark each docs page as current, needs refresh, missing, or deprecated.
- Prioritize pages tied to activation, revenue workflows, or support tickets.
Phase 2 — Rewrite high-impact docs
- Quickstart and onboarding.
- Phone, SMS, email, and communication history.
- People, person detail, insights, deals, and pipelines.
- Winnie and AI settings.
- Team/admin rollout.
Phase 3 — Build durable maintenance
- Add a docs freshness checklist to every major release.
- Require new feature PRs to include a docs decision: new page, update page, no docs needed.
- Keep API docs generated or checked against route contracts where possible.
- Run link checks before publishing.
Page quality standard
Every maintained docs page should answer these questions:- Who is this for?
- What job does this help them complete?
- Where is it in the app?
- What prerequisites are required?
- What exact steps should the user take?
- What does Winnie do automatically, suggest, or require approval for?
- What data, permissions, or compliance concerns apply?
- What related pages should the user read next?
Near-term backlog
| Priority | Work item | Outcome |
|---|---|---|
| P0 | Publish this roadmap and link it from Getting Started. | Team alignment on docs recovery work. |
| P0 | Add Developer, API Reference, Architecture, and Integrations to navigation. | Existing pages become discoverable. |
| P0 | Audit stale version claims such as old Next.js references. | Docs stop contradicting the monorepo. |
| P1 | Rewrite Quickstart around first-value workflows. | New users can activate without support. |
| P1 | Create a Winnie/Agent OS overview page. | AI positioning becomes consistent and trustworthy. |
| P1 | Refresh communication docs against phone, SMS, email, transcripts, and recordings. | Revenue-critical workflows are accurate. |
| P2 | Add admin rollout and brokerage operator guides. | Teams can deploy Winnerr consistently. |
| P2 | Add docs contribution workflow for engineers. | Documentation stays current after the recovery push. |
Definition of done
The documentation app is caught up when:- The sidebar reflects the real product, not the historical folder structure.
- Users can find first-value workflows without knowing internal terminology.
- Admins understand setup, governance, and rollout responsibilities.
- Developers can find API, webhook, auth, and integration guidance from the main navigation.
- AI and Agent OS pages explain capabilities conservatively without implying Winnie replaces the agent.
- Every major page has an owner, freshness status, and source-of-truth reference.