# Roadmap — as of 2026-04-21

Stitches together the pending work from today's session. Next session should read this first, then fan out to the linked design docs.

## Currently uncommitted (in this working tree)

Run `git status` before anything else. Expected pile:

- Yesterday's 9 audit fixes (morning audit part 1, all verified holding)
- Today's `places_search` + `places_details` native tools
- Today's `show_map` inline UI tool + PlaceMap renderer (with dark tiles, fitBounds, container-query layout)
- Today's Save-to-Files button in ArtifactSidebar
- Today's starter branding / secrets docs / env updates for `GOOGLE_PLACES_API_KEY`

**First action next session**: commit this pile in two or three logical commits, push, then start Phase 1.

## Phases in order

### Phase 1 — Morning audit fixes (~2 hours)

From `.jez/artifacts/ux-audit-2026-04-21.md`. Highest ROI first.

- **H1** — conversation title leaks `<skill_content>` wrapper. **Verify first** — part 2 audit suggests this may already be fixed (sidebar titles now read cleanly). Repro with `/plan-task <prompt>` in a fresh chat and inspect breadcrumb + sidebar title.
- **H2** — SkillActivationBlock pill doesn't render during streaming. Streaming state must run parseSkillActivation, not just persisted load.
- **M1** — no slash-command autocomplete. Typing `/` should open a picker of enabled skills. Use existing skills registry.
- **M2** — empty-state "Good evening" bleeds into active streaming conversations. Gate on "messages.length === 0 AND not streaming".
- **L1** — `/skill-name` inline code pill wraps at hyphen on Skills page (add `white-space: nowrap`).
- **L2** — sidebar toggle has no tooltip (add `title` / `aria-label`).
- **T1** — theme editor HSL inputs missing H/S/L column labels.
- **T2** — theme editor token names not self-descriptive (tooltip per row).
- **T3** — Paste CSS placeholder looks like real content (dim it, or show as example above the textarea).
- **A1** — activity feed leaks skill wrapper (same root cause as H1, fix once at save layer).
- **A2** — `/dashboard/notifications` 404s (add page OR "View all" link in bell dropdown).
- **ADM1** — admin feature flags tab only shows DB-driven flags (add "Deploy-time flags" read-only section).
- **ADM2** — Active Sessions 8 vs Total Users 4 (add session cleanup scheduled worker).

### Phase 2 — Map-feature polish (~1 hour)

From `.jez/artifacts/ux-audit-2026-04-21-part2.md`.

- **MAP-5** — card-click zoom too aggressive. Either cap at zoom 12 or only fly-to when off-screen.
- **MAP-6** — no discoverability chip on empty state. Add "Find local businesses" example prompt.
- **MAP-7** — 50k tokens per wreckers query. Either accept (cost is fine) or sketch the `places_from` pattern to reuse tool output.

### Phase 3 — Email integration (~1.5-2 days)

See `.jez/artifacts/email-design.md`.

Quick summary:
- `src/server/modules/email/` wrapper — Email Service primary, Email Routing SendEmail fallback
- Templates: password-reset, magic-link, invite, welcome, notification, email-verification
- Wire into better-auth `sendResetPassword` / `sendVerificationEmail`
- Admin "invite user" flow
- Agent `send_email` tool with `needsApproval: true`
- `email_log` D1 table + admin view
- Optional Queue consumer for async retries

**Why before Phase 4**: quick win, unblocks every better-auth flow that needs email, demonstrates Queues pattern, small surface area. ~2 days for huge fork value.

### Phase 4 — RAG over user files (~2 days)

Note: previously numbered Phase 2 in my earlier thinking — rebalanced here because email should ship first.

- Ingest pipeline: R2 put → Queue message → consumer → `env.AI.toMarkdown()` → chunk → embed (`@cf/baai/bge-m3`) → Vectorize upsert with `{userId, fileId, chunkIndex, excerpt, mimeType}` metadata
- Vectorize metadata index MUST be created BEFORE first insert (known gotcha)
- Agent tool: `search_files(query, limit)` → filter by userId → return chunks + file refs
- Files page: "Indexed ✓" badge on ingested files
- Auto-ingest chat-attachment saves from today's Save-to-Files feature
- Re-ingest on file rename/update
- Delete vectors when file deleted

