letsbe/pn-new-crm
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs(uat): annotate master doc + plan for Group A ships (e33313b)

Browse Source 
7 master-doc entries now carry the `SHIPPED in e33313b` line:
  - Admin Documenso env-fallback pills
  - WatchersCard empty-state padding (follow-up bump)
  - /invoices/upload-receipts copy rewrite
  - Pageviews chart X-axis tick thinning
  - CommandList scroll-cap (popover-aware max-h)
  - DropdownMenu max-h cap (Radix-aware)
  - Residential InterestsTab standalone-list whole-row navigate
  - StageStepper visible stage names

3 master-doc entries verified pre-shipped (A3, A6, A8) — already
carrying SHIPPED markers from earlier commits; A6 + A8 confirmed
in the new commit notes for cross-reference.

Plan doc (`2026-05-21-remaining-plan.md`) Group A section
collapsed to a 12-line ✓ list pointing at the verifying commits.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Matt
2026-05-21 21:38:27 +02:00
parent e33313bd64
commit 670ca16a05
2 changed files with 22 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
docs/superpowers/audits/2026-05-21-remaining-plan.md
View File

@@ -16,24 +16,22 @@
---
## Group A — Tiny copy / UI fixes (batch as one PR, ~1 h total)
## Group A — Tiny copy / UI fixes — [SHIPPED in e33313b]
These are all <15 min each. Bundle so the commit history doesn't sprawl.
All 12 items closed. 7 new ships + 5 verified pre-shipped (annotation gap in master doc).
1. **[Q] Admin Documenso settings: surface env-fallback state pills** — _src/app/(dashboard)/[portSlug]/admin/documenso/page.tsx_. Pattern from `203f543` (env-fallback tooltip on password fields) needs to be applied to all Documenso settings fields. Show `Using env fallback` / `Per-port override active` pill next to each field. ~30 min.
2. **[Q] WatchersCard empty-state padding** — small CSS fix, add `pb-2` or `pb-3` to the empty state. ~5 min.
3. **[Q] EOI empty state: add "Mark as signed without file" button (parity with Reservation + Contract tabs)** — _src/components/interests/interest-eoi-tab.tsx_ — copy the existing button from the reservation/contract tabs that fires `markStageSigned` without requiring a PDF upload. ~10 min.
4. **[Q] `/invoices/upload-receipts` guide: copy rewrite** — terse, professional, in the luxury-CRM voice. ~10 min.
5. **[Q] Pageviews chart: X-axis date ticks too cramped — drop the time component** — _src/components/website-analytics/_. Format ticks `MMM d` instead of `MMM d HH:mm`. ~5 min.
6. **[Q] Pageviews chart: inline note explaining Pageviews vs Sessions** — small `<p>` under the chart title. ~5 min.
7. **[Q] Inbox: swap section order — Reminders above Alerts** — _src/components/inbox/_. Single JSX reorder. ~3 min.
8. **[Q] BulkAddBerthsWizard: currency field should use `<CurrencySelect>`** — _src/components/admin/bulk-add-berths-wizard.tsx_. Swap raw input for the existing component. ~5 min.
9. **[Q] CommandList scroll-cap bug** — _src/components/ui/command.tsx_. CommandList inside Popover scrolls short of the bottom. Add `max-h-[var(--radix-popover-content-available-height)]` to the inner scroll container. Affects every cmdk dropdown. ~10 min.
10. **[Q] DropdownMenu content stretches to fill viewport — cap it** — _src/components/ui/dropdown-menu.tsx_. Add `max-h-[80vh]` to the content variant. ~5 min.
11. **[Q] Residential InterestsTab: whole row should navigate to the interest, not just the "View" link** — wrap row in `<Link>` or add `onClick` to the row. ~10 min.
12. **[Q] StageStepper: surface stage names visibly on reached slices** — _src/components/interests/stage-stepper.tsx_. Currently shows just an icon; add `aria-label` + visible text below the icon on reached slices. ~15 min.
**Commit shape:** one PR titled `chore(uat-batch): group-A copy + UI quick fixes (12 items)`.
1. **[SHIPPED — e33313b]** Admin Documenso settings env-fallback pills — collapsed legacy SettingsFormCard blocks into RegistryDrivenForm sections (`documenso.behavior` + `documenso.templates`).
2. **[SHIPPED — e33313b]** WatchersCard empty-state padding — `mb-3` → `mb-4 pb-1`.
3. **[SHIPPED — 52342ee, verified]** EOI "Mark as signed without file" button — already in place.
4. **[SHIPPED — e33313b]** /invoices/upload-receipts copy rewrite — ~50% body-copy reduction, terse luxury-CRM voice.
5. **[SHIPPED — e33313b]** Pageviews X-axis ticks — `interval="preserveStartEnd"` + `minTickGap={52}`.
6. **[SHIPPED earlier, verified]** Pageviews vs Sessions explainer — Info popover already in `website-analytics-shell.tsx`.
7. **[SHIPPED — e33313b]** Inbox section order — docstring fixed; JSX already had Reminders before Alerts.
8. **[SHIPPED earlier, verified]** BulkAddBerthsWizard CurrencySelect — already wired at apply-to-all + per-row.
9. **[SHIPPED — e33313b]** CommandList scroll-cap — `max-h-[min(300px,var(--radix-popover-content-available-height,300px))]`.
10. **[SHIPPED — e33313b]** DropdownMenu max-h cap — `max-h-[min(24rem,var(--radix-dropdown-menu-content-available-height,24rem))]`.
11. **[SHIPPED — e33313b]** Residential InterestsTab whole-row navigate — `<tr onClick>` + first-cell Link stopPropagation.
12. **[SHIPPED — e33313b]** StageStepper visible stage names — stage-name row below the bar; `size="xs"` hides labels.
---

