<!-- VORFLUX_AGENT_PR_BODY_BEGIN -->
Adds the full 654-entry MCP directory without bundling records into client JavaScript, with explicit capability status and connector branding that degrades safely when no authoritative logo is available.
## Changes
- Lazy-load and validate the searchable, filterable, progressively rendered MCP catalog.
- Render same-origin proxied provider icons for 543 entries, with a reviewed domain allowlist and deterministic fallback marks for 111 unresolved or unbranded entries.
- Record OAuth discovery capability separately from end-to-end support; all directory setup actions remain suppressed until their authentication flow is verified.
- Add a reproducible OAuth metadata probe with HTTPS/private-network protections, stable URL keys, authorization-server scanning, and catalog fingerprint validation.
- Add Google Drive branding for the curated built-in connector.
## Testing
- **Passed:** Deterministic generation and catalog assertions.
```bash
PATH="$HOME/.bun/bin:$PATH" python3 apps/web/scripts/generate-mcp-directory.py --output
cmp apps/web/public/mcp-directory.json
```
Verified 654 entries, 254 DCR discoveries, 27 preregistered OAuth discoveries, 373 unclassified entries, and zero directory setup actions.
- **Passed:** Stale OAuth metadata fingerprint is rejected by the generator.
- **Passed:** Touched-file Biome checks and `git diff --check`.
- **Passed:** Icon proxy returned 200 for an allowlisted domain and 400 for an unknown valid-looking domain.
- **Passed:** Authenticated desktop/mobile browser inspection and conservative capability labels.
- **Passed:** Public preview returned HTTP 200 and rendered the real app. Authentication cookies do not transfer to the public hostname, so the public screenshot shows login.
- **Partial:** Repository-wide TypeScript checks remain blocked by unrelated existing errors outside the touched MCP files.
- **Partial:** 111 entries intentionally retain deterministic fallback marks; endpoint-derived domains may not always be the canonical brand logo.
- **Blocked:** Google rejected the local HTTP OAuth callback, so live Google Drive consent, callback, persistence, tool discovery, disconnect, and reconnect were not completed.
Public preview: https://ar8ruchhbi65.preview.us1.vorflux.com/configure/tools
---
**Attached Images**
*[288.csv]*
*[mcp-directory-final.json]*
<!-- VORFLUX_AGENT_PR_BODY_END -->
---
**Session Details**
- Session: [View Session](https://supermemory.us1.vorflux.com/agent-sessions/1cd0aab9-2a45-4818-aa13-f9bfe032ddba)
- Requested by: Dhravya Shah (dhravya@supermemory.com)
- Address comments on this PR. Add `(aside)` to your comment to have me ignore it.
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> **Medium Risk**
> Changes how users pick MCP URLs and auth (OAuth vs API key) before hitting existing connect endpoints; no new backend auth logic in this diff, but misconfiguration or trusting bad URLs remains a user-risk surface.
>
> **Overview**
> Adds a **browseable MCP directory** on the Company Brain connectors page: the catalog is **not bundled in JS**—it loads from static **`/mcp-directory.json`** only after the user opens the directory (with validation, caching, and abort handling).
>
> The new **`McpDirectoryBrowser`** supports search, category/availability filters, and progressive “show more” rendering. Supported remote entries route into the existing custom MCP flow via **Set up**, which pre-fills name/URL and opens the connector dialog with context-specific copy.
>
> The custom connector dialog now uses an explicit **OAuth vs API key** toggle; API key fields only appear for API-key mode, and directory-backed connections get **stable slugs** (`-dir-` suffix) so names display cleanly on connected cards. **Middleware** excludes `mcp-directory.json` from the auth matcher so the asset can be fetched publicly.
>
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 8b59bae84a. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
Configure sections were local useState, so they could not be linked or bookmarked and always opened on the default section. Each section is now a route (/configure, /configure/models, /configure/workspace-prompt, /configure/proactivity, /configure/automations), mirroring the existing /integrations/[card] pattern. The shell renders from the segment layout so switching sections does not remount the app, and legacy /?view=configure links forward to /configure.
Fixes ENG-1140
## What changed
- Make `/brain` reuse the active Company Brain, switch to a single existing Company Brain, show a picker for multiple choices, or create one only when none exists.
- Wait for active-organization restoration before making that decision.
- Make Company Brain onboarding match organizations by the confirmed company domain and never offer unrelated-domain workspaces.
- Create a new Company Brain when no matching workspace exists and show an actionable workspace-limit toast when creation is blocked.
- Improve the organization picker, loading, and error states.
## Why
The previous flows could use or mutate the currently active normal organization, start research against stale Company Brain metadata, or offer unrelated Company Brain workspaces after a quota failure.
## Impact
Normal organizations are no longer silently converted. Research is scoped to the Company Brain for the confirmed domain, and users receive a clear recovery path when they reach their workspace limit.
This keeps the existing `{ domain }` research API contract; no organization-reconfiguration API is required.
## Validation
- Biome checks passed for all five changed web files
- Targeted web TypeScript diagnostics reported no errors for the changed files
- React Doctor against `origin/main`: no issues found
- `git diff --check`
No test files were added.
Adds a dismissible Company Brain card to the dashboard header slot and a permanent entry in the profile menu for users whose org has no company brain, both linking to team onboarding.
Onboarding now honours ?mode=team so a personal-domain email arriving from those CTAs isn't routed to personal onboarding.
Fixes ENG-1132
- Drop the company-brain-beta PostHog flag gate; Team mode is available to all users.
- Remove the invite-only gate card and the effectiveMode downgrade that silently wrote brainMode: "personal" on team signups.
- Add a "Use a personal workspace instead" link to the domain-confirm step, which had no way back once the gate stopped catching users.
Fixes ENG-1106
## Summary
- Documents that mono attaches Scale 14d trial + Company Brain after Slack OAuth from `/brain`.
Stacks on #1310. Billing implementation is in mono.
New /brain route creates the org straight from signup and redirects into the Slack install, so onboarding has no domain-confirmation step. Returning from OAuth shows an Open Slack handoff instead of a toast.
Also models the terminal research error state: polling stops, the UI retries once, and the docked header no longer gates Continue on research finishing.
- Confirm-domain step, then live research transcript + action rail
- Poll research status; client-side force-start fallback
---
**Session Details**
- Session: [View Session](https://supermemory.us1.vorflux.com/agent-sessions/4f4c1321-9b65-4dac-9906-8b78c4c32926)
- Requested by: Unknown
- Address comments on this PR. Add `(aside)` to your comment to have me ignore it.
- onboarding: unified About step, mode-aware Sources, Slack-focused Flows step, connect feedback (toast + connected state), auto-draft company description from domain
- brain-home: Active members stat + invite, real OneDrive icon
- useConnectorAccess hook so company_brain unlocks pro-tier connectors across onboarding + integrations
- fix company-brain-connections crash on empty connections
---
**Session Details**
- Session: [View Session](https://supermemory.us1.vorflux.com/agent-sessions/64a15b29-0848-42d1-af4c-138c5a27136f)
- Requested by: Unknown
- Address comments on this PR. Add `(aside)` to your comment to have me ignore it.
## Summary
- Fix delete-organization dialog focus when switching orgs inside Settings.
- Restyle delete-organization modal to match the app modal theme and remove extra organization icons.
- Make the organization switcher list scrollable when many orgs exist.
- Send Create organization directly to onboarding instead of opening the create-org modal.
- Stop onboarding from completing when org creation fails, show an error toast, and return existing users to the dashboard.
- Promote integrations from ?view=integrations to real /integrations and nested /integrations/[card] routes; the page body is shared via AppExperience and useViewMode is path-aware.
- Legacy ?view= URLs (and /settings/integrations) redirect to the new routes for back-compat; middleware/ensure-workspace allow the public routes.
- Add ?connect=<plugin|provider> deeplink that opens a card's connect modal instantly with a loading state (e.g. Hermes API key).
New /org/invite/[invitationId] page so consumer-org invitees can view and accept or decline invitations in the app instead of the console.
Fixes ENG-811
Settings 'create organization' now routes to /onboarding?new=1&name=... (team/personal, invites) instead of a bare authClient.create. Adds the forceCreate path with name prefill, clears new=1 after a successful create to prevent duplicate orgs, and fixes the Radix popover-to-dialog pointer-events lock.
Wire PostHog funnel events (started, step viewed/completed, mode, workspace, sources, ingest, team, completed) across the brain onboarding flow, and drop stale pre-brain event defs from analytics.ts.
---
**Session Details**
- Session: [View Session](https://supermemory.us1.vorflux.com/agent-sessions/5b48bbe4-422a-4577-b6bf-fd9416a6846b)
- Requested by: Sreeram Sreedhar (sreeram@supermemory.com)
- Address comments on this PR. Add `(aside)` to your comment to have me ignore it.
### TL;DR
Adds a Weekly Digests view to the web app, allowing users to browse and read their personalized weekly memory recaps directly in the UI, along with a notification preference toggle to opt out of digest emails.
### What changed?
- Added a new `digests` view mode that renders a `DigestsView` component, accessible from the dashboard via a new weekly digest preview card that appears when a digest exists.
- `DigestsView` displays a master-detail layout: a scrollable list of past weekly digests on the left, and a full digest content pane on the right. The detail pane renders the intro (with a floating brain illustration), numbered highlights, and feature recommendations styled to mirror the email layout.
- Added thumbs-up/thumbs-down feedback controls and an optional free-text input on each digest, wired to analytics events.
- Added `useDigests` and `useDigest` hooks that fetch digest list and detail data from the API, with 5- and 10-minute stale times respectively.
- Registered four new API schema endpoints: `GET /digests`, `GET /digests/:id`, `GET /digests/preferences`, and `POST /digests/preferences`.
- Added a `DigestPreferences` section to the account settings page with a toggle that lets users opt in or out of the weekly digest email.
- Extended the `viewModeChanged` analytics event and the `viewLiterals` search param list to include `"digests"`, and added `digestViewed`, `digestFeedback`, and `digestFeedbackDetail` analytics events.
- Added documentation for the `SUPERMEMORY_EMBEDDING_RAM_LIMIT` and `SUPERMEMORY_INGEST_CONCURRENCY` environment variables, explaining the memory-bounded ingestion queue and its live terminal status output.
### How to test?
1. Navigate to the dashboard and confirm the weekly digest preview card appears when a digest exists, and clicking it transitions to the `digests` view.
2. In the digests view, verify the list renders past digests with the most recent highlighted by a gradient border, and selecting a row loads the correct detail content.
3. Confirm the empty state renders correctly when no digests exist.
4. Use the thumbs-up/thumbs-down buttons and the detailed feedback textarea on a digest, verifying the toast confirmation appears on submission.
5. Open account settings, locate the "Notifications" section, and toggle the weekly digest switch on and off, verifying the preference persists without errors.
6. Confirm the `digests` view mode is reflected in the URL search params when active.
### Why make this change?
Users currently receive weekly digest emails but have no way to revisit past digests within the app. This change surfaces digest history directly in the UI, adds in-product feedback collection on digest quality, and gives users control over whether they receive the emails — improving discoverability, engagement, and preference management.
Consent + connect UI for the new OAuth 2.1 provider. The API side lives in mono#1812 (stacked on the Enterprise MCP PR). When an MCP client starts OAuth, this is the page where you pick the org and approve access.
What's here:
- `/oauth/consent`: the consent screen. Pick an organization (cards), then set access: permission (read / read+write) and scope (full, or scoped to specific container-tag spaces with a searchable picker). Approving hands the code back to the client.
- `/connect`: plugin-aware entry for known clients (Claude Code, etc.).
- `ConsentCard.tsx`: shared card component (org list with fade, dual-icon connecting header, scoped-spaces picker), built to reuse across plugins.
- plus a fix to the mcp resource metadata.
Pairs with mono#1812 (the API OAuth provider) and the Enterprise MCP PR. Draft until the end-to-end flow is verified.
Fixes the onboarding source-integrations step: corrects connector behavior, applies plan-based gating to connectors, and polishes the integrations layout.
## Summary
- Allow logged-out users to load `/?view=integrations` without being redirected to login
- Add a public integrations header with Supermemory branding and a login CTA
- Run IntegrationsView in guest mode with static catalog data only, no auth-backed queries
- Route all guest Connect actions to login with a redirect back to the integrations page
<img width="1680" height="1009" alt="Screenshot 2026-06-09 at 9 32 33 PM" src="https://github.com/user-attachments/assets/111f2b1a-5224-47ae-8152-e1349c05842d" />
feat(web): make brain onboarding the default flow
- Replace legacy /onboarding with the brain onboarding flow (about -> sources -> ingest -> team -> done)
- Add brain-home dashboard page and widgets
- Old /onboarding/brain deep links fall through to the existing catch-all redirect
feat(onboarding): create org on About step + remove skip
- Create the organization on About -> Continue (authClient.organization.create + setActiveOrg), persisting brain context to org metadata; fixes the no-org redirect loop
- Show a Creating… state on Continue while the org is created
- Remove Skip on the required About step (name + workspace)
- Add generateOrgSlug/generateUsername helpers to onboarding-brain/types
- Added attachment draft/shared types and validation in components/chat/attachments.ts.
- Added paperclip upload UI to Nova composer with file chips, size/status, remove, retry, and per-file Save / Chat only toggle.
- Wired uploads before send to /chat/attachments, then sends returned attachment references in chat message metadata.
- Preserved attachment metadata when loading threads and rendered attachment chips on user messages.
- Added attachment support from the home composer into the full chat view.
- Extended chat analytics with attachment counts.
<img width="1905" height="900" alt="image" src="https://github.com/user-attachments/assets/631001b8-7c68-4015-b36b-06c69cdad271" />
<img width="1323" height="1600" alt="image" src="https://github.com/user-attachments/assets/77eee08a-b235-41eb-b03a-f406b81b46e7" />
- ensured responsiveness
Integrate the new api_max plan ($100/mo, $130 credits) from mono into the
nova web app, mirroring mono's tier semantics.
- Tiers: insert api_max between pro and scale; resolves to Pro-tier for feature gates while displaying as "Max" (queries.ts, use-token-usage)
- Billing page: Max plan card ("Most Popular"), checkout/cancel/invoice wiring; advanced carousel page now 3-up (Max/Scale/Enterprise); Scale builds on Max
- Carousel auto-opens to the page holding the current plan (Max/Scale/ Enterprise users land on their own card instead of Free+Pro)
- Cancel: retention dialog listing what you lose + type-to-confirm "CANCEL"
- Cancel/resume state mirroring console: detect canceledAt-scheduled cancellation, show "Cancelling" pill + "Cancels on {date} · N days left", and a "Resume plan" (uncancel) action
The onboarding rework moved the flow to app/(app)/onboarding and dropped the funnel tracking, so onboarding_completed stopped firing on 2026-05-02.
- Wire onboarding_step_viewed across idle/processing/done/error transitions
- Fire onboarding_completed on real completion (status=done) with source + memories_count
- onboarding_profile_submitted now carries { source }
- Add onboarding_skipped { from_step }
- Remove dead onboardingCompleted() from InitialHeader and unused name/relatable helpers
- Rebuild the integrations catalog as horizontally-scrollable category rails
(MCP, Plugins, Knowledge bases, Apps & extensions) with header chevrons
- Add an auto-rotating Featured hero with problem-led headlines, backdrop
imagery and a gradient FEATURED badge
- Surface all 9 MCP clients as individual cards that open a setup modal
styled like the plugin connect flow (reuses MCPSteps embedded variant)
- Align MCP setup steps and the Claude Desktop timeline to the design system
- Merge the Integrations and Connections settings tabs into one entry
Consolidate login routes, add animated tool context visualization on the hero panel, and polish loading states across onboarding, settings, and workspace bootstrap.
- Replace the top-left logo menu with an org switcher (Switch brain): lists organizations with avatar monograms, brand-blue active row, and the active org name (sans "Organization") shown above the supermemory wordmark.
- Switching an org persists the active org and reloads so all data re-scopes.
- Show each org's plan badge in the switcher, reusing the account settings badge (extracted OrgPlanBadge + resolveOrgPlan to a shared component).
- Match the profile dropdown to the same design (rows, hover/focus, border).
- Remove the 'Be part of the next supermemory app' research CTA card.
- Add hideCount prop to SpaceSelector; hide the space count in chat input.
The home dashboard suggestion cards routed Notion/Google Drive clicks through setViewMode("notion"|"google-drive"), but those values aren't in viewLiterals, so nuqs rejected them and silently fell back to the dashboard view — the click did nothing.
Route those two providers to the connect modal (setAddDoc("connect")), matching the Integrations 'Connections' card, and widen IntegrationParamValue to include them.
Pairs with the API change that populates sourceDocumentId. The dashboard reads memory-of-day from localStorage first, so without a cache-key bump users would keep seeing the stale null-sourceDocument response for the rest of today. Bumping to :v2: forces a refetch on next load.
- Fix `authClient.apiKey.create()` returning undefined: better-auth resolves to `{ data, error }`, not the key directly. Use `res.data.key` (with `res.error` handling) in both `RaycastDetail` and `settings/integrations.tsx`.
- Extract `RaycastSetupModal` and reuse it across the nova home Raycast card and the Settings → Integrations Raycast modal. The new modal matches the plugins-connect design system (icon box, pill close, inset card with shared `InstallSteps`, install pill).
- Add `/settings/integrations` redirect page so `app.supermemory.ai/settings/integrations?q=raycast` lands on the Integrations tab and auto-opens the Raycast modal (the `?q=raycast` auto-trigger logic already existed; the route was the missing piece).
## Summary
Changes the highlight "Chat" button behavior:
- **Before**: Clicking "Chat" immediately opened the chat view with "Tell me more about XYZ" sent as the user's first message
- **After**: Clicking "Chat" reveals an inline reply input right under the highlight card. The user types their response, and when they submit:
- The highlight content appears as the **assistant's first message** (prefixed with "Here is a highlight from your memories:")
- The user's reply appears as the second message
- A fresh chat thread is created (no overwriting existing conversations)
### Files Changed
- **`apps/web/components/highlights-card.tsx`** - Added inline reply input UI with send/cancel buttons, keyboard handling (Enter/Escape), auto-focus, and state reset on item navigation or items refresh
- **`apps/web/components/chat/index.tsx`** - Added `queuedHighlightContent` prop, fresh thread creation for highlight chats, deferred `setMessages` to ensure correct Chat instance targeting, and `awaitingHighlightInjectionRef` for safe reply dispatch
- **`apps/web/app/(app)/page.tsx`** - Added `queuedHighlightContent` state, updated `handleHighlightsChat` to accept highlight content + user reply, cleared stale highlight content in `handleHomeChatStart`
- **`apps/web/components/dashboard-view.tsx`** - Updated `onHighlightsChat` type signature
- **`apps/web/components/memories-grid.tsx`** - Updated `HighlightsProps.onChat` type signature
## Testing
### TypeScript
- `npx tsc --noEmit` — no new type errors (all errors are pre-existing in unrelated files)
### Biome
- `bunx biome check --write` — clean on all changed files (pre-existing warnings only in dashboard-view.tsx)
### Automated Tests (via testing subagent)
- **25 passed / 0 failed / 1 skipped** (26 total)
- Tests covered: inline reply input visibility, keyboard handling (Enter/Escape), reply state reset on navigation, highlight content injection as assistant message, user reply dispatch, fresh thread creation, stale highlight content prevention, pagination dot handler
- The testing agent discovered and fixed a race condition where `setMessages` was called before `useChat` had recreated its internal Chat object after `setFallbackChatId` — the fix defers `setMessages` to a separate effect gated on `currentChatId` matching the target
- 1 test skipped (T12): Nova FAB button not separately visible from highlights card button at 1440px viewport — expected structural behavior
---
**Session Details**
- Session: [View Session](https://supermemory.us1.vorflux.com/agent-sessions/9cbf2106-b7b9-4d7c-b275-2a7e72417793)
- Requested by: Soham Daga (soham@supermemory.com)
- Address comments on this PR. Add `(aside)` to your comment to have me ignore it.
## Summary
Addresses user feedback about the graph view: content in node popovers was hard-truncated at 100 characters with no way to read the full text or navigate to the document.
### Changes
**Scrollable popover content (no more truncation)**
- Removed the `truncate(content, 100)` call -- full content is now rendered in the popover
- Made the content area scrollable with `maxHeight: 100px` and `overflowY: auto`
- Increased version timeline entry truncation from 60 to 120 characters
- Increased version timeline container height from 120px to 160px
**"View document" in shortcuts panel**
- Added an eye icon + "View document" entry to the shortcuts panel (alongside existing arrow navigation)
- Clicking opens the Document Modal for the corresponding document
- Works for both document nodes (opens that document) and memory nodes (opens the parent document)
- Popover is automatically dismissed before the modal opens (prevents z-index overlap)
- Wired `onOpenDocument` callback through the full component chain: `page.tsx` -> `GraphLayoutView` -> `MemoryGraph` wrapper -> `MemoryGraphBase` -> `NodeHoverPopover`
**Shortcuts panel visual cleanup**
- Icon badges (`KeyBadge`) retain dark background and border for a keyboard-key badge look
- All icons (including the new EyeIcon) are uniformly wrapped in `KeyBadge` for consistent styling
- Removed background, border, and border-radius from the shortcuts panel container itself
- Widened shortcuts panel from 100px to 160px so navigation labels are fully visible
**Type safety improvement**
- Changed `MemoryGraphProps.colors` from `GraphThemeColors` to `Partial<GraphThemeColors>` to match actual usage (callers pass partial overrides that get merged with defaults)
- Replaced `as Partial<typeof import(...)>` cast with proper `satisfies Partial<GraphThemeColors>` using a direct type import
### Files changed
- `packages/memory-graph/src/components/node-hover-popover.tsx` -- scrollable content, EyeIcon + "View document" in shortcuts, KeyBadge styling, NavButton icon type broadened to `React.ReactNode`, all icons wrapped in KeyBadge
- `packages/memory-graph/src/components/memory-graph.tsx` -- popover dismissal wrapper (`handleOpenDocument`), prop forwarding
- `packages/memory-graph/src/types.ts` -- `onOpenDocument` prop on `MemoryGraphProps`, `colors` changed to `Partial<GraphThemeColors>`
- `apps/web/components/graph-layout-view.tsx` -- accepts and passes `onOpenDocument`
- `apps/web/components/memory-graph/memory-graph-wrapper.tsx` -- `onOpenDocument` in wrapper props, clean type import
- `apps/web/app/(app)/page.tsx` -- `handleOpenDocumentById` handler, wired to `GraphLayoutView`
## Testing
### Unit Tests (154/154 passed)
- **Command:** `cd packages/memory-graph && bun run test`
- **Result:** 9 test files, 154 tests passed (107 existing + 47 new)
- **New test file:** `packages/memory-graph/src/__tests__/node-hover-popover.test.tsx` covering:
- Layout constants (`SHORTCUTS_W=160`, `CARD_W=280`, `TOTAL_W` formula)
- Content area scrollability (`maxHeight:100`, `overflowY:auto`, `flex:1 1 auto`, no truncation)
- KeyBadge styles (has `backgroundColor: colors.controlBg`, has `border` with `colors.controlBorder`)
- Shortcuts panel styles (no `backgroundColor`, no `border`, no `borderRadius`)
- EyeIcon SVG component (`aria-hidden`, viewBox, path, circle, stroke)
- "View document" button render guard (`onOpenDocument && documentId`)
- `documentId` derivation (memory vs document node)
- VersionTimeline truncation limit (120 chars) and container maxHeight (160)
- `onOpenDocument` prop wiring
- NavButton icon prop type (`React.ReactNode`), all icons wrapped in KeyBadge
- `handleOpenDocument` wrapper in MemoryGraph (dismiss calls, ordering, useCallback deps)
### Build
- **Command:** `bun run --filter=@supermemory/memory-graph build`
- **Result:** Build succeeds, 0 errors
### Lint/Format
- **Command:** `bunx biome ci --changed --since=origin/main --no-errors-on-unmatched`
- **Result:** 6 files checked, no fixes applied, 0 errors
### Type Checking
- `packages/memory-graph`: 0 errors
- `apps/web`: 0 new errors introduced
### CI
- "CI - Type Check, Format & Lint" workflow passes
- "Claude Code Review" workflow fails due to repo config (`non-human actor: vorflux` not in `allowed_bots` list) -- not related to code changes
---
**Session Details**
- Session: [View Session](https://supermemory.us1.vorflux.com/agent-sessions/d0c067f1-38c1-40c5-ada9-b2ffb7331d1c)
- Requested by: Mahesh Sanikommu (mahesh@supermemory.com)
- Address comments on this PR. Add `(aside)` to your comment to have me ignore it.