Prerequisite dependencies built: chat Save-to-Files (already shipped today), `env.VECTORS` binding (already wired).

### Phase 5 — MCP Connectors (~10-12 days)

See `.jez/artifacts/mcp-connectors-design.md`.

This is the big one. Broken into sub-phases:

- **5.1** — OAuth scaffolding + Google Drive as first connector (~3 days)
- **5.2** — Full Google Workspace catalogue (Gmail, Calendar, Docs, Sheets, Slides, Tasks, Contacts) (~1 day)
- **5.3** — Per-tool permissions UI (~2 days)
- **5.4** — Bearer token fallback flow (~1 day)
- **5.5** — Browse connectors modal + Add custom connector (~2 days)
- **5.6** — RAG integration: connector-sourced docs feed the Phase 4 pipeline (~1-2 days on top)

Screenshots of reference UX at `/Users/jez/Documents/screenshots/Screenshot 2026-04-21 at 10.*.pm.png`.

## Design docs

| Topic | File |
|-------|------|
| Morning audit findings (14 items, 9 verified from yesterday) | `.jez/artifacts/ux-audit-2026-04-21.md` |
| Afternoon audit + places/map feature | `.jez/artifacts/ux-audit-2026-04-21-part2.md` |
| Email integration (Phase 3) | `.jez/artifacts/email-design.md` |
| MCP Connectors (Phase 5) | `.jez/artifacts/mcp-connectors-design.md` |
| This roadmap | `.jez/artifacts/roadmap-2026-04-21.md` |

## Screenshots / references worth keeping

- `/Users/jez/Documents/screenshots/Screenshot 2026-04-21 at 10.03.29 pm.png` → `10.04.54 pm.png` — full claude.ai connectors UX reference
- `/Users/jez/Documents/screenshots/Screenshot 2026-04-21 at 1.22.31 pm.png` — claude.ai Google Maps answer format (the pattern we copied for `show_map`)

## Total time estimate

| Phase | Estimate |
|-------|----------|
| Commit | 15 min |
| Phase 1 — audit fixes | 2 hrs |
| Phase 2 — map polish | 1 hr |
| Phase 3 — email | 1.5-2 days |
| Phase 4 — RAG over files | 2 days |
| Phase 5 — MCP connectors | 10-12 days |
| **Total** | **~2-3 weeks of focused work** |

## Ordering rationale

1. **Commit first** — prevents merge pain if laptop breaks or Jez swaps machines
2. **Audit fixes before new features** — H1/H2/M1 are user-visible polish blockers
3. **Map polish** is cheap and closes the current feature arc
4. **Email before RAG** — email unblocks auth flows for any fork that enables email/password. RAG is a more advanced feature that smaller forks may not need.
5. **RAG before Connectors** — the RAG pipeline becomes the ingestion target for connector-sourced documents (Phase 5.6)
6. **Connectors last** — largest piece, needs the other phases to be stable

## Principles carried through this roadmap

- **Don't break the starter's fork-friendly story** — every feature must work with minimum config and degrade gracefully when bindings/secrets are missing
- **Every phase produces a demo-ready artefact** — no half-done phases
- **Document-as-you-go** — update CLAUDE.md, `.dev.vars.example`, and inline comments as each phase lands
- **Security-conscious defaults** — destructive tools `ask` by default, no tokens in logs, encrypted storage for OAuth tokens
- **Pattern-library discipline** — whatever ships teaches the forker how to build similar capabilities, not just "use this feature"

## If time is short — the ruthless version

If only 2 days next session:
1. Commit (15 min)
2. H1/H2/M1 + MAP-6 (3 hrs)
3. Phase 3.1 — email wrapper + password reset wired into better-auth (4 hrs)
4. Phase 3.3 — agent `send_email` tool (2 hrs)

Everything else defers. This still delivers real value and unblocks email-dependent auth flows.

---

**Last updated**: 2026-04-21