14
docs/superpowers/audits/alpha-uat-master.md
View File

@@ -25,7 +25,7 @@ _Copy tweaks, alignment, single-prop edits, obvious typos._
>
> - **Rename "Mark in EOI bundle" + add tooltip** — _src/components/interests/linked-berths-list.tsx (or wherever the toggle lives)_ — the toggle controls `interest_berths.is_in_eoi_bundle` (per CLAUDE.md), which decides _which_ of the deal's berths the signed EOI document actually commits to. Today the rep sees a label they can't decode. Rename to something like "Include in EOI" + add an info-tooltip popover explaining "Berths flagged here are covered by the EOI signature. A deal can flag a subset (e.g. 2 of 3 linked berths)." ~10 min. **SHIPPED in db51106:** label renamed to "Include in EOI"; existing tooltip already explained the bundle-vs-signature distinction.
> - **Lower supplemental-info-request link TTL to ~2 weeks** — _src/lib/services/_ (token model) — link currently expires ~1 month out (`Wed, 17 Jun 2026` shown for an email sent May 18 = ~30 days). User wants ~14 days. Single constant change. ~5 min. **SHIPPED in db51106:** `TOKEN_TTL_DAYS` 30 → 14 in supplemental-forms.service.
> - **Admin Documenso settings: surface env-fallback state** — _src/app/(dashboard)/[portSlug]/admin/_ (Documenso settings page) — `getPortDocumensoConfig` already does the right thing (`adminValue ?? env.DOCUMENSO_API_KEY ?? ''`), but the admin UI doesn't show which fields are filled by the admin entry vs. silently falling back to env. Caused an in-session diagnosis loop where the operator had entered creds on Port Amador but was generating EOIs on Port Nimara — Port Nimara's admin row was empty, so it fell back to a stale env key and threw 401. Recommend a small "Using fallback from env" / "Per-port override active" pill next to each Documenso settings field so the operator can see at a glance which scope is in effect. ~30 min.
> - **Admin Documenso settings: surface env-fallback state** — _src/app/(dashboard)/[portSlug]/admin/_ (Documenso settings page) — `getPortDocumensoConfig` already does the right thing (`adminValue ?? env.DOCUMENSO_API_KEY ?? ''`), but the admin UI doesn't show which fields are filled by the admin entry vs. silently falling back to env. Caused an in-session diagnosis loop where the operator had entered creds on Port Amador but was generating EOIs on Port Nimara — Port Nimara's admin row was empty, so it fell back to a stale env key and threw 401. Recommend a small "Using fallback from env" / "Per-port override active" pill next to each Documenso settings field so the operator can see at a glance which scope is in effect. ~30 min. **SHIPPED in e33313b:** collapsed `V2_FEATURE_FIELDS` + `CONTRACT_RESERVATION_FIELDS` (legacy `SettingsFormCard`) into `RegistryDrivenForm` sections (`documenso.behavior` + the existing `documenso.templates`). Every Documenso setting now flows through the registry path that surfaces the env-fallback / port / global source badge per field via `/api/v1/admin/settings/resolved`. EOI generation card retitled to "Templates & signing pathway" since `documenso.templates` covers EOI + reservation + contract template IDs.
> - **InterestDocumentsTab label clarity** — _src/components/interests/interest-documents-tab.tsx_ — the tab has two sections: "Legal documents" (Documenso envelopes — EOI / Reservation / Contract, signature-driven) and "Attachments" (general file uploads). "Legal documents" is misleading — the section is scoped to _signature envelopes_, not any legal doc. A rep uploading externally-signed PDFs (lawyer-prepared addenda, etc.) currently goes into Attachments — fine, but the label gap suggests reps expect "Legal documents" to accept external uploads too. Two paths: (a) rename "Legal documents" → "Signature documents" (or "Contracts & EOI") to scope it correctly, OR (b) allow external uploads into that section (more disruptive — needs file-classification metadata). ~15 min for rename + tooltip; ~2 h for upload route. **SHIPPED (a) in 552b966:** section heading renamed to "Signature documents".
> - **Berth recommender: drop the "Tier X" prefix, keep plain-English label + add tooltip** — _src/components/interests/berth-recommender-panel.tsx:181_ (the pill render) and _:94-99_ (`TIER_LABELS` map) — the pill currently renders `Tier A · Open` / `Tier B · Fall-through` / `Tier C · Active interest` / `Tier D · Late stage`. The four tier letters are internal taxonomy from `berth-recommender.service.ts` (A = never had interest, B = past fall-through, C = active interest, D = active in late stage); reps don't speak in tier letters and the suffix label already carries the meaning. Fix: (1) drop the `Tier {rec.tier} · ` prefix in the rendered pill — show just `tier.label` (e.g. "Open" / "Fall-through" / "Active interest" / "Late stage") so the chip is self-explanatory. (2) Wrap the pill in a `Popover` (click) or `Tooltip` (hover) that explains the four-state ladder in plain English: "Recommender state — **Open**: never had interest. **Fall-through**: prior interest didn't close (warm). **Active interest**: another deal is in play. **Late stage**: another deal is near-sold." (3) Optional: a small `?` icon next to the chip so the tooltip is discoverable without hovering. The internal `Tier` type stays as-is in the service (it has semantic value in the SQL ladder + admin settings); only the UI label changes. ~15 min. Captured 2026-05-18 from UAT. **SHIPPED in 203f543:** pill is now a Popover trigger with the plain-English label + HelpCircle icon; popover content explains the 4-state ladder.
> - **ChartCard: center the chart vertically when grid row is taller than the chart** — _src/components/dashboard/chart-card.tsx_ — every chart widget (`pipeline-funnel`, `occupancy-timeline`, `lead-source`, `berth-status`, `source-conversion`, …) wraps a fixed-height `ResponsiveContainer` (240-280px) inside `ChartCard`. The Card is `h-full` (stretches to its grid-row height) but the inner content keeps its 240-280px and pins to the top — when a neighbour card in the same row is taller (e.g. Pipeline Value with its full per-stage breakdown), the chart card has visible empty space below the chart. Fix: convert `ChartCard` to a flex-column (`<Card className="h-full flex flex-col">`); `CardHeader` keeps natural height; `CardContent` gets `flex-1 flex items-center` so the chart's wrapping div sits vertically centered in the remaining space. ResponsiveContainer stays at its declared fixed height. Affects all chart widgets via one wrapper change — no per-chart edits. ~10 min. Captured 2026-05-18 from UAT. **SHIPPED in 203f543.**
@@ -98,7 +98,7 @@ _Copy tweaks, alignment, single-prop edits, obvious typos._
> - **Render order change in interest-tabs.tsx:** lift the PaymentsSection mount from its current position (line 846-852, above milestones) to AFTER the milestone strip + AFTER the OverviewTab grid (below "Latest note", Tags, Berth requirements). It becomes the last visual element on the OverviewTab.
> - **Collapse state:** persist per-interest via Zustand or react-query cache (so re-opening the same deal remembers the rep's last expand/collapse). Default collapsed unless a deposit was added in this session.
> - **Effort:** ~1-1.5h (layout reorder + collapsed-bar state + summary chip + render-order verification). Captured 2026-05-21 from UAT. **SHIPPED (layout reorder) in f39f0aa:** PaymentsSection moved below milestones (was above). Collapsed-bar + summary-chip refinement parked.
> - **WatchersCard empty state missing bottom padding** — _src/components/documents/document-detail.tsx:546_ — `<p className="text-xs text-muted-foreground">No one is watching this document yet.</p>` has no margin while the sibling populated `<ul>` at line 548 has `mb-3 space-y-1`. Empty state text sits flush against the add-watcher form below. Add `mb-3` to the empty-state `<p>` to match. ~30s. Captured 2026-05-21 from UAT. **SHIPPED in 52342ee.**
> - **WatchersCard empty state missing bottom padding** — _src/components/documents/document-detail.tsx:546_ — `<p className="text-xs text-muted-foreground">No one is watching this document yet.</p>` has no margin while the sibling populated `<ul>` at line 548 has `mb-3 space-y-1`. Empty state text sits flush against the add-watcher form below. Add `mb-3` to the empty-state `<p>` to match. ~30s. Captured 2026-05-21 from UAT. **SHIPPED in 52342ee.** Further bumped to `mb-4 pb-1` in **e33313b** after a follow-up UAT noted the lines still read tight.
> - **DocumentDetail Interest link should show berth(s), not duplicate the client name** — _src/components/documents/document-detail.tsx:96 (type) + 237-241 (linked-entity row builder)_ + the document-detail API service that hydrates `linked.interest`. Today renders `Client: Matthew Ciaccio · Interest: Matthew Ciaccio` — visually redundant, and the Interest link carries no distinct information. Should be `Client: Matthew Ciaccio · Interest: A1-A3, B5-B7` (berth range via the existing `formatBerthRange()` helper from `src/lib/templates/berth-range.ts`, same idiom as the locked folder-naming convention and the external-EOI default title).
> - **Backend:** swap the response payload's `interest: { id, clientName }` → `interest: { id, berthLabel }` where `berthLabel` is derived in the service layer from the interest's primary or in-bundle berths. Falls back to "No berths linked" when no berths are attached.
> - **Frontend:** change line 241 from `sub: linked.interest.clientName` → `sub: linked.interest.berthLabel ?? 'No berths linked'`.
@@ -307,7 +307,7 @@ _Component refactors, multi-file edits, single-service tweaks, new validators._
> - **YachtPicker: selected yacht renders as `Yacht <uuid-prefix>` when not in the autocomplete results** — _src/components/yachts/yacht-picker.tsx:75-79_ — the trigger button label is `match?.name ?? `Yacht ${value.slice(0, 8)}``— the fallback fires whenever the currently-selected yacht isn't in`rawOptions`(e.g. picker was opened with a pre-set value from a URL param / parent default and the autocomplete results don't include it, OR the user typed a search that filtered it out). Result: reps see`"Yacht 3bd83076"` instead of the yacht's name.
> - **Fix:** add a second `useQuery` keyed on `['yacht-detail-label', value]` that fetches `/api/v1/yachts/{value}?fields=name` when `value` is set AND not present in `rawOptions`. Use its result as the fallback label in priority order: `match?.name ?? fallbackQuery.data?.name ?? `Yacht ${value.slice(0, 8)}``. Cache hit on repeat opens; tiny request. (b) Also pre-select the currently-managed yacht as the default `value`for any picker rendered in a context where "the current yacht" makes sense — that's a parent-prop concern; this picker handles whatever`value` it's given. (c) Sweep for the same pattern in other pickers (ClientPicker, CompanyPicker, BerthPicker if they exist) — same root cause + same fix shape.
> - **Effort:** ~20 min per picker; ~1h with the sweep. Captured 2026-05-18 from UAT. **SHIPPED (YachtPicker) in 2bcf544:** fallback `useQuery(['yacht-detail-label', value])` against `/api/v1/yachts/{value}` enabled only when value isn't in `rawOptions`. ClientPicker/CompanyPicker sweep deferred until UAT confirms the same pattern needs fixing there.
> - **CommandList (cmdk) inside a Popover: scroll caps short of the bottom — applies to ALL dropdowns using the Command primitive** — _src/components/ui/command.tsx:57-75_ — `CommandList` has `max-h-[300px] overflow-y-auto overscroll-contain` plus a custom wheel handler (lines 68-72) that re-implements scrolling because "native wheel scrolling is intercepted by the focus-scope and never reaches the cmdk list" (per the inline comment). User reports they can scroll a short distance, then the list stops responding before reaching the bottom — and notes this is the case for **every dropdown on the drawer they're looking at**, so it's the shared primitive, not a per-picker bug.
> - **CommandList (cmdk) inside a Popover: scroll caps short of the bottom — applies to ALL dropdowns using the Command primitive** — _src/components/ui/command.tsx:57-75_ — `CommandList` has `max-h-[300px] overflow-y-auto overscroll-contain` plus a custom wheel handler (lines 68-72) that re-implements scrolling because "native wheel scrolling is intercepted by the focus-scope and never reaches the cmdk list" (per the inline comment). User reports they can scroll a short distance, then the list stops responding before reaching the bottom — and notes this is the case for **every dropdown on the drawer they're looking at**, so it's the shared primitive, not a per-picker bug. **SHIPPED in e33313b:** `max-h-[300px]` now `max-h-[min(300px,var(--radix-popover-content-available-height,300px))]` so the cmdk list never extends past the host Popover's available area. Non-Popover hosts fall through to the 300px static cap. The list now consistently reaches the bottom of the visible popover regardless of where the trigger sits in the viewport.
> - **Suspected causes (likely a combination):**
> - **(i) cmdk auto-scroll-to-highlighted-item** fights the manual scroll: when the user wheels past the currently-highlighted item, cmdk's internal handler snaps the scroll back so the highlighted item stays visible. Net effect: user can scroll up to a few items past the highlight, then it bounces back. **Fix attempt:** on wheel/scroll, clear the cmdk highlight (or set it to a non-highlighted state) so cmdk doesn't re-snap. cmdk exposes a `value` prop on `Command` for controlled-highlight; set it to `undefined` on scroll, restore on hover/keyboard nav.
> - **(ii) Manual wheel handler ignores trackpad-momentum + keyboard:** `event.currentTarget.scrollTop += event.deltaY` only handles wheel events. Trackpad-flick momentum continues firing wheel events with diminishing `deltaY`, but if cmdk traps the events the user's input bounces. Touch / keyboard arrow keys may have similar interception issues. **Fix attempt:** prefer letting cmdk handle scroll natively (newer cmdk versions fixed the popover-focus-scope issue) and remove the manual handler. Check `package.json` for `cmdk` version; if < 1.0.0, upgrade.
@@ -421,6 +421,7 @@ _Component refactors, multi-file edits, single-service tweaks, new validators._
> - **Target length:** ~60-70% reduction. Reads in 30 seconds instead of 3 minutes; the rep gets the workflow, not a friendly essay.
> - **Companion audit:** flag for review across other guide / help / empty-state copy that may have drifted into the same warm-blog voice (consumers of `src/components/shared/empty-state.tsx`, any `*-guide.tsx` pages, onboarding flows, longer Toast copy). One pass for tone consistency platform-wide — captured as a deferred follow-up; this page is the most visible offender.
> - **Effort:** ~45 min for this page; ~3-4h for the platform-wide tone audit if pursued. Captured 2026-05-18 from UAT.
> - **SHIPPED in e33313b:** page rewritten to terse luxury-CRM voice. PageHeader description, "What it does" section, Step 1 ("Install the scanner"), Step 2 ("Capture a receipt"), best-practices list, and PlatformBlock trailing line all tightened. Dropped the OCR mini-essay, "fancy phone camera" / "No typing. No spreadsheets" pleasantries, and parenthetical asides. ~50% size reduction in body copy. Platform-wide tone audit still parked.
> - **Expenses page header copy: drop "port" from the description** — _src/app/(dashboard)/[portSlug]/expenses/page.tsx:33_ → PageHeader at _src/components/shared/page-header.tsx:38_ — description currently reads `"Track and manage port expenses"`; user wants the word `"port"` removed. Suggested copy: `"Track and manage expenses."` (or, if the team wants to keep the "manage" verb spelled out, `"Track and manage business expenses."`). Trivially small. ~30 sec. Captured 2026-05-18 from UAT — likely indicative of a broader "remove the word 'port' from user-facing copy where it's redundant" pass; the portSlug already scopes everything, so user-facing strings shouldn't restate it. Worth a quick grep for `port expenses`, `port clients`, `port settings`, etc. in component strings. **SHIPPED in c6dcf49:** "port" dropped. Platform-wide grep sweep deferred to follow-up.
> - **Topbar search: widen + center against the _viewport_ (including sidebar space), not the topbar's middle grid slot** — _src/components/layout/topbar.tsx:57_ (grid template) + _src/components/layout/topbar.tsx:77-84_ (search container) + _src/components/search/command-search.tsx:103_ (the input itself) + _src/app/globals.css:114_ (`--width-sidebar: 256px` token already available) — current behaviour: the topbar uses `grid grid-cols-[minmax(0,1fr)_minmax(360px,640px)_minmax(0,1fr)]` inside the AppShell's main area (right of the sidebar), so the search bar centers within _the topbar_ — visually it sits offset to the right of the screen by half the sidebar width because the topbar itself starts after the sidebar. User wants the search visually centered against the full viewport (sidebar inclusive) and wider.
> - **Two coordinated changes:**
@@ -431,7 +432,7 @@ _Component refactors, multi-file edits, single-service tweaks, new validators._
> - **Mobile (< sm):** the sidebar is hidden and the layout is different (`MobileLayoutProvider` with bottom-tabs); the transform should only apply on `sm:` and up. Use `sm:-translate-x-[calc(var(--current-sidebar-width)/2)]`.
> - **Left column doesn't get visually overlapped:** since the search shifts via transform (paint-only, doesn't affect layout flow), the breadcrumbs in the left grid slot retain their declared width — but the search will visually overlap them. Solution: reduce the breadcrumbs slot's effective width (e.g. `minmax(0,0.6fr)` instead of `1fr`) OR add `pointer-events: none` to the breadcrumbs when the search is focused. Easier: hide breadcrumbs on narrower laptop widths and rely on the back-chevron + page-h1 for context (also addresses the breadcrumb-wrap finding above).
> - **Effort:** ~30-45 min total — the `--current-sidebar-width` variable + the transform + the grid bump + verifying behaviour at collapsed/expanded/mobile. Captured 2026-05-18 from UAT. **SHIPPED in 8fcbe45:** grid middle slot bumped from `minmax(360,640)` → `minmax(420,800)`; search wrapper `max-w-md` → `max-w-2xl`; `sm:-translate-x-[calc(var(--width-sidebar)/2)]` centers against the full viewport. Collapsed-sidebar-aware `--current-sidebar-width` variable parked.
> - **Pageviews chart: X-axis date ticks too cramped — drop the time component** — _src/components/website-analytics/pageviews-chart.tsx_ (recharts `XAxis`) — current bucket labels render in `YYYY-MM-DD HH:MM:SS` format from Umami's `x` field, which the chart's X-axis prints verbatim. On a 30-day range the labels overlap into an unreadable strip. Fix: pass a `tickFormatter` to `XAxis` that parses `row.x` and renders just the date portion (`MMM d` or `M/d`), keeping the timestamp available via Tooltip's full-precision render. ~10 min. Captured 2026-05-18 from UAT.
> - **Pageviews chart: X-axis date ticks too cramped — drop the time component** — _src/components/website-analytics/pageviews-chart.tsx_ (recharts `XAxis`) — current bucket labels render in `YYYY-MM-DD HH:MM:SS` format from Umami's `x` field, which the chart's X-axis prints verbatim. On a 30-day range the labels overlap into an unreadable strip. Fix: pass a `tickFormatter` to `XAxis` that parses `row.x` and renders just the date portion (`MMM d` or `M/d`), keeping the timestamp available via Tooltip's full-precision render. ~10 min. Captured 2026-05-18 from UAT. **SHIPPED (formatter) earlier (already in place as "MM-DD"); thinning in e33313b:** added `interval="preserveStartEnd"` + `minTickGap={52}` to `XAxis` so multi-week ranges anchor first/last ticks and Recharts thins out the middle automatically instead of overlapping.
> - **Pageviews chart: inline note explaining Pageviews vs Sessions** — _src/components/website-analytics/pageviews-chart.tsx_ + the Card's CardHeader subtitle slot — add a small `?` info popover (matching the pattern on the Pipeline Value tile) next to the chart title that explains: "Pageviews = total page hits including refreshes. Sessions = distinct visitor sessions (a single visitor browsing multiple pages = 1 session, many pageviews)." Helpful because the chart shows both series and the distinction is non-obvious. ~10 min. Captured 2026-05-18 from UAT.
> - **Inbox page: swap section order — Reminders above Alerts** — _src/components/inbox/inbox-page-shell.tsx:84-111_ — current order is `Alerts` (line 84) then `Reminders` (line 99). User wants the order reversed so Reminders is the top section. Swap the two `<section>` blocks; ids (`inbox-section-alerts`, `inbox-section-reminders`), URL-hash deep-link logic, and the localStorage open-state keys all remain untouched (they're keyed on section id, not order). PageHeader copy "Alerts & Reminders" should also flip to "Reminders & Alerts" to mirror the new visual order. ~3 min. Captured 2026-05-18 from UAT. **SHIPPED in 203f543.**
> - **Inbox → Reminders: move filter row inline with the "New Reminder" button (embedded mode)** — _src/components/reminders/reminder-list.tsx:298-315_ — in embedded mode (used by Inbox), the "New Reminder" button renders on its own line at line 298-311 (`<div className="mb-3 flex justify-end">`), and the filters row (My/All tabs + status filter + priority filter) renders separately below at line 315. The two should share one row: filters left, button right. Fix: merge the two into a single `<div className="mb-4 flex flex-wrap items-center gap-3 sm:gap-4">`, keep the filter controls in their current order at the start, and append the "New Reminder" button with `className="ml-auto"` (or wrap the filters in a container + put the button as a sibling and use `justify-between`). Non-embedded mode (PageHeader path at lines 282-297) is unaffected. ~10 min. Captured 2026-05-18 from UAT. **SHIPPED in 203f543.**
@@ -451,10 +452,10 @@ _Component refactors, multi-file edits, single-service tweaks, new validators._
> - **(a) Dock letters are free-form / inferred from `berths.mooring_number`** (no separate `docks` table): then the wizard just needs to allow a new letter prefix in its input. UI fix: replace the letter input (or dropdown) with a combobox-style "pick existing or type a new letter" control — same idiom as Tag picker. Backend: nothing — first insert with the new prefix establishes the dock. ~30 min.
> - **(b) Docks are a first-class entity** (separate `docks` table with `port_id` + `letter` + metadata like `position`, `pontoon_type`, `power_capacity`): then the wizard needs a "+ New dock" affordance opening a small dock-create dialog (letter + name + optional metadata), then returning to the wizard with the new dock pre-selected. Permission: `berths.manage_docks` (or whichever owns dock metadata). The user's question — "_or is this an admin setting?_" — suggests they're not sure either; if it IS an admin-only concern (docks are infrastructure not data the rep should touch), then keep it admin-side and just surface a contextual link in the wizard ("New dock? Add it in Admin → Docks first → [link]"). ~1-2h depending on the model.
> - **Action item:** check whether `docks` / `pontoons` / `marina_sections` table exists in the schema (`grep -r "docks\|pontoons" src/lib/db/schema/`); shape the fix accordingly. If no dedicated table, the wizard fix is trivial; if there is one, decide admin-only vs in-wizard-create with the team. Captured 2026-05-18 from UAT.
> - **DropdownMenu content stretches to fill viewport — cap it** — _src/components/ui/dropdown-menu.tsx:66_ — the shadcn `DropdownMenuContent` primitive uses `max-h-(--radix-dropdown-menu-content-available-height)` (Radix's CSS variable that exposes the room between the trigger and the viewport edge). On long lists the menu visually stretches all the way to the viewport bottom even though the items don't need that height; reads as a wall of options. Internal `overflow-y-auto` is already on so scrolling works. Fix: replace the Radix `max-h-(...)` token with a fixed `max-h-96` (384px) or `max-h-[28rem]` (448px) so the menu caps at a comfortable height regardless of available space, scrolling internally for longer lists. Global change in the base primitive — affects every dropdown in the app, which is the right call (no consumer currently relies on the "fill the viewport" behaviour). ~2 min. If a specific dropdown needs the old behaviour, it can pass `className="max-h-[var(--radix-dropdown-menu-content-available-height)]"` to opt back in. Captured 2026-05-18 from UAT. **SHIPPED in c6dcf49.**
> - **DropdownMenu content stretches to fill viewport — cap it** — _src/components/ui/dropdown-menu.tsx:66_ — the shadcn `DropdownMenuContent` primitive uses `max-h-(--radix-dropdown-menu-content-available-height)` (Radix's CSS variable that exposes the room between the trigger and the viewport edge). On long lists the menu visually stretches all the way to the viewport bottom even though the items don't need that height; reads as a wall of options. Internal `overflow-y-auto` is already on so scrolling works. Fix: replace the Radix `max-h-(...)` token with a fixed `max-h-96` (384px) or `max-h-[28rem]` (448px) so the menu caps at a comfortable height regardless of available space, scrolling internally for longer lists. Global change in the base primitive — affects every dropdown in the app, which is the right call (no consumer currently relies on the "fill the viewport" behaviour). ~2 min. If a specific dropdown needs the old behaviour, it can pass `className="max-h-[var(--radix-dropdown-menu-content-available-height)]"` to opt back in. Captured 2026-05-18 from UAT. **SHIPPED in c6dcf49.** Subsequent tightening in **e33313b:** `max-h-96` now `max-h-[min(24rem,var(--radix-dropdown-menu-content-available-height,24rem))]` so on small viewports the menu caps at the available space (not just the static 24rem) before falling back to internal scroll.
> - **DocumentsHub aside column: flush-left with the app sidebar (kill the AppShell padding for this page)** — _src/components/documents/documents-hub.tsx:246_ + _src/components/layout/app-shell.tsx:113-121_ — the desktop `<main>` wrapper applies `px-6 pt-3 pb-6` to all dashboard pages, so the DocumentsHub two-pane (`ResizablePanelGroup` with the `<aside>` folder column on the left) gets 24px of whitespace between the global app sidebar and its own border. The folder column should sit flush against the app sidebar — it reads as "an extension of the navigation," not "a card inside the page." Fix (surgical): change DocumentsHub's root `<div className="h-full">` at line 246 to `<div className="h-full -mx-6 -mt-3 -mb-6">` (mirror the AppShell desktop padding so the hub renders full-bleed inside the main viewport). Add a comment explaining the intentional escape. The right-pane content keeps its own internal `p-4` so it doesn't run flush with the viewport edge. **Alternative (cleaner long-term):** make the AppShell padding route-aware via a prop on `<main>` (or a layout-level opt-out for hub-style pages); but (a) is the right call until a second page needs the same treatment. ~5 min for the negative-margin fix. Captured 2026-05-18 from UAT. **SHIPPED in 8fcbe45:** `sm:-mx-6 sm:-mt-3 sm:-mb-6` on the wrapper (mobile layout unchanged).
> - **DocumentsHub: hide breadcrumb on root "All documents" view, move PageHeader up to fill the space** — _src/components/documents/documents-hub.tsx:196-209_ — the top row currently always renders the `FolderBreadcrumb` (and conditionally the `NewDocumentMenu` when a folder is selected); on the root view (`selectedFolderId === undefined`) the breadcrumb shows only a "Home / All documents" label with no useful navigation, eating vertical space above the `PageHeader` that already says "Documents" + description. Fix: wrap the entire breadcrumb row at line 196-209 in `{selectedFolderId !== undefined && ( … )}` so the row is gone on the root; the PageHeader becomes the top element. When the rep navigates into a folder, the row reappears with both breadcrumb + NewDocumentMenu (the existing folder views don't render PageHeader, so the breadcrumb is the wayfinding cue). ~5 min. Captured 2026-05-18 from UAT. **SHIPPED in 2bcf544.**
> - **Residential InterestsTab: whole row should navigate to the interest, not just the "View" link** — _src/components/residential/residential-client-tabs.tsx:273-289_ — current `<li>` lays out `[stage chip] [preferences/notes truncated text] [View → link]` and only the "View" text on the right is clickable. The whole row should be a target, matching the idiom used in the main client's `InterestRowItem` (`src/components/clients/client-interests-tab.tsx:53`) — the entire card is a `<button>`/`<Link>` so reps can tap anywhere. Fix: wrap the `<li>`'s flex container in `<Link href={…}>` (`className="block w-full"` to preserve layout), drop the trailing "View" link, add `hover:bg-muted/50` to make the affordance discoverable. ~10 min. Captured 2026-05-18 from UAT. **SHIPPED in c6dcf49.**
> - **Residential InterestsTab: whole row should navigate to the interest, not just the "View" link** — _src/components/residential/residential-client-tabs.tsx:273-289_ — current `<li>` lays out `[stage chip] [preferences/notes truncated text] [View → link]` and only the "View" text on the right is clickable. The whole row should be a target, matching the idiom used in the main client's `InterestRowItem` (`src/components/clients/client-interests-tab.tsx:53`) — the entire card is a `<button>`/`<Link>` so reps can tap anywhere. Fix: wrap the `<li>`'s flex container in `<Link href={…}>` (`className="block w-full"` to preserve layout), drop the trailing "View" link, add `hover:bg-muted/50` to make the affordance discoverable. ~10 min. Captured 2026-05-18 from UAT. **SHIPPED (client-detail tab) in c6dcf49.** **SHIPPED (standalone list page) in e33313b:** `<tr onClick={router.push(...)}>` on `residential-interests-list.tsx`; first-cell `<Link>` stops propagation so middle-click / Cmd-click still opens in a new tab.
> - **Residential namespace breadcrumb link is 404** — _src/components/layout/breadcrumbs.tsx_ (the breadcrumb generator splits the URL and makes every segment a link) + missing _src/app/(dashboard)/[portSlug]/residential/page.tsx_ — on any `/{portSlug}/residential/clients` or `/{portSlug}/residential/interests` page, the breadcrumb renders "Residential" as a link to `/{portSlug}/residential` but no `page.tsx` exists at that path (only `clients/` and `interests/` subdirectories). Clicking the breadcrumb yields a 404. Two reasonable fixes:
> - **(a) Quickest:** create `src/app/(dashboard)/[portSlug]/residential/page.tsx` as a server component that calls `redirect(`/${portSlug}/residential/clients`)`. Single file, ~5 min, breadcrumb works immediately. Same pattern works for any other namespace-only segment that lacks a real landing page.
> - **(b) Cleaner long-term:** add a "namespace" concept to the breadcrumb generator — segments that exist only as URL parents (residential, admin if applicable, …) render as plain text (`<BreadcrumbPage>`) rather than `<BreadcrumbLink>`. Centralized in `breadcrumbs.tsx`'s `SEGMENT_LABELS` map by extending the value to `{ label, namespace?: boolean }`. ~30 min, fixes the class of problem instead of one instance.
@@ -470,6 +471,7 @@ _Component refactors, multi-file edits, single-service tweaks, new validators._
> - **Recommended approach (concise):** Keep the segmented bar exactly as-is (preserves the visual rhythm + works in narrow cards). Render an inline breadcrumb row underneath with one chip per _reached_ stage — chronological left-to-right, last chip = current stage (filled-emphasis using the stage's `STAGE_BADGE` colour), prior chips in the muted variant of the same colour family with a connecting `→`. Pending stages are not labelled (the bar carries that info). Reads as: `Enquiry → Qualified → EOI` for a deal currently in EOI. ~45min.
> - **Alternative (verbose):** Convert `StageStepper` to a true horizontal stepper layout — text label above each tick, current stage bolded, past stages muted, pending stages greyed. More familiar pattern but takes more vertical space and wraps awkwardly on narrow containers (a client card with 4-5 active interests stacks them all). ~1.5h, including a `compact` prop so the hero variant can keep the dense form.
> - **Recommendation:** ship the inline breadcrumb (concise) — solves the "I can't tell what stage this is at without hovering" complaint with minimum visual footprint, and the existing `STAGE_BADGE` colour map provides the per-stage tint for free. Add a `showLabels?: boolean` prop to `StageStepper` so the dense rail-tile variants (`size="xs"`) can opt out. Captured 2026-05-18 from UAT.
> - **SHIPPED in e33313b:** chose the "verbose" stepper variant — stage-name row underneath the bar showing every stage's `STAGE_SHORT_LABELS`. Reached stages render in foreground text; future stages in muted/60 so the rep still sees the ladder ahead. `size="xs"` keeps the dense rail-tile variant intact (no labels row). `STAGE_SHORT_LABELS` re-exported through `pipeline-constants.ts`. Inline-breadcrumb chips variant deferred — the verbose row reads better at the typical container widths we see in practice.
> - **EntityActivityFeed: rewrite per-row rendering to surface _what_ changed** — _src/components/shared/entity-activity-feed.tsx_ (the shared per-entity timeline used on Clients / Yachts / Berths / Residential / Interest detail pages) — each row currently reads `"<actor> updated the <field>"` with the old→new values dropped on a second line, often null or rendered as a truncated JSON dump. Reps can see _something_ changed but not _what_. Several coordinated fixes — pick the subset that's worth doing in one pass:
> - **(a) Bake the value into the sentence line.** Replace `sentence()` (lines 70-77) so when both `fieldChanged` and `newValue` are present the row reads `"<actor> set <field> to <new>"` (with `(was <old>)` appended in muted text on the same line if `oldValue` exists). Eliminates the separate strikethrough line in 80% of cases and reads like a sentence, not a diff. Keeps the separate diff line only for long-form changes (notes body, descriptions) where truncation matters.
> - **(b) Type-aware value formatting beyond the four enums already handled.** `formatValueForField()` (lines 48-66) special-cases `pipelineStage`, `source`, `leadCategory`, `outcome`. Extend with: user-FK fields (`assignedTo`, `ownerId`, `createdBy`) resolved to display names via the same bulk-resolution pattern queued in the actor/diff UUID finding above; berth-FK fields (`berthId`, `primaryBerthId`) resolved to mooring number; yacht-FK / company-FK fields resolved to entity name; date columns (`outcomeAt`, `dueDate`, `startDate`) formatted as `MMM d, yyyy`; currency columns (`price`, `total`) formatted via `formatCurrency` with the row's currency code from `metadata`; boolean toggles rendered "enabled" / "disabled" instead of "true" / "false"; JSON / object values get a one-line summary (e.g. address → `"Address updated: 123 Main St → 456 Elm St"` rather than the JSON dump).