# Phase 11: Individual Planning - Context

**Gathered:** 2026-05-16
**Status:** Ready for planning

<domain>
## Phase Boundary

Phase 11 delivers a protected personal planning page at `/planning` for each authenticated user. The page aggregates that user's scheduled events across accessible tablos, presents them as a chronological agenda, and links each event back to its tablo context. This phase does not add new event creation/editing semantics beyond using the Phase 10 event model and tablo Events tab.

</domain>

<decisions>
## Implementation Decisions

### Planning Navigation Window
- **D-01:** `/planning` defaults to an upcoming agenda view rather than a week or month calendar.
- **D-02:** The default agenda range is the next 14 days starting from today.
- **D-03:** Navigation uses fixed 14-day windows with `Today`, previous-window, and next-window controls.
- **D-04:** Past events are not shown by default, but users can reach past events intentionally through previous-window navigation.
- **D-05:** Keep the first planning view focused on agenda browsing. Do not recreate the Phase 10 tablo Events month calendar on the personal planning page.

### Agenda Row Content
- **D-06:** The agenda renders as a single continuous chronological list, not grouped by day or by tablo.
- **D-07:** Each event row shows time, title, tablo context, and location when present.
- **D-08:** Do not show description snippets in the first planning agenda rows; avoid noisy/tall rows.
- **D-09:** Tablo context appears as the tablo title plus a small color dot using `tablo_color` when present.
- **D-10:** Events without an end time display the start time only. Do not add "no end" copy or infer a default duration.

### the agent's Discretion
- Exact route handler names, template names, query parameter names, and HTMX fragment boundaries are planner discretion if they preserve the decisions above and match existing Go/HTMX patterns.
- Exact empty-state wording is planner discretion, but it must be functional and plain.
- Exact date label formatting is planner discretion, but the list must remain chronological and easy to scan.

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Product Scope
- `.planning/ROADMAP.md` - Phase 11 goal, MVP mode, success criteria, and user-in-loop decision about today/upcoming versus week navigation.
- `.planning/REQUIREMENTS.md` - PLAN-01 through PLAN-04 and Phase 11 traceability.
- `.planning/PROJECT.md` - v2 constraints: Go + HTMX, individual planning, plain functional UI, and no JS framework.

### Event Handoff
- `.planning/phases/10-events/10-CONTEXT.md` - Event date/time semantics, planning handoff decisions, and deep-link expectations.
- `.planning/phases/10-events/10-03-SUMMARY.md` - User-scoped event range query and navigation/prefill behavior delivered for planning.
- `.planning/phases/10-events/10-04-SUMMARY.md` - Final Phase 10 verification and browser UAT approval.
- `.planning/phases/10-events/10-VERIFICATION.md` - Evidence that EVENT-01..05 and planning handoff query passed.

### Go Backend Entry Points
- `backend/internal/db/queries/events.sql` - `ListUserEventsRange` query returns event fields plus `tablo_title` and `tablo_color` filtered by `tablos.user_id`.
- `backend/internal/web/router.go` - Protected route group and static route ordering pattern where `/planning` should mount.
- `backend/internal/web/handlers_events.go` - Event date/month parsing and event ownership conventions to reuse where relevant.
- `backend/templates/events_forms.go` - Event date/time formatting helpers and `EventTimeRange` behavior for no-end-time display.
- `backend/templates/layout.templ` - Authenticated shell and navigation integration point.
- `backend/templates/tablos.templ` - Existing server-rendered page/tab patterns and plain UI style.
- `backend/internal/web/handlers_events_test.go` - DB-backed event aggregation, ordering, ownership, and formatting tests to mirror for planning.

### Historical TypeScript Reference
- `apps/main/src/pages/planning.tsx` - Old planning page reference for possible agenda concepts only; do not recreate its imports/exports/month/week/day complexity in Phase 11.
- `packages/shared-types/src/events.types.ts` - Historical `EventAndTablo` shape for reference only.

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `ListUserEventsRange` already provides the core data needed for `/planning`: event date/time fields, title, location, description, `tablo_id`, `tablo_title`, and `tablo_color`.
- `templates.FormatEventDate`, `templates.FormatEventTime`, and `templates.EventTimeRange` provide event formatting behavior that keeps Phase 11 consistent with Phase 10.
- Existing `Layout` templates provide the authenticated page shell; `/planning` should be a normal protected page, not a tablo tab.
- Existing `ui.Button` and form/error helpers are enough for a plain toolbar with Today/previous/next navigation.

### Established Patterns
- Protected pages live inside the `auth.RequireAuth` route group and get the authenticated user from context.
- SQLC query files are canonical; generated Go files are reproduced by `just generate` and should not be hand-edited.
- DB-backed web tests use `setupTestDB`, `preInsertUser`, session cookies, and the full router to prove auth and query behavior.
- User-scoped aggregation must filter by `tablos.user_id`, not by trusting event IDs or client-supplied tablo IDs.
- Non-HTMX full-page behavior should work for primary pages; HTMX can be used for navigation fragments if the planner chooses.

### Integration Points
- Add a `/planning` route in the protected router group.
- Add a planning handler/dependency shape using `sqlc.Queries`.
- Add a planning template rendering the 14-day agenda, toolbar, empty state, and event rows.
- Use `ListUserEventsRange` with a calculated start/end date based on query params or defaults.
- Add handler tests for unauthenticated redirect, owned-only aggregation, chronological ordering, navigation links, empty state, and event links back to tablo context.

</code_context>

<specifics>
## Specific Ideas

- The first personal planning page should feel like an agenda, not another calendar.
- Default to the next 14 days from today.
- Keep rows compact: time, event title, tablo title/color, and location if present.
- Event links should carry users back to the tablo context; Phase 10 established `/tablos/{id}/events?month=YYYY-MM` as the planning deep-link shape.

</specifics>

<deferred>
## Deferred Ideas

- Week and month planning views.
- Date picker navigation.
- Grouped-by-day or grouped-by-tablo planning layouts.
- Description snippets in agenda rows.
- ICS import/export, external calendar sync, and recurrence.

</deferred>

---

*Phase: 11-Individual Planning*
*Context gathered: 2026-05-16*
