Hotel Universe.
The complete user story backlog

app/layout/AppLogin.vue and components/landing/useSignIn.ts both call the scaffold AuthService.login() with authProvider: 'google' from Config; the API side exchanges the code with GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET and fetches userinfo before minting the JWT.

Google is a single point of failure for all human access — an OAuth outage locks out every customer with no fallback credential. Corporate tenants that block third-party Google apps cannot sign in at all, which is a live sales blocker.

app/layout/GoogleAuthCallback.vue takes code, error and state as route props; fragment stripping lives in RouterManager.ts's beforeResolve guard.

A code replayed from browser history or a copied URL will fail exchange, but only after a round trip — the resulting error copy is generic. There is no CSRF check tying state to a value the portal generated and stored.

RouterManager.setRedirectUrl() / goToRedirectUrl(clear = true); /login also accepts redirectUrl as an explicit query prop.

sessionStorage is per-tab, so a sign-in completed in a different tab loses the redirect. The stored URL can point at a route the user's tier cannot reach (e.g. requiresMetasearchAccess), bouncing them to Billing immediately after login.

ApiManager.refreshToken(), ensureValidToken(), startTokenRefreshInterval() / stopTokenRefreshInterval(); the JWT itself is long-lived (JWT_TOKEN_EXPIRATION_SECONDS e.g. 604800 = 7 days).

Several tabs each run their own 5-minute interval and race to write ubio_auth_token; a tab suspended by the browser can wake with a token refreshed elsewhere. Criterion 4 is the weakest part of the current behaviour — see AUTH-10.

ProfileMenu.vue → ApiManager.logout(); AccessManager.clear() drops cached access info.

Client-side state outlives logout: hotel-universe:selected-hotels, hotel-universe:ai-assistant-chat and directPricingActiveBatches are not purged, so a second user on the same browser can see the previous user's selection and assistant transcript. That is a genuine privacy defect worth fixing alongside AUTH-16.

First-login handling in the auth service: create User, process pending invitations by email, then fall through to org creation (AUTH-07). GET /users/me returns {id, email, name, avatarUrl, lastOrganizationId} and, on first sign-up, the initialSignUp flag that triggers the onboarding tour.

Invitation processing at first login is the only place an invite is auto-consumed; if it throws after the user is created, the user exists in a fresh trial org while the invite still shows as pending to the admin who sent it.

Org auto-creation sits in the Google auth flow; the tier ceiling is enforced by AccessTierService counting distinct huId values in the time-series accessLogs collection for action hotels:view.

The org name is derived from the Google profile name, so shared or generic Google names produce confusing org names that only the admin can fix in Settings. The trial hotel count is all-time and never resets, so a long-running evaluation quietly dead-ends.

AccessTokens.vue + ApiManager.getPersonalAccessTokens/createPersonalAccessToken/deletePersonalAccessToken; server-side accessTokens {_id, name, hash, scopes[], createdAt, createdBy, orgId}. The portal also emits access_token_created / token_deleted telemetry.

Non-expiring secrets with no last-used timestamp and no rotation story are the single largest credential risk on the platform; a leaked pat_ in a public repo grants org-wide read of hotels, reviews, metasearch, lists and exports indefinitely. docs/docs.http still documents a non-existent POST /auth/pat, so integrators can start from the wrong endpoint.

users.lastOrganizationId is returned by GET /users/me and updated by POST /auth/switch-org; the portal reads the membership list via GET /users/me/orgs.

Criterion 3 is the fragile one — removal from an org (ORG-07) does not clear other users' lastOrganizationId, so the next sign-in can mint a token for a membership that no longer exists.

The gap is concrete: router.beforeEach awaits access.refreshAccessInfo() and swallows failure, continuing navigation, and there is no central 401 interceptor in ApiManager (3782 lines) — each caller surfaces its own error state or toast.

With a 7-day JWT and a 5-minute refresh loop, expiry mostly bites laptops resumed from sleep — exactly when a user has many tabs open and will hit the failure ten times before understanding it. Swallowed access-info failures can also mask a tier downgrade, showing metasearch UI that then 402s.

Adds POST /auth/register, POST /auth/login, POST /auth/password/reset alongside POST /auth/google, with Argon2id hashes on the users record. Email delivery would extend the SendGrid service, which today sends exactly one message type (sendInvitationEmail).

Password auth drags in verification, reset, lockout and breach-list checks — a real ongoing cost. Account-linking between a Google identity and a password identity on the same address is the classic takeover vector and must be verified-email-gated.

Reuses the invitation-token pattern already in the codebase (/invite/accept?token=), but with proper single-use consumption and short expiry rather than the invitation's 7-day, id-as-token model.

Email forwarding and corporate link-scanners pre-fetch URLs and can burn single-use tokens before the human clicks; a POST-on-confirm interstitial avoids this.

Builds on the existing JWT minting path (JWT_ISSUER, JWT_PRIVATE_KEY) — federation only changes how identity is established. Per-org IdP config would live on organizations alongside tier and billing. Note that app/public/silent-check-sso.html and AC_PUBLIC_ENV_KEYCLOAK_URL are legacy Keycloak leftovers, unused by the Google flow, and should be removed rather than revived.

Domain ownership must be proven (DNS TXT) before an org can claim it, or one tenant can hijack another's users. Users with membership in several orgs need a deterministic rule for which IdP wins.

A /scim/v2/Users and /scim/v2/Groups surface writing to the existing users and organizations collections; depends on RBAC (ORG-12) to make group mapping meaningful, since today every member has identical scopes.

SCIM is only worth building after roles exist — without them, group sync can express nothing. A misconfigured IdP push can mass-remove members; changes should be rate-limited and reversible for a grace period.

Applies to password and magic-link paths; Google and SSO logins inherit the provider's factor. Enforcement flag stored per organisation next to tier.

MFA on the human path does nothing for pat_ tokens, which bypass it entirely — the real credential risk stays with AUTH-08 and AUTH-19 until PATs gain expiry and rotation.

Requires server-side session records (jti plus device metadata) because JWTs are currently stateless and self-validating — revocation needs either a deny list in Redis (already available when REDIS_URL is set for rate limiting) or short-lived tokens per AUTH-19.

Without a deny list, a stolen 7-day JWT stays valid for its full lifetime no matter what the UI claims — the feature must not promise revocation it cannot deliver.

Mirrors the existing accessLogs design — a MongoDB time-series collection with timeField: time, metaField: meta, hourly granularity and a TTL (the data-access log uses one year). Distinct from accessLogs, which records hotels:view / metasearch:view style data access, not authentication.

IP and user-agent capture is personal data under GDPR; retention and access must be documented alongside AUTH-22. High-frequency PAT traffic could dominate the collection — log first-use-per-day per token rather than every request.

Today accessTokens already produces principal.type: serviceAccount with displayName: "PAT <name>", but the record is created by a person under PAT_MANAGE and carries createdBy. This story separates the identity (service account) from the credential (token), and pairs naturally with the landing page's promise of "Scoped API keys — issue read-only tokens per agent or per workspace".

Scope escalation is the main risk; the current PAT scope set is fixed (exports, lists, hotels, reviews, metasearch) rather than chosen, so genuinely read-only agent keys are not yet possible despite being advertised.

Extends accessTokens with expiresAt, lastUsedAt and rotatedFrom; the portal already has the UI column and the one-time-secret dialog to hang this on. Short-lived access tokens make AUTH-16 revocation real without a deny list.

Introducing expiry on existing non-expiring PATs will break live integrations unless grandfathered and announced; treat the first cohort as never-expiring with a loud dashboard warning.

Config.authProvider is already a named setting and the scaffold has an AuthProviderRegistry, so a second provider is a registration plus a callback route rather than an auth rewrite.

Identity linking by email address is only safe when the provider asserts a verified address; Entra guest accounts can present addresses from other tenants.

Would extend GET /billing/subscription ({tier, subscriptions, billing, usage}) with a seat dimension and render through the existing formatSubscriptionUsageLine / formatSubscriptionOverageLine helpers in utils/billingFormatters.ts.

No usage is metered to Stripe today — quotas are computed internally from access logs — so seat billing needs a decision on whether seats are a Stripe quantity or another internally enforced cap. Blocking a join at the limit is a bad first experience; a soft overage line may sell better.

accessLogs records principalId and is a time-series collection with a one-year TTL, so pseudonymisation there needs a rewrite-or-wait decision. Note that HotelReviewExport already strips the reviewer field for PII reasons — the same principle applies to account data.

Erasing a createdBy on lists and tokens can orphan audit trails that other tenants' compliance teams rely on; pseudonymise rather than null out. Stripe customer records are a separate controller relationship and need their own deletion path.

POST /orgs in the API; the same code path is used by first-login auto-creation of "<name>'s Organization" (AUTH-07). The organizations document is {id, name, memberIds[], tier, createdAt, createdBy, updatedAt, billing?}.

There is no portal screen for creating a second organisation — the endpoint exists but the UI only ever surfaces orgs you already belong to, so self-serve multi-tenant setup requires an API call or a support ticket.

app/views/Settings.vue → ApiManager.updateOrganization(orgId, name) → PUT /orgs/{id}, gated server-side by ORGS_MANAGE, which every JWT holds.

Because every member has orgs:manage, any member can rename the org — including a guest invited only to view a list. Renames are not audited, so there is no record of who changed it.

DELETE /orgs/{id} exists in the API but there is no portal UI for it — Settings.vue only offers rename. Criteria 2–4 describe behaviour that is not verified to exist and would need to be confirmed or added.

Deleting an org while another member has a live JWT scoped to it leaves that token pointing at a missing tenancy; deletion should revoke sessions and PATs for the org. Cascade behaviour across lists, listEntries, exports, accessTokens and GCS export objects is the real work here.

Membership is a plain array — organizations.memberIds — with no role or join-date metadata. SettingsMenu.vue and ProfileMenu.vue both render the org Select from ApiManager.getOrganizations().

With no per-org roles, a consultant holds full administrative scope in every client org they join, including the ability to change that client's subscription. That is the single strongest argument for ORG-12.

ApiManager.switchOrganization(orgId) followed by window.location.reload() in SettingsMenu.vue; applyOrganizationFromQuery() / handleStripeRedirect() on Billing.vue; AiAssistantManager resets its sessionStorage state (hotel-universe:ai-assistant-chat, STORAGE_VERSION = 10) on switch.

The full page reload is the named gap: it discards in-flight work, unsaved selections and scroll position, and it makes switching feel like signing in again. Some client state is not org-scoped at all — hotel-universe:selected-hotels holds huIds selected in the previous org.

app/views/Members.vue, reached from SettingsMenu.vue; the members endpoint is gated only by org membership, since the declared orgs:members:view scope is commented out in the permission set.

The list shows no last-active date, no role and no indication of who holds which PATs, so an admin auditing access cannot tell a dormant account from an active one.

Members.vue with $confirm.require, ApiManager.removeMember(orgId, memberId), and a member_removed telemetry event.

Criterion 4 is the weak one: the removed user's existing JWT stays valid until it expires (up to 7 days) and any PAT they created remains active and org-scoped, so removal is not immediate revocation. This is the clearest dependency on AUTH-16 and AUTH-19.

Members.vue invite modal → ApiManager.inviteUser(email); server-side sendInvitationEmail is the only email type the platform sends, with support@ubio.ai in the footer. Emits member_invited telemetry.

The invitation is gated by the wrong scope (see ORG-11), and its id doubles as the acceptance token, so the identifier returned by GET /invitations is itself the bearer secret. There is no bounce handling — a typo'd address fails silently from the admin's point of view.

app/layout/InviteAccept.vue → ApiManager.acceptInvite(token); the route is requiresAuth: false. POST /invitations/{id}/accept is unauthenticated — it is on the API's list of unauthenticated surfaces alongside /scrapers/*, /sources and /img/resize.

Criterion 5 is the gap: the invitation id is guessable-adjacent, single-use semantics are unclear, and an unauthenticated accept endpoint means the URL alone is the credential. A forwarded invitation email grants org membership to the forwardee.

Members.vue pending-invitations table → ApiManager.getInvitations() and deleteInvitation(id), with $confirm.require on cancel.

Expired invitations are not visibly distinguished from fresh ones beyond the status tag, and nothing prunes them, so the table accumulates dead rows on long-lived orgs.

The mis-scoping is documented as a known issue: invitations are gated by LISTS_MANAGE. The consequence today is that a PAT — which holds lists:manage but not orgs:manage — can add members to an organisation, which is a privilege-escalation path from a leaked API key to full tenancy access.

Fixing the scope is a one-line change with a real blast radius: any customer automation currently inviting users with a PAT breaks. Announce it, and note that users:manage is declared but never enforced anywhere, so a broader scope audit is warranted at the same time.

Today membership is a flat memberIds[] array and every member receives the identical JWT scope set (orgs:manage, exports:manage, lists:manage, hotels:view, reviews:view, metasearch:view, pat:manage). This story replaces the array with member records carrying a role, and maps roles to those existing scopes plus the currently commented-out orgs:members:manage / orgs:members:view.

Scopes are baked into the JWT at mint time, so a demotion does not take effect until the next refresh — up to 5 minutes, or 7 days if refresh is failing. Migration must default every existing member to a role that does not reduce their access overnight.

Builds directly on the eight declared permissions; the portal already has per-tier capability helpers in utils/accessTier.ts that would gain a per-scope sibling for rendering.

Custom roles multiply the gating matrix already created by tiers (trial/paid/full) and route meta (requiresMetasearchAccess, requiresUbioAccess); without a single evaluation helper the portal will drift out of step with the API.

lists already carry orgId and createdBy and the portal already filters "My lists" versus "All lists" (/lists/my), so a per-list access-control list is an incremental step. Product scoping maps onto the existing BillingProduct split (smartFeed, metasearch, richContent).

Dynamic lists re-run a saved searchQuery, so a restricted member could infer excluded data through search even when list access is denied; search itself would need the same scoping to close that hole.

Hooks the same first-login branch that today auto-creates a trial org, checking a verified-domains list on organizations before falling back. The internal isUbee() check (email contains @ub.io, portal also accepts ubio.ai) is a crude precedent for domain-based membership and should not be extended as-is.

Domain verification is mandatory — without it, one tenant can capture another's users. Auto-join plus flat scopes (ORG-12 unbuilt) means any new starter arrives with full administrative rights, so this should not ship before roles.

Depends on ORG-12 for the concept of an owner; organizations.createdBy is the closest thing today and is never used for authorisation. The expiry pattern can reuse the invitation model's 7-day expiresAt.

Support-initiated transfers need their own audit record and a strong identity check, or they become a social-engineering path into a customer's whole data set.

The data-access side already exists — accessLogs is a time-series collection recording hotels:view, reviews:view, metasearch:view, lists:create, export:create: and export:download:, surfaced on /usage via GET /stats/. This story adds administrative events and a per-org viewer, and the portal already emits close analogues as telemetry (member_invited, member_removed, access_token_created, token_deleted, subscription_cancellation_scheduled) to POST /portal-events.

Portal telemetry is not an audit log — it is client-emitted, best-effort and flushed on a 5-second timer with keepalive, so it can be dropped or forged. Audit entries must be written server-side at the point of the mutation.

Requires ORG-12 (roles) and ORG-14 (per-list scoping) first; the members list would gain a guest section distinguishing full members from time-boxed collaborators.

Guests count towards seat maths (AUTH-21) unless explicitly excluded, and a guest with metasearch view can consume the host org's metasearch allowance — which triggers the metasearch_topup_required 402 for everyone.

Would add a workspace dimension to lists, exports and accessLogs.meta alongside orgId, and a second-level selector in SettingsMenu.vue. The portal's own design guideline — top bar for main sections, left sidebar for the second level, tabs for the third, URLs addressing resources — constrains where the switcher can live.

Adding a tenancy level below the org affects every scoped query and every access-log aggregation; the /stats aggregation is per-org today and would need a workspace group-by. This is the most invasive story in the epic and should follow, not precede, roles.

Reads the plan from GET /billing/subscription and renders through the existing formatSubscriptionUsageLine / formatSubscriptionOverageLine helpers. Pairs with AUTH-21; this story is the org-side enforcement, that one is the sign-in-side provisioning.

All three paid plans currently grant identical access — there is a standing TODO to decide how much to gate on tier — so seat limits would be the first hard plan differentiator and need commercial sign-off before enforcement.

Reuses the CSV machinery already proven for lists: PrimeVue FileUpload (basic, auto, text/csv, 1 MB) and csv-parse with columns: true, plus the 406 UploadListError shape with expected/received detail.

Bulk invitation is a spam vector; rate-limit per org per day and require a verified domain or an established subscription. Extra CSV columns should be ignored, consistent with the list-upload promise "No need to reshape it first".

Extends invitations with lastSentAt and a reminder counter, and adds a second SendGrid template alongside sendInvitationEmail — the platform's only transactional email today. The scrapers package's PeriodicTaskRunner.schedule(task, interval, name) is an existing in-house pattern for the reminder job.

Extending expiresAt on resend means an invitation URL can live far longer than 7 days, widening the window on the unauthenticated accept endpoint (ORG-09). Bounce handling requires configuring SendGrid event webhooks, which do not exist today.

components/.../ProfileMenu.vue in the topbar; version strings come from the __PORTAL_VERSION__ build define and ApiManager.getStatus().

The version footer is the fastest triage tool support has, but it is buried in a menu — when a customer reports a bug there is no copy-diagnostics action to capture portal version, API version, org id and tier in one click.

components/app/DarkModeToggle.vue plus the pre-boot initialiser in app/entrypoint.ts; the safe storage wrappers live in managers/storage/ (LocalStorageManager, getItem/setItem/loadJson/saveJson).

The preference is per-browser, not per-account, so it does not follow a user across devices — see ACCT-13. Once set explicitly it never re-follows a change in the OS setting, because there is no "system" third state.

Preset configured in app/app.ts; stylesheets are stylesheets/index.css, portal.css (1904 lines), landing.css, layout/layout.css, layout/menu.css, tour.css. Shared states: EmptyState.vue, ErrorState.vue, UpgradeRequired.vue, Loading.vue.

A 1904-line portal.css alongside Tailwind 4 and PrimeVue tokens is three styling systems in one app; ad-hoc overrides there are the most likely source of dark-mode and contrast regressions (ACCT-18).

Persisted keys today: darkMode, ubio_auth_token, ubio_last_token_refresh, hotel-universe:search-mode, hotel-universe:selected-hotels, hotel-universe:ai-assistant-chat (STORAGE_VERSION = 10), hotel-universe:ai-assistant-sidebar-collapsed, directPricingActiveBatches (TTL 24 h), metasearch-filter-panels, redirectUrl. Read and written through LocalStorageManager / SessionStorageManager.

The named gap: none of this is per-user or per-org on the server, so preferences do not follow a person between devices, and on a shared browser the next signed-in user inherits the previous user's selection and assistant transcript (see AUTH-05). Only the assistant state resets on org switch.

Tour hosted in app/layout/AppLayout.vue; options overlayOpacity 0.4, popoverOffset 20, stageRadius 6, overlayClickBehavior: 'none', styles in stylesheets/tour.css with classes hu-tour-popover / hu-tour-welcome. Unused anchors already exist for lists-sidebar, prices-results, assistant-empty, assistant-composer, search-ai-composer, ai-search-examples.

The tour navigates between routes and clicks real controls, so a slow API or a tier-gated route (/metasearch bounces trial users to Billing) can strand it mid-sequence. There is no way to replay it deliberately once dismissed.

AppLayout.vue + AppMenu.vue / composables/layout.ts (staticMenuMobileActive, toggleMenu) handle mobile navigation; the tour is explicitly skipped when window.innerWidth < 992. The selection rail is collapsible on mobile with ResizeObserver-measured height.

Navigation being responsive is not the same as the product being usable: the results table, the competitor price matrix and the direct-rates calendar are dense horizontal layouts, and the MapLibre location picker with its radius and area-scale sliders is difficult on touch. See ACCT-22.

users {id, googleId?, email, name, avatarUrl, lastOrganizationId?, createdAt, updatedAt}; there is no profile-edit endpoint and no profile screen — /settings edits the organisation name only.

Criterion 3 is unverified — if the profile is only captured at first login, stale names persist indefinitely, and the auto-generated org name "<name>'s Organization" freezes that stale name in place too.

<Toast> and <ConfirmDialog> are mounted globally in AppLayout.vue; copy constants are almost entirely inline, with only app/copy/toastTexts.ts (RICH_CONTENT_SUBSCRIBE_MESSAGE) extracted.

Toasts are transient and bottom-left; a user who looks away misses the only record that an export started or a subscription changed. There is no notification centre, which is what ACCT-12 addresses.

utils/formatters.ts uses toLocaleDateString('en-GB'|'en-US') with the locale hard-coded per call site; billing formatting lives in utils/billingFormatters.ts (formatCurrency, formatRenewalDate, prettifyPlan, formatTierLabel).

Mixing en-GB and en-US in one product means the same date can appear in two orders on two screens — a genuine misreading risk on check-in dates and cancellation deadlines. Criterion 4 needs ACCT-13.

app/views/Usage.vue + UsageTable.vue → ApiManager.getOrganizationStats({organizationId, startDate, endDate}); internal @ub.io users see all organisations via getAllOrganizations().

The metric is distinct hotels per action, not request count, so it does not explain rate-limit 429s on GET /metasearch or a metasearch allowance exhaustion; a user diagnosing a 402 will not find the answer here.

Adds a genuine account screen — today /settings is organisation settings only. Avatar hosting could reuse the img app (GET /img/resize?hash&w&h, sharp cover-resize, JPEG q75), though that endpoint is currently unauthenticated and would need gating for user-supplied images.

User-uploaded images introduce a moderation and malware surface the platform does not have today; restrict to image MIME types, re-encode server-side, and never serve the original bytes.

The platform sends exactly one email type today (sendInvitationEmail via SendGrid) and has no welcome, export-ready or quota-warning emails. The signals all exist server-side: export status transitions, accessLogs-derived quota maths, metasearchAllowance.exhausted, and listDiffManager new-hotel counts.

Export links must not embed credentials — the download URL is a 15-minute signed GCS URL, so an email should link to the portal, not to the signed URL. Digest volume must respect the 30-day export expiry so links in old digests fail gracefully.

Preferences stored on the user record and applied as defaults in MetasearchFilter.vue (currency list from utils/currencies.ts, locale list from utils/locales.ts), the competitor and surroundings components, and utils/formatters.ts. Note a documentation trap: docs/docs.http states a locale default of gb while the API code uses us.

Currency is not just presentation — GET /metasearch takes it as a request parameter and providers return prices in it, so a default change alters what is fetched and cached, not just what is displayed. TripAdvisor and Booking scrapers default to USD and MILES internally, which can leak into displayed source data.

The Home route is a redirect: { name: 'HotelsSearch' } in RouterManager.ts; this makes the redirect target a stored preference resolved after access.refreshAccessInfo() so tier gating is known.

Interacts with three existing guards (requiresAuth, requiresMetasearchAccess, requiresUbioAccess) and with the onboarding tour, which assumes it starts on /search — the tour must override the preference on first sign-in.

Distinct from dynamic lists: a saved search today is a list (POST /search/save creates one, auto-named from the filters, e.g. "name:hotel, country:ES, city:San"). A preset is lighter — filter state only, no entries, no diffing — and would serialise the same query object that queryToFilters and applyFilters already round-trip through the URL.

Filter definitions evolve; a preset saved against an older FILTER_DEFS set must degrade gracefully when a key disappears. Presets containing map geometry (geometry, geometryMultiplier) reference a place id that may change upstream.

Highest value in ListReviewQueue.vue (1094 lines, approve/reject per row plus approve-selected and approve-all) and HotelResultsTable.vue with its per-row, select-all-visible and virtual-selection modes. The assistant composer already binds Enter to send, which is the existing precedent to respect.

Infinite-scroll tables move focus unpredictably when new pages load through the IntersectionObserver sentinel; focus must be pinned to the row, not the index.

Targets HotelsTable.vue / HotelResultsTable.vue, components/search/LocationPickerModal.vue (MapLibre, radius slider 1–200 km, area-scale slider 1–10×, debounced getNearbyHotels count with a "1000+" cap) and components/hotel/MapComponent.vue. PrimeVue 4 provides accessible primitives, but the icon-dense custom cells and canvas maps do not inherit them.

Canvas-rendered maps are opaque to assistive technology by definition, so the text alternative is the feature, not a nicety. Chasing WCAG 2.2 AA without an automated check in CI means regressions land silently.

Affects CompetitorPriceMatrix.vue (date × hotel matrix, heat gradient legend, weekend shading, ±% gap colouring), GaugesList.vue, HotelInfoFieldConsensus.vue confidence pills, the direct-pricing status icons, and the global <Toast> / <ConfirmDialog> in AppLayout.vue. The "Cosmic Calm" OKLCH ramps make contrast auditable programmatically.

Heat maps are the hardest case: the gradient is the product's core price-intelligence visual, and making it colour-blind safe without losing its instant readability needs design work, not just a token swap.

There is no i18n today: no vue-i18n, no $t(), no locale message files, and all copy is hard-coded English. The only locale-adjacent utilities are utils/locales.ts, utils/currencies.ts, utils/languageCodesMapToName.ts and the toLocaleDateString calls in utils/formatters.ts. Extraction is the bulk of the work — portal.css aside, copy is spread across every component, with only app/copy/toastTexts.ts centralised.

Marketing copy on the landing page, the AI assistant's generated replies and the onboarding tour steps are three separate translation surfaces with different owners. Assistant output is model-generated and cannot be catalogued — it needs a language instruction instead.

GET /metasearch takes checkIn as a date and nights as a count, so stay dates are calendar values, while GET /stats takes startDate/endDate as ms epoch — the two must not be formatted by the same helper. DirectPricesDetail.vue shows per-day Updated timestamps and a live refresh poll; ListExports.vue shows created dates and expiry.

Date-versus-instant confusion is the classic source of off-by-one-day bugs in travel, and it lands directly on the product's core claim about which dates are cheapest. Export expiresAt (30 days) and signed URLs (15 minutes) are true instants and must stay so.

Reuses the export pipeline that already exists for lists: Readable.from(dbStream) → transform → toJsonArray → gzip → GCS, with getSignedDownloadUrl (v4, 15-minute validity) and the 200/202/410 download semantics. accessLogs is keyed by principalId, so per-user extraction is a direct query.

Token secrets are stored only as SHA-256 hashes and must never be reconstructed or included. Access logs contain huId values that reveal the org's commercial interests, so this is arguably org data as much as personal data — legal review needed on what a member may take with them.

The heaviest screens are CompetitorPriceMatrix.vue (date rows × hotel columns with a market-median column), DirectPricesDetail.vue (180/365-day calendar with row expansion), HotelResultsTable.vue and LocationPickerModal.vue. The mobile drawer, collapsible selection rail and ScrollTop already exist as building blocks.

Some of these screens are inherently two-dimensional; a naive responsive collapse loses the comparison that makes them valuable. Mobile also amplifies payload concerns — the matrix fetches months of price data at once, which is expensive on a phone connection.

app/components/search/filterDefs.ts (FILTER_DEFS, activeFilterDefs, formatChipValue, clearFilterDef) drives HotelFilterBar.vue; HotelManager.queryToFilters() / applyFilters() own normalisation and URL sync. Telemetry: search_filter_applied (with filterType), filter_chip_removed, filters_cleared.

Filters live only in the URL, so a very wide chip set produces long, ugly links; chip edits that race an in-flight request can show counts from the previous filter set until the newer response lands.

suggestFilterDefs(query, tier) and isFilterDefAvailableForTier in filterDefs.ts; tier comes from AccessManager.currentAccessInfo. The richContentSubscribed filter is the main tier-restricted entry (paid only).

Suggestions are matched against hard-coded English labels with no i18n and no synonym table, so "wifi" or "pool" surfaces nothing useful; tier data is cached for 30 s in AccessManager, so a just-upgraded org can briefly still see a filter greyed out.

FILTER_DEFS defines name, city, state, postalCode and brand as text/token chips; the local API clone's Atlas index atlas_custom_search_10 is dynamic: false and indexes only info.name and location.city among these. Gap: state, postalCode and brand have portal chips with no corresponding indexed field in the clone's search implementation.

Silently ignored filters are the worst failure mode here — a user believes they filtered by postcode and exports a list that was never constrained. location.state/province and brand are also sparsely populated across DS_NAMES, so even once indexed, recall will be uneven.

Chips defined in filterDefs.ts; backend clauses in the search repo build compound.filter in clauses for stars[] and country[]. Gap: propertyType and languagesSpoken are portal filters with no indexed field in atlas_custom_search_10, which indexes only info.starRating and location.countryCode from this group.

PROPERTY_CODES are mapped from roughly 80 raw source strings during ingest, so mis-mapped source values move a property into other and it disappears from a hotel filter. Star rating scale differs by source before canonicalisation, so 0 can mean "unrated" or "unknown".

Feature clauses are built as scoring must clauses in the Atlas compound; features.title is one of the indexed paths. Roughly 280 canonical FEATURE_TITLES exist in the API but are not yet enforced at ingest, so titles are whatever the Google/Booking/TripAdvisor feature maps produced.

maxEdits: 2 over-matches short tokens ("spa" matches "sea", "bar"), producing confident-looking but wrong lists. Because feature clauses are must and scoring, adding features both narrows and reorders, which surprises users who expect filters to be non-destructive.

hasLocation/hasFeatures/hasRating/hasImages/hasReviews map to HotelMeta availability flags indexed as meta.*.available in atlas_custom_search_10. Gap: the portal also exposes hasRooms and hasDirectWebsite chips, which have no counterpart in the clone's shared filter set or search index.

computeMeta makes images and reviews sticky — once available, always available — so a hotel whose images later 404 still passes hasImages. Availability says nothing about depth: hasReviews is true for a hotel with one review.

Chips minRating, minReviews and the rooms range (minRooms/maxRooms) are defined in filterDefs.ts. The Atlas index carries rating.numberOfReviews and rating.overallRating.max. Gap: the clone's GET /search filter set has no minRating/minReviews/room-count parameters, and no room-count field is indexed at all.

HotelRating.overallRating scale varies by source (Google 5, Booking 10) — a threshold applied before normalisation will silently mis-rank. Room counts come from HotelRoom.numberOfRooms per room type and are frequently absent, so a room-range filter will exclude large swathes of otherwise good data.

Both are boolean chips in FILTER_DEFS; tier gating flows through app/utils/accessTier.ts (showRichContentSubscribeOnSearch(tier), usesRichContentSubscriptionTabs(tier)) and AccessManager. Subscribed hotels are held per org (POST /orgs/:orgId/subscribed-hotels). Gap: neither filter exists in the local API clone's search parameters — both are live-only.

Subscription is time-boxed (365 days, richContentExpiresAt), so a saved search built on richContentSubscribed quietly shrinks as subscriptions lapse. directPricingOnly depends on IBE linkage, much of which is still resolved by the ubio-internal manual matching screens.

components/search/LocationPickerModal.vue (maplibre-gl); counts via ApiManager.getNearbyHotels({lat, lon, radius, limit, geometry, geometryMultiplier}) → GET /search/nearby; place lookup via ApiManager.geocode(query) → GET /geocode returning lat/lon/displayName/addressType/polygon/place_id. Server side, lat/lon/radius become a geoWithin.circle clause on the _loc 2dsphere/geo-indexed field, radius 1–10,000,000 m.

Polygon scaling is sqrt-linear from the centroid, so scaling a concave or multi-part boundary (an island group, a city with exclaves) produces an area no user asked for. The debounced count is an estimate capped at 1000+, so it cannot be used to predict export size or subscription cost.

Chip defined as hotelIds + hotelIdType + hotelIdFilterMode: include|exclude in filterDefs.ts; types/hotel.ts holds the ID-type list. Backend supports hotelIdType/hotelId over huId|googleHotelId|googlePlaceId|bookingHotelId|tripAdvisorHotelId|expediaHotelId. Gaps: the clone has no exclude mode, no multi-ID form, and no coverage for AllTopHotels or the extra OTA slugs; unmatched IDs are only surfaced via /stats on the CSV-upload path, not in search.

refs.* are token-indexed and case-sensitive; an ID pasted with different casing or a stray space will not match. The huId short-circuit bypasses every other filter clause, so combining huId with a radius silently ignores the radius.

HotelManager.listScopeId / setListScopeId(); entry point is the "Search this list" action in ListHeader.vue linking to /search?listId=. Gap: there is no listId parameter on GET /search in the API clone, so the scoping contract is live-only and undocumented.

Scoping a dynamic list is ambiguous — the list is a stored searchQuery, so "search this list" is really a query intersection whose membership can change between page loads. Large lists risk pushing the scope into a huge $in, which interacts badly with Atlas Search scoring.

Implemented in the search pipeline builder: no compound clauses at all → $match {_id: 'impossible-id'}. Portal side, HotelsSearch.vue renders AiAssistant/AiSearch when there are no filters.

The behaviour is a guard rail, not an error, so API consumers cannot distinguish "your filters matched nothing" from "your filters were all unrecognised and dropped" — both look like zero results. A documented 400 for a clause-free query would be safer, but would break the portal's current initial-load pattern.

Today there are no sort controls at all — the server always sorts rating.numberOfReviews: -1 and pages via Atlas searchAfter + searchSequenceToken (fetch 11, return 10). This would add a sort parameter to GET /search, extend the token payload, and add sort affordances to HotelResultsTable.vue.

Sorting by distance is only meaningful when a map filter is present; sorting by rating without normalising the source scale (Google 5, Booking 10) would produce a nonsense order. Non-relevance sorts fight Atlas Search scoring and may need a $sort stage, which costs the searchAfter optimisation.

Presets are distinct from dynamic lists: a dynamic list materialises hotels via POST /search/save, whereas a preset stores only the filter object. History could be derived from the existing hotel_search_executed telemetry already sent to POST /portal-events, or stored explicitly alongside presets.

Presets containing a map geometry reference a geocoder place_id that may change or disappear upstream. Org-shared presets need a permission model, and the platform currently has no per-user roles — every org member has identical scopes.

Builds on the existing Atlas compound construction, adding a mustNot bucket alongside must/filter; filterDefs.ts would gain a negatable flag and formatChipValue a negative rendering. The hotelIds chip already models this idea with hotelIdFilterMode: include|exclude.

Negation over incomplete data is dangerous: excluding "no pet friendly" removes hotels that simply never had features scraped. Fuzzy feature matching with maxEdits: 2 in a mustNot clause will over-exclude far more visibly than it over-includes.

Extends the existing map filter, which already carries an arbitrary geometry string plus geometryMultiplier, and the geoWithin clause on _loc. Isochrones require a routing provider; the geocoder behind GET /geocode already returns polygons, so the polygon plumbing exists end to end.

Isochrones are expensive and time-of-day dependent — caching them per POI/mode/budget is essential, and a cached rush-hour isochrone shown as an off-peak one is misleading. Transit isochrones have poor coverage outside major cities, which will look like a data bug to users.

LocationPickerModal.vue already renders boundary-fill / boundary-outline layers for geocoded polygons and emits an opaque geometry identifier; this would extend geometry to carry (or reference) a stored shape and add a MapLibre draw control. Backend already uses _loc with a 2dsphere index, which supports $geoWithin on arbitrary polygons.

Arbitrary polygons with many vertices will slow the geo clause and blow up saved-search payloads; a simplification step is needed. Shapes crossing the antimeridian or with reversed winding order are a classic source of "returns the whole planet" bugs.

The portal already has a flat brand chip and HotelInfo.vue displays "Brand" and "Sub-brand". This would add a canonical chain reference dataset alongside the existing reference data (Countries.ts, IsoCodes.ts, FeaturesMapGoogle.ts) and index brand fields in atlas_custom_search_10.

Brand attribution is the least consistent field across DS_NAMES, and the canonical merge takes the highest-priority source's value wholesale, so a stale GoogleHotels brand will beat a fresher Booking one. Chains rebrand and get acquired, so the hierarchy needs versioning or historical searches will drift.

Would join search against the pricing surfaces rather than canonicalData6: GET /metasearch already returns rateType: cheapest|refundable and free-cancellation dates per offer, and Direct ARI exposes "per room, with full rate plans, LOS rules and cancellation policies" up to a 365-day lookahead. Gating would follow hasMetasearchAccess() / direct-pricing entitlement.

Metasearch responses take 2–5 s per property and are rate-limited per principal (RATE_LIMIT_REQUESTS 100 / 60 s applied to GET /metasearch), so a live rate-aware filter over thousands of hotels is not feasible without a precomputed nightly index. Rate availability changes minute to minute, so results will be stale by the time a list is exported.

This generalises the existing competitor search: GET /hotels/:huId/competitors with {radius, limit, criteria}, surfaced by HotelLocation.vue with the CompetitorCriteria.vue weighting UI (stars, guest rating, property type, amenities, distance; levels including off; presets; reset) and 10 km default. The proposal is to promote that engine into the main search screen and let its output become a normal selectable result set.

Competitor search is currently coupled to the metasearch/price-insights flows and its own access checks, so promoting it needs a clear entitlement story. Similarity over amenity counts rewards hotels with verbose source data rather than genuinely comparable ones.

Builds on the existing POST /search/ai path used by views/AiSearch.vue, which already applies filters and navigates to /search, and on the assistant's active-filter chips in views/AiAssistant.vue. The improvement is a strict mapping contract onto FILTER_DEFS plus an explicit unmapped-fragment channel in the response.

A parser that silently invents filters is worse than one that refuses — the current failure mode (filters applied without explanation) already makes result counts hard to trust. Parsed geographies need to route through GET /geocode so that "near the client office" produces a real map filter rather than a city guess.

The API defines roughly 280 canonical FEATURE_TITLES that are not yet enforced, plus per-source maps (FeaturesMapGoogle.ts at 1166 lines, Booking and TripAdvisor maps) that the dictionary would sit beside. The current pipeline puts scoring clauses in compound.must (name text, geoWithin.circle, per-feature fuzzy text, meta equals) and non-scoring ones in compound.filter (stars in, countryCode in, city text, refs equals), then sorts by rating.numberOfReviews: -1 — so score is computed and then largely thrown away; exposing $search score metadata and a weights config makes that trade-off visible.

Enforcing canonical titles or publishing synonyms retroactively changes what existing dynamic lists return on refresh — a silent membership change nobody asked for. Synonyms are language-specific and the platform has no i18n; explanations expose index internals, so the debug panel should be tier- or role-gated.

Custom values would live alongside listEntries (which already carries per-entry reference IDs) rather than polluting canonicalData6, with an org-scoped index for filtering. Ingest could reuse the existing CSV path (POST /lists/upload, csv-parse with columns: true, extra columns currently ignored) — the landing copy already promises "extra columns are ignored", which is exactly the data being discarded.

Org-scoped fields must be strictly partitioned; the platform's cross-org guard today is a single 403 check on list reads, and POST /sources currently has no auth check at all, so a new write surface needs careful scoping. Custom-field filters cannot be served by the shared Atlas index without a per-org join, which will be the performance bottleneck.

Today the equivalent path is CSV upload to POST /lists/upload, which keeps a row only if it carries at least one of huId/googleHotelId/googlePlaceId/bookingHotelId/tripAdvisorHotelId/expediaHotelId, then runs matchRecordsToHotelsByIds as $lookup + $merge per id field in the fixed order googleHotelId → googlePlaceId → bookingHotelId → tripAdvisorHotelId → expediaHotelId (first match wins), leaving unmatched entries with huId: null. This story brings that power to search without forcing list creation first.

The fixed field order means a row carrying conflicting IDs resolves to whichever field is checked first, which can be the wrong property; the report must show which field matched. At 10,000 IDs the response exceeds sensible page sizes, so the result must be a cursor or a job, not a single payload.

components/search/HotelsTable.vue → HotelResultsTable.vue; ratings via the shared HotelRating component; rows are HotelPreview objects (huId, googlePlaceId?, preview{name, city, country, starRating, userRating}, meta{...available}) returned by GET /search.

HotelPreview carries only preview fields, so anything richer requires a profile fetch that may return 402 on trial. Names come from the highest-priority source in _dsNames, so the table can show a name a user does not recognise from their own file.

Icons are driven by HotelPreview.meta which mirrors HotelMeta availability flags derived by computeMeta during the canonical merge; the same six-icon pattern (minus one) appears as five icons in ListEntries.vue.

computeMeta treats images and reviews as sticky — once true, always true — so the icons overstate current availability. The icons are the only pre-selection quality signal, so their accuracy directly affects subscription spend.

HotelResultsTable.vue uses an IntersectionObserver sentinel; HotelManager holds hotels, total, nextPageToken, loading, loadingMore. Server side, GET /search returns {total, nextPageToken, hotels} with page size 10, implemented as Atlas searchAfter + searchSequenceToken fetching 11 and returning 10.

There is no way to jump to a position, so reaching row 4,000 means 400 sequential requests; the total itself is capped by a $searchMeta threshold of 1000 with an estimatedDocumentCount fallback, so the count above the sentinel can be an estimate. Browser memory grows unbounded on very long scrolls since rows are not virtualised.

HotelSelectionManager (toggleHotel, removeHotel, selectAll, isSelected, getSelectedIds, getSelectedHotels, getSelectedCount, syncVisibleHotels, clearAll).

"Select all visible" means "all loaded so far", which grows as you scroll — the same control does different things at different scroll depths. Selection is keyed on huId, so a hotel that appears twice under different reference IDs is a single selection.

HotelManager.forEachHotelsPageForCurrentFilters(onPage, {signal}) drives the paged fetch with an AbortSignal; the "Stop" affordance lives in the results table header alongside the bulk-select control.

A sweep over a result set of tens of thousands issues thousands of GET /search calls at page size 10 — there is no rate limit on /search today (only GET /metasearch is limited), so this is a self-inflicted load risk. Results can shift under the cursor mid-sweep, producing a selection that never existed as a single consistent set.

app/utils/selection.ts defines STATIC_SELECTION_LIMIT = 1000, the scope key (serialised filters) and createVirtualSelectionSaveToast; HotelSelectionManager exposes selectAllVirtual and isVirtualSelectionActive, with MAX_VIRTUAL_PREVIEW_HOTELS = 250. Gap: virtual selection is a portal-side concept with no corresponding server contract beyond POST /search/save, so "virtual selection minus exclusions" has nowhere to be expressed.

A virtual selection saved as a dynamic list is not a snapshot — refreshing it later returns whatever matches then, which is a materially different promise from "the 4,200 hotels I selected". The 250-hotel preview cap means users approve a bulk subscribe having seen 6% of what they are buying.

HotelSelectionManager.persistChanges() / hydrate() against the session key hotel-universe:selected-hotels; storage goes through the safe SessionStorageManager wrappers (loadJson/saveJson). Gap: only ids are persisted, so restoring a selection whose hotels are no longer in the visible result set gives a count without rows.

Session scope means a browser crash or an accidental tab close discards work that could represent hours of curation. Persisting ids without the scope key makes it possible to restore a selection under a different filter set.

Selection rail in HotelsSearch.vue with actions Save search as dynamic list, Save selection to static list, View N selected / Show all results, Subscribe to N selected (paid only, via RichContentSubscribeModal.vue and computeRichContentOverLimit), Compare metasearch, Clear selection, plus an "Assistant suggests" tip block; collapsible on mobile with a ResizeObserver-measured height. Telemetry: selection_drawer_opened, list_saved:dynamic, list_saved:selection_drawer.

"Save search as dynamic list" and "Save selection to static list" sit next to each other and produce very different artefacts — one tracks the query, one freezes ids. Subscribing is a billable action reachable in two clicks from a bulk selection, so the confirmation copy is doing a lot of work.

components/search/SaveSelectionForm.vue; ApiManager.saveListFromHotelIds(hotelIds, name?) → POST /lists/fromIds, appendListEntries(listId, huIds) → POST /lists/:id/entries, getLists({createdBy, page}). Telemetry list_saved:selection_table / list_saved:selection_drawer.

Appending to a dynamic list mixes manually chosen hotels with query-derived membership, and a later refresh or "Make static" makes the provenance ambiguous. There is no duplicate check on append, so the same hotel can be added repeatedly across sessions.

"Check prices" lives in the Name column of HotelResultsTable.vue and targets views/Metasearch.vue, which mirrors its params into the URL and discards stale in-flight results via a request key. GET /metasearch is FULL-tier only (402 otherwise), accepts only huId|googleHotelId per METASEARCH_HOTEL_ID_TYPES, and is rate-limited per principal.

Metasearch responses take 2–5 s and the rate limiter is 100 requests per 60 s per principal, so clicking "Check prices" down a result list will hit 429 with a Retry-After. Hotels without a googleHotelId ref cannot be priced at all, and the row gives no advance warning.

Implemented as a per-row hint icon in the Location column of HotelResultsTable.vue, comparing the hotel's preview.city against the active city filter term. Gap: it is a string comparison, not a boundary test, so it flags spelling variants as boundary issues and misses genuine boundary cases where the strings happen to match.

location.city comes from the highest-priority source in _dsNames.location, so the comparison is really "does this source's city string match your typing". Users may read the hint as a data-quality warning about the hotel rather than about their query.

Extends HotelResultsTable.vue, whose columns are currently fixed (selection, Name, Location, Star rating, User rating, Data). Preferences would follow the existing client-persistence pattern (LocalStorageManager keys such as hotel-universe:search-mode, metasearch-filter-panels).

Any column beyond HotelPreview's fields requires either a wider search projection or a second fetch, which conflicts with the ten-row page size. Per-user column state that is not org-shareable makes screenshots and support conversations harder to follow.

Would reuse the MapLibre setup already present in LocationPickerModal.vue (openfreemap liberty style, NavigationControl) and components/hotel/MapComponent.vue (which already renders hotel plus competitor markers), driven by the same HotelManager result state.

Only the first ten rows exist until you scroll, so a map of "results" is really a map of "loaded results" unless a separate bounded fetch is added — GET /search/nearby is capped and returns a count, not a full set. Clustering at low zoom over a large country will be dominated by data density, not relevance.

Would reuse HotelDetailHero.vue, HotelRatingDetails.vue and the amenities card from components/hotel/, fetching via GET /hotels/:id (which returns {access: 'full'|'preview', hotel}) and falling back to utils/hotelPreviewToHotel.ts on preview access.

Each quick look is a profile view and therefore counts against ACCESS_TIER_TRIAL_LIMIT (100 distinct hotels, all-time, counted from access logs) — arrow-key browsing could burn a trial in a minute. The drawer must not double-log hotels:view for a hotel already opened in the same session.

The "Field / Direct / OTAs" table in HotelDirectWebsiteOtaComparison (including its "Identical" rows and amenity shared/websiteOnly/otaOnly summary) is the closest existing pattern, and CompetitorPriceMatrix.vue already renders a hotel-column matrix. Comparison rows would draw on HotelInfo, features grouped by category, HotelRating and room counts.

Attribute-level comparison exposes provenance conflicts loudly — two hotels described by different priority sources will look more different than they are. Loading prices for four hotels is four metasearch calls at 2–5 s each against a per-principal rate limit.

Reuses the confidence model already in the link package: nameSimilarity*0.2 + addressSimilarity*0.2 + postalCodeMatch*0.3 + locationMatch*0.3, accepted at ≥ 0.7, with Jaccard plus Levenshtein similarity, normalised postcode equality and Haversine distance. The presentation can follow ListReviewQueue.vue, which already shows per-signal confidence pills for overall/name/address/postalCode/geo.

The known limitation that "123 Main St" and "124 Main St" are not well distinguished cuts both ways — false duplicate prompts erode trust faster than missed ones. Merging is destructive and must never be user-initiated without data-ops review.

Today exports exist only against a list: POST /lists/:listId/exports with type full|preview|reviews, streamed as Readable.from(dbStream) → transform → toJsonArray → gzip → GCS, expiresAt = now + 30 days, signed download URL valid 15 minutes, plus a source_data type in the portal gated on access.licensedSources. This story would let a search feed the same pipeline, using the repo's unbounded stream generator that already backs saved search.

Exporting "all matching results" for a filter that matches hundreds of thousands of hotels is effectively a bulk data extraction — it needs the same tier gating and access logging (export:create:*) as list exports, or it becomes a licensing hole. The clone produces gzipped JSON only; CSV is live-portal behaviour and needs a defined column contract.

The portal already writes filters to the URL query via HotelManager.applyFilters and reads them back with queryToFilters, and the README requires that URLs address resources — so the substance here is a short-link store plus org-scoped resolution, not new filter plumbing.

Long filter sets already make unwieldy URLs, so a share feature will be used heavily and become an access-control surface: short links must be resolved against org membership, not treated as capability tokens. Links must not embed the hotel-universe:selected-hotels selection, which is personal and session-scoped.

Diff computation already exists: GET /lists/:id/diff powers ListDiffManager and the ListDiff.vue panel ("Found N hotels not in the list", Add selected / Add all). The gaps are scheduling and delivery — the platform sends exactly one email type today (sendInvitationEmail via SendGrid), and the landing page already advertises "push diffs to a webhook", which does not exist in the clone.

Diffs on a filter-based list are sensitive to index and ingest changes, so a reindex or a synonym change could produce a huge false "new hotels" email. Email volume and unsubscribe handling are new operational surfaces with no existing precedent beyond invitations.

Promotes the current session-only mechanism (HotelSelectionManager.persistChanges/hydrate against hotel-universe:selected-hotels) to a server-side working set keyed by user plus org, stored alongside the scope key from utils/selection.ts so restored selections carry their filter context.

A durable selection is close to being an unnamed list, so it risks duplicating the list model — it should have an explicit lifetime and a one-click "make this a list". Cross-device sync needs conflict handling when both devices edit the selection.

Builds on the existing global <Toast position="bottom-left"> in AppLayout.vue and HotelSelectionManager.clearAll; the undo buffer is a single previous snapshot of getSelectedIds() plus isVirtualSelectionActive state.

Undo for a virtual selection can only restore the scope key, not a materialised set, so the restored state may resolve to different hotels. Undo must not extend to already-committed actions such as list creation or subscription, which have billing consequences.

Applies to HotelResultsTable.vue; the infinite-scroll IntersectionObserver sentinel needs a keyboard-driven counterpart because focus movement does not necessarily scroll the sentinel into view. The six availability icons need accessible labels, which they currently rely on tooltips for.

Keyboard paging plus select-all interactions can trigger the same bulk sweeps as the mouse path, so the abort control must also be reachable by keyboard. Focus management across appended pages is a common source of focus-loss bugs.

Would extend the existing telemetry channel (portalTracking.track → POST /portal-events) with a first-class feedback resource, and reuse the escalation pattern already built for the assistant (POST /ai/assistant/contact with message, transcript and page URL). Reports would join the same ops queue that reviews entity-resolution decisions.

Without triage, a feedback button generates volume no one reads, which is worse than no button. Reports contain customer query context, so retention and cross-org visibility need to be explicit.

The rules are written down in the portal README.md (top bar = main sections, left sidebar = second level, tabs = third level, URLs must address resources, icons on nav links, action placement, capitalisation, "no stale content, show skeleton", content width and right-sidebar rules). Implemented through AppLayout.vue, SettingsLayout.vue and the per-area sidebars such as ListsSidebarMenu.vue.

The README also declares the repo deprecated in favour of packages/portal in the API monorepo, so the guideline document and the code that follows it are drifting apart. Screens added under time pressure (the internal IBE matching views, AiRecommendations.vue) already sit outside the model.

app/managers/NavigationManager.ts. Gap: /ai/search, /ai/assistant, /ai/insights and /ai/recommendations are real routes with no nav item — the assistant is reachable only inline from search, AiRecommendations.vue is unlinked mock data, and /direct-prices/lists has no entry either.

Hiding gated products makes them undiscoverable and directly costs upgrades; showing them all makes the trial experience feel like a wall of locks. Orphan routes accumulate silently because nothing fails when a route has no nav entry.

Required by the README ("URLs must address resources"); implemented for search filters (HotelManager.applyFilters / queryToFilters), metasearch (params mirrored into the query and auto-searched on deep link), hotel and list tabs (?tab=), /direct-prices?view=my|all, /lists/:filter(my|all) and billing's ?organizationId=. Gaps: selection state lives in sessionStorage (hotel-universe:selected-hotels), assistant conversations in hotel-universe:ai-assistant-chat, exports and filter drawers have no URL, and there is no sort in the URL because there is no sort.

State split between URL and storage means a shared link reproduces a different screen for the recipient than the sender sees. Auto-searching on deep link means a shared metasearch URL immediately spends a rate-limited, billable query.

RouterManager.ts — router.beforeEach steps 1 and 2, router.beforeResolve hash stripping, helpers goHome(), goToLogin(), setRedirectUrl(url), goToRedirectUrl(clear = true) with the same-origin check; layout/GoogleAuthCallback.vue handles code/state/error with processing, error and success states.

redirectUrl is session-scoped, so signing in from a fresh window loses the destination. If storage writes fail (private browsing, quota), the redirect silently degrades to Home with no message.

router.beforeEach step 4 checks access.hasMetasearchAccess() for /metasearch, /hotels/:id/competitor-prices, /lists/:id/price-comparison and /ai/insights. Allowance exhaustion is separately modelled by METASEARCH_TOPUP_REQUIRED_REASON = 'metasearch_topup_required' with warning banners on Price Insights, Market Insights and the price matrix. Gaps: the redirect carries no context about where I came from, and refreshAccessInfo() failures are swallowed with navigation continuing.

A silent bounce to Billing looks like a bug, especially when it happens from a shared deep link. The 30 s access cache means a user who just subscribed can be redirected once more before their new entitlement is visible.

router.beforeEach step 5; AccessManager.isUbioUser() / ensureUbioAccessResolved() check the email domain; routes /hotels/:huid/manual-ibe-matching and /lists/:listId/manual-ibe-matching. Gaps: the API's isUbee() checks only @ub.io while the portal also accepts ubio.ai, and internal super-user status is an email-substring test rather than a role.

Email-substring authorisation is fragile — a customer address containing the string, or a domain change, silently grants or removes internal access. There are no per-user roles in the platform at all, so "internal" cannot currently be modelled any other way.

?tab= is handled by HotelDetails.vue (tabs preview, overview, rooms, photos, reviews, directwebsite, metasearch, insights, directari) and ListView.vue (Needs review, Rejected/Unmatched, Confirmed Hotels, plus Subscribed and Not subscribed on paid), with app/utils/accessTier.ts supplying listViewValidRouteTabs(tier). Gap: tab availability depends on tier, preview-versus-full access and list type, so the same link resolves differently for different recipients with no explanation.

On preview profiles overview/rooms/photos/reviews are locked behind a padlock and RICH_CONTENT_SUBSCRIBE_MESSAGE, so a support link to a locked tab looks like a dead end. Deep-linking the metasearch tab triggers a billable, rate-limited query on load.

RouterManager.ts defines the catch-all as redirect: { name: 'Home' }, and Home itself redirects to HotelsSearch. Gap: there is no 404 or 403 view anywhere in app/views/ — every unknown, unauthorised or gated path converges on the search screen.

Three different failures (typo, deleted resource, missing entitlement) produce one identical outcome, which makes support triage guesswork. Silent redirects also mask genuine routing regressions, because nothing ever errors.

AppLayout.vue hosts the mobile Drawer, with AppMenu.vue / AppMenuItem.vue and composables/layout.ts (staticMenuMobileActive, toggleMenu). Tour skipping is explicit: onboarding is skipped when window.innerWidth < 992. Gap: the wide data screens (CompetitorPriceMatrix.vue, HotelPriceInsights.vue) have no small-screen treatment.

Skipping the tour on mobile means mobile-first users never get onboarded at all. Chart.js canvases and the date × hotel matrix do not reflow, so mobile users see horizontally scrolling tables with no affordance saying so.

Titles are declared in RouterManager.ts route meta (Hotel Universe: search, …full profile). Gap: only a few routes declare a title, none are dynamic, so most screens inherit whatever the previous route set.

Dynamic titles need the resource loaded, so the title lags the navigation and must be updated after fetch — and reverted if the fetch 402s or 404s. Titles containing customer list names end up in browser history and screenshots, which is a minor data-exposure consideration.

router.afterEach in RouterManager.ts; PortalTrackingManager.track(event, pageOrMetadata?, metadata?) with a 5 s flush and pagehide keepalive flush. page_view sits alongside the wider event set (hotel_search_executed, search_filter_applied, list_saved:, metasearch_executed, ai_assistant_, welcome_tour_* and others).

Events are keyed on route name, so /hotels/:id reports as HotelDetails with no resource identity — useful for funnel analysis, useless for "which hotels does this account look at" (that lives in accessLogs instead). Dropped flushes are invisible, so the data is best-effort.

Would live in AppLayout.vue alongside the existing Toast, ConfirmDialog and ScrollTop globals, drawing hotel results from GET /search, lists from GET /lists, and destinations from NavigationManager.getNavItems(). The tier labelling can reuse isFilterDefAvailableForTier-style checks and AccessManager.

Typing in a palette that hits GET /search on every keystroke is a load problem given there is no rate limit on search; debouncing and a minimum query length are mandatory. Palette hotel lookups must not count as profile views against ACCESS_TIER_TRIAL_LIMIT.

HotelDetailHero.vue already renders breadcrumbs on the hotel profile — this generalises that to lists, direct prices, the price matrix and settings, and makes origin part of the route state so "back to search with filters" is possible (which the filter-in-URL design already supports).

Origin-aware breadcrumbs need the origin carried in the URL or in history state, or they break on reload — the same class of problem as the selection state. Deep screens reachable from three places (a hotel from search, a list and the assistant) risk inconsistent trails.

The data already exists server side: accessLogs is a time-series collection recording {time, principalId, huId, meta:{orgId, action}} for hotels:view, reviews:view and more, and GET /stats/ already aggregates it. A recents endpoint would read the same collection ordered by time rather than aggregated.

accessLogs has a one-year TTL and hourly granularity, and its aggregation path is per-action distinct-hotel counting, so a recents query needs its own index or it will scan. Recents are per principal, so PAT-driven agent activity would pollute a human's list unless filtered by principal.type.

Pins are per user and per org, stored server side rather than in localStorage, and surfaced through NavigationManager.getNavItems() as an additional group. Subscription state for the badge comes from AccessManager.isRichContentSubscribed(huId) and richContentExpiresInDays().

Pinned items are another cross-org leak surface — resolution must be scoped by the current org, which changes under the user via switchOrganization and a full page reload. A pinned list that is deleted by a colleague needs a graceful tombstone, since lists are org-owned and anyone with lists:manage can delete them.

Static membership is a direct query over listEntries (which stores {listId, huId?, googleHotelId?, …} per entry) scoped to orgId. Dynamic lists hold a searchQuery instead of materialised entries, so membership for those is either evaluated on demand or marked as approximate. The section would sit in HotelDetailRail.vue next to the subscribe CTA.

For dynamic lists there is no cheap "does this hotel match this stored query" test, so the honest answer is "possibly" unless the query is re-run — showing a false membership would be worse than omitting it. listEntries is indexed by listId, so a reverse lookup by huId across an org needs a new index.

The artifact model already exists in AiAssistantManager / views/AiAssistant.vue (hotel_search, hotel, hotel_reviews, images, list_created, list, list_collection, pricing, location, generic) with an action toolbar offering "Open in Hotels", "Save as dynamic list", "Save as static list" and "Open list: <name>". This story makes those links carry full state (filters, ?tab=) instead of landing on defaults.

Assistant-generated filter sets must round-trip through queryToFilters cleanly or the user sees a search that does not match what the assistant described. Chat state persists in sessionStorage (hotel-universe:ai-assistant-chat, STORAGE_VERSION = 10) and resets on org or user switch, so deep links from an old conversation can outlive their context.

Builds on the existing query-string contract (queryToFilters/applyFilters, ?tab=, ?view=, ?listId=) and on setRedirectUrl/goToRedirectUrl with its same-origin check. Search mode is currently persisted in localStorage under hotel-universe:search-mode, which is what makes criterion 3 non-trivial.

A permalink is not an authorisation grant — a prospect without an org still sees nothing, so sales links need to pair with an invitation flow (POST /invitations, 7-day expiry). Links that pre-apply a metasearch query trigger billable, rate-limited calls on open.

Today Home is a hard redirect to HotelsSearch in RouterManager.ts, and goHome() is used by several guards. This would read a per-org preference (stored alongside the organisation record, edited in Settings.vue, which currently only renames the org) and resolve it inside the Home redirect and goHome().

The org default is consulted by guards that also fire on failure paths (requiresUbioAccess → Home), so a badly chosen default could create a redirect loop if that destination is itself gated — the resolver must fall back to /search unconditionally. The platform has no per-user roles, so "org admin" has no enforcement point today beyond the orgs:manage scope.

Replaces the catch-all redirect: { name: 'Home' } and the silent guard redirects in router.beforeEach (metasearch → Billing, ubio → Home) with dedicated views built on the existing components/ErrorState.vue, components/EmptyState.vue and components/UpgradeRequired.vue (which already carries the lock legend, value proposition and "View Billing" / "Contact Sales to Upgrade" buttons).

Distinguishing 403 from 404 leaks existence information, so internal routes must deliberately return not-found while customer-facing gated routes return an explicit upgrade page. Changing the catch-all will surface every currently masked broken internal link at once, which is the point but should be expected.

GET /hotels/{huId} in the api package, guarded by HOTELS_VIEW; the portal wraps it as ApiManager.getHotel(hotelId) and stores the result on HotelDetailsManager.hotel / .hotelPreview via loadHotel(id). huId is the 10-character ^[A-Za-z0-9]+$ primary key of canonicalData6.

The access-log row is written per view, so a customer polling the endpoint in a render loop burns trial quota against distinct hotels; repeat views of the same huId are deduplicated only because /stats counts distinct hotels per action, not requests.

views/HotelDetails.vue on the router entry /hotels/:id (name HotelDetails, title "…full profile"), tab state synced to ?tab= per the portal README rule that "URLs must address resources"; the padlock path is driven by HotelProfileAccess.PREVIEW with the subscribe CTA in HotelDetailRail.vue / RichContentSubscribeModal.vue and the copy constant in app/copy/toastTexts.ts.

Metasearch, Price Insights and Direct ARI tabs embed whole views (Metasearch.vue, DirectPricesDetail.vue) and are gated separately by hasMetasearchAccess(), so a deep link into an inaccessible tab lands on an upgrade panel that reads as a broken link; preview payloads are padded into a Hotel shape by utils/hotelPreviewToHotel.ts, so a component that fails to handle undefined shows a confident-looking empty value instead of a lock.

Quota is computed by AccessTierService from distinct huId values in accessLogs for hotels:view, all-time; FULL tier is unlimited. Portal handling is in HotelDetailsManager.loadHotel(id).

The limit is all-time and there is no reset or warning threshold, so a trial user can be one click from a hard stop with no prior notice; there is also no email at 80% or 100%, since sendInvitationEmail is the only transactional email that exists.

components/hotel/HotelDetailHero.vue; the subscribed state comes from AccessManager.isRichContentSubscribed(huId) and the Direct ARI badge from HotelDetailsManager.directPricingStatus.

Hero images are served through images.automation.cloud/img?hash=… and resized by the unauthenticated GET /img/resize app with cache-control commented out, so hero loads are neither cached nor rate-limited.

components/hotel/HotelInfo.vue reading HotelInfo from canonicalData6 (name ≤ 1000 chars, website, description, propertyType {code,title}, starRating 0–5, languagesSpoken[], phoneNumber, checkIn.from, checkOut.until).

Property type is mapped from roughly 80 raw source strings into 11 codes, so genuinely unusual stays collapse into other; brand and sub-brand are displayed but are not first-class indexed fields, so they cannot be filtered on in the same way as city or stars.

Amenities card in components/hotel/ (the older fieldset variant HotelFeatures.vue still exists); source titles are mapped by FeaturesMapGoogle.ts (1166 lines) plus the Booking and TripAdvisor feature maps, retaining originalTitle, originalCategory and dsName.

Search matches features with a fuzzy text clause per feature (maxEdits 2) against features.title, so unnormalised titles degrade both the profile display and the features[] filter at the same time; enforcing FEATURE_TITLES later will be a breaking change for anyone who has stored our titles.

components/hotel/HotelLocation.vue reading HotelLocation {streetAddress, city, postalCode, countryCode, country, state, province, coordinates{lat,lon}, rawAddress}; _loc is the 2dsphere-indexed GeoJSON point used by geo search.

Structured address components are produced by AddressSplittingService posting rawAddress to an external NodeScript endpoint; when that normalisation is poor the address lines and the coordinates can disagree, and nothing on the panel flags the conflict.

components/hotel/HotelRoomsDetails.vue over HotelRoom {id, name, description, surfaceM2, maxOccupancy, numberOfRooms, smokingAllowed, bedConfiguration[], roomFacilities[], roomViewOptions[], extras{blocksForRoom[], roomDetails}}; Booking room data is scraped via mobile.roomList using a "best date" one-night USD probe.

numberOfRooms comes from an availability probe on a single arbitrary date, so it reflects inventory offered that night rather than the property's true room count; the facilities column shows a count only, so two rooms with identical counts but different facilities look the same.

components/hotel/HotelImages.vue; URLs are rewritten to https://images.automation.cloud/img?hash=<AES-256-CBC ciphertext>.<iv> at ingest and resized on demand by the img app (sharp, cover, cubic, JPEG q75).

The AES key used to encode image URLs is hard-coded, and /img/resize has no auth and no cache headers; heavy gallery use is effectively an open image-proxy workload.

HotelSummaryManager wrapping the generic GeneratingSummaryPoller<T> (3 s interval, MAX_POLLS = 20, statuses ready / generating / error, unit-tested in GeneratingSummaryPoller.test.ts); the same poller backs HotelReviewSummaryManager and DirectWebsiteInsightsManager.

Twenty polls at three seconds is a hard 60-second ceiling; a cold generation for a very rich hotel can exceed it and surface as an error even though the summary lands moments later, and the client has no way to recover the completed result except a manual reload.

ApiManager.getDirectWebsite(hotelId) → GET /hotels/:id/direct-website and getDirectWebsiteInsights(hotelId, refresh) → /direct-website/insights, surfaced through DirectWebsiteInsightsManager; social handles are parsed by utils/socialLinks.ts. The tab is hidden on preview profiles.

Coverage is scrape-dependent and uneven, so for many hotels the flagship comparison table is simply absent; "Identical" is a string-level judgement, so trivially different formatting of the same address reads as a discrepancy.

HotelDetailRail.vue export-record action, gated on AccessManager.isRichContentSubscribed(huId); list-level equivalents go through POST /lists/{listId}/exports with type full | preview | reviews.

Because the download is not metered, per-hotel export volume is invisible in GET /stats/ and in any usage-based commercial conversation; a customer could script the profile endpoint and reconstruct a bulk export outside the export quota.

Build on HotelDataUpdateService.combineData, which already knows the previous _dsNames[group] and the incoming values, by emitting a change document per field group into a time-series collection alongside accessLogs; "last verified" can come from scrapingStatuses updatedAt per source rather than needing new crawling.

Naive per-field history over 1M+ hotels across seven field groups and five sources is a very large write volume; the design needs value-hashing and change-only writes, or it will dominate storage. Exposing history also exposes source churn that customers may read as instability.

All the raw values already exist in sourceHotelData5 keyed by {dsName, dsHotelId} and linked by huId; this is a read-only endpoint such as GET /hotels/{huId}/sources?field=info.name plus a popover in HotelInfo.vue, reusing the consensus data structure that already backs HotelInfoFieldConsensus.vue.

Showing raw OTA values verbatim raises redistribution questions — some sources' terms allow us to derive canonical values but not to republish their originals, so this needs to respect AccessManager.licensedSources in the same way the source_data export does.

Add a Manual entry at the top of DS_NAMES so the existing combineData priority walk enforces overrides for free, plus a review queue modelled on ListReviewQueue.vue (approve / reject per row, per-signal detail in an expansion panel).

A hotel owner asserting values about their own property is both the best and the worst source — self-reported star ratings and amenity lists are a known inflation risk, so overrides need an audit trail and probably a per-field allow-list. Unbounded manual overrides also fork the record away from what re-scraping can maintain.

SourceImageData already stores width, height, format, fileSize, pixels, aspectRatio, compressionRatio and estimatedQuality per source image, so scoring is mostly a matter of surfacing and combining fields that are already collected; classification into roles would need a vision pass at ingest.

This depends on the encodeImageUrls dimension-loss bug being fixed first (HOTL-09) — scoring on canonical records that have lost width/height would silently fall back to defaults and rank everything equally.

Reuses the scoring and review-queue pattern already proven in the CSV matching flow (matchRecordsToHotelsByIds, ListReviewQueue.vue, confidence thresholds, approve/reject) but applied to HotelRoom.name plus bedConfiguration and maxOccupancy as signals.

Room names are the least normalised part of the record (they come straight from scraped room lists), so mapping quality will be materially worse than hotel-level matching; per-organisation mapping tables also multiply export cost since exports currently stream a single canonical shape.

Extend HotelImage into a media union with a kind discriminator so images[] stays backward compatible, and bypass the img resize path for floor plans, where cover-cropping to a thumbnail destroys the asset.

The current image pipeline assumes cover-resize JPEG output; floor plans and PDFs would need a separate storage and serving path. Third-party video links rot quickly and there is no link-checking job today.

Today this exists only as a Business & Events feature category with boolean-ish titles; structured capture would need a new sub-document on CanonicalData plus Booking and TripAdvisor extraction, and a new Atlas Search field to make capacity filterable.

Meeting capacity is quoted inconsistently across sources (theatre vs banquet vs classroom), so a single "capacity" number would be misleading; coverage would be very thin outside chain properties, which risks a filter that silently excludes good hotels.

The Accessibility value already exists in the sixteen-category HotelFeature enum and TripAdvisor PoiAmenities returns granular items, so this is largely a mapping and presentation problem on top of the existing feature pipeline plus enforcement of the canonical FEATURE_TITLES.

Publishing accessibility claims we scraped from OTAs creates real-world harm and legal exposure if wrong; present / absent / unknown must be honest, and "unknown" will be the most common answer for a long time.

HotelFeature.tags already encodes Free / Extra charge / On-site / Nearby / Public / Private, which is the seed of the structure; the Booking scraper's getPolicies call already returns policy text that is currently only kept in sourceHotelData5.policies.

Fees change more often than the 30-day scrape threshold, so a stale price shown as structured data reads as authoritative in a way free text does not — these fields need per-field freshness (HOTL-13) before they are safe to publish.

The Booking scraper already calls getHotelDescriptionTranslations, so multi-language descriptions are partly collected and discarded at merge; storing them as a language-keyed map on HotelInfo is the smaller half of the work. Note the portal itself has no i18n at all, so this is an API-first capability.

Language coverage will be source-skewed towards Booking, so a lang= parameter that works for Booking-covered hotels and falls back for Google-only ones produces an inconsistent catalogue; per-language descriptions also multiply export size.

brand is already a search filter def in filterDefs.ts and is displayed by HotelInfo.vue, but there is no brand collection and brand is not in the atlas_custom_search_10 indexed field list — this needs a canonical brand entity, a resolution pass over existing values and a new indexed field.

Brand strings vary wildly by source and franchise agreements change ownership without changing signage, so a brand entity will need the same manual-override and dispute machinery as the rest of the record; getting it wrong is commercially sensitive for the brands themselves.

Sits next to the existing export-record action in HotelDetailRail.vue and would reuse the export pipeline pattern (async job, GCS upload, signed download URL) rather than rendering client-side, so large hotels do not block the browser.

A PDF that embeds OTA-sourced photos and review scores is a redistribution surface; attribution and licensedSources checks matter more here than for JSON, because the artefact leaves the customer's systems.

GET /hotels/{huId}/reviews guarded by REVIEWS_VIEW; reviews live in their own collection canonicalReviewData1 {huId (_id), _dsNames.reviews, reviews[]}, separate from canonicalData6. Portal access is via HotelReviewsManager.loadReviews(hotelId).

Reviews are stored as a single array on one document per hotel, so a hotel with tens of thousands of reviews produces an unbounded response with no pagination parameters — this is the sharpest scale risk in the epic.

components/hotel/HotelReviews.vue over HotelReview {source, reviewDate?, reviewer.name, overallRating?, original{...}, translation?}; a count line sits above the list and the tab badge shows a formatted count such as 1.2k.

reviewer.name is present in the read model even though the export schema strips it, so the portal is displaying PII that the export path deliberately removes — the two surfaces disagree about what is publishable.

components/hotel/HotelRatingDetails.vue plus the generic components/GaugesList.vue (0–1 ProgressBar list), reading HotelRating.ratingDistribution{1_star…5_stars .percent} and numberOfReviews.

rating.numberOfReviews is also the default search sort key and is indexed in Atlas Search, so a source that inflates review counts both distorts this panel and quietly reorders every search result page.

HotelRating.overallRating{min,max,average} in the shared schema (Google 5, Booking 10); the HotelRating component in search results and HotelRatingDetails.vue on the profile both do their own normalisation.

This is the single most likely source of a customer-visible correctness complaint in the whole review area, because it is invisible until someone sorts or thresholds on rating and gets a list that makes no sense.

HotelRating.categoryScores{cleanliness, comfort, facilities, location, staff, valueForMoney, wifi, total} (0–10), populated by the Booking and TripAdvisor category-score maps in the shared reference data.

Category scores are effectively Booking- and TripAdvisor-shaped; Google-only hotels will show none, so a customer comparing a Google-only property against a Booking-covered one sees an apparent data gap that is really a coverage gap.

components/hotel/HotelReviewMentionRatings.vue over reviewMentionRatings[]{title, category?, type?, sentiment{overall, negative.percent, positive.percent, neutral.percent}}, with source aspect names mapped through MentionRatingMap.ts.

Aspect vocabularies differ per source and the mapping is a static file, so unmapped aspects fall through with their raw source title, producing inconsistent aspect names between hotels.

HotelReviewSummaryManager over the shared GeneratingSummaryPoller<T>; refresh is getHotelReviewsSummary(hotelId, refresh).

An AI-written "Common complaints" list attached to a named hotel is a defamation-shaped risk if it over-generalises from a handful of reviews; the footnote is the only mitigation today.

HotelReviewExport in the shared schemas explicitly omits reviewer; ExportService emits one HotelReviewExport per review through Readable.from(dbStream) → transform → toJsonArray → gzip → GCS.

The guarantee holds for exports but not for GET /hotels/{huId}/reviews, which still returns reviewer.name; a customer who pages the API instead of exporting gets PII that the export contract says they will not receive.

ListExportsManager (exportListHotels, startPolling, downloadExport) and components/list/ListExports.vue; files are gzipped JSON at {listId}/{exportId}/{type}-{timestamp}.json.gz in GCS.

On the paid subscription model the reviews export is disabled on the review, unmatched, hotels and not-subscribed tabs ("Subscribe to hotels to unlock export"), which means the button a customer can see is frequently one they cannot press; the generic failure message also gives support nothing to work with.

GET /stats/ aggregates distinct huId per action from the accessLogs time-series collection (TTL 1 year, hourly granularity); views/Usage.vue with a default range of the last 30 days.

Counts are distinct hotels, not requests, so a customer hammering the reviews endpoint for one hotel shows as usage of exactly one — usage reporting and cost of service are only loosely related, and none of this is reported to Stripe.

Requires reshaping canonicalReviewData1 from one array-bearing document per hotel into a queryable per-review collection, or at minimum a server-side filter and pagination layer over the array; the portal filter UI can reuse the chip pattern from HotelFilterBar.vue and filterDefs.ts.

Traveller type is not captured in HotelReview at all today, so that dimension needs new extraction from the Booking and TripAdvisor scrapers before it can be filtered; shipping the filter with a mostly-empty facet would look broken.

Extend the existing Atlas Search investment — a second index over a per-review collection, mirroring the pattern of atlas_custom_search_10 on canonicalData6 (lucene.standard, dynamic: false, explicit field list).

Multi-language corpora make relevance ranking awkward; searching English against machine translations returns different results than searching the original language, and users will not realise which they are doing.

Chart.js is already registered in the portal with bar and line controllers for HotelPriceInsights.vue, so the rendering stack exists; the aggregation would be a new endpoint alongside GET /hotels/:huId/price-insights.

reviewDate is optional in HotelReview and coverage varies by source, so a volume trend can look like a collapse in guest activity when it is really a change in which source we last scraped.

Reuses GET /hotels/:huId/competitors and the CompetitorCriteria.vue weighting UI (stars, guest rating, property type, amenities, distance, presets, off levels) that already drives competitor discovery and the price matrix.

Blocked on REVW-04 — benchmarking averages across mixed scales would produce confidently wrong league tables, which is worse than no benchmark at all.

Needs both a scheduled evaluation job — the PeriodicTaskRunner / Sleepbox pattern from the scrapers package is the natural home — and an outbound delivery mechanism. Neither exists: today there is exactly one transactional email (sendInvitationEmail) and no outbound webhook feature, despite the landing page advertising "push diffs to a webhook".

False positives from re-scraping are the dominant failure mode; an alerting product that cries wolf on ingest artefacts will be muted within a week, so provenance-aware suppression is a hard prerequisite, not a refinement.

Requires historising reviewMentionRatings, which today is overwritten on each canonical recompute; the change-feed proposed in HOTL-13 would carry these snapshots for free if rating is one of the tracked field groups.

Scrape cadence is a 30-day staleness threshold with batches of 100 at concurrency 50, so aspect series will be irregularly sampled — trendlines must be drawn against real observation dates, not evenly spaced buckets.

HotelReview has no response field today; Booking and TripAdvisor both expose management responses in the payloads the existing scrapers already fetch, so this is an extraction and schema change rather than new crawling.

Response-rate metrics attached to a named property are exactly the kind of comparison a hotel will dispute; without complete source coverage the number will be systematically understated.

Duplicate-text detection across hotels is feasible today because reviews are stored centrally per hotel with a source field; the same Jaccard / Levenshtein similarity utilities used by AddressMatcher in the link package can be reused for near-duplicate text.

Publishing an authenticity score implicitly accuses named sources of hosting fake reviews; the score should probably be exposed as an internal filter first, and only surfaced externally with careful wording.

HotelReview.source and canonicalReviewData1._dsNames.reviews already carry everything needed; this is an aggregation endpoint plus a table, sharing the provenance vocabulary used by HotelReferences.vue.

Because review documents are merged by source priority, a lower-priority source's reviews may be entirely absent rather than merely down-weighted, so the breakdown may reveal a coverage gap customers did not know they had.

Directly closes the named gap in REVW-04; needs a stored normalised field indexed in atlas_custom_search_10 so minRating filtering becomes meaningful, plus per-organisation configuration stored on organizations next to tier and billing.

Per-organisation scoring makes the canonical record no longer identical for every customer, which cuts against the "one canonical record" positioning; it is safer to ship a fixed default normalisation first and make configuration an add-on.

The clone's ExportService only emits gzipped JSON, though the live portal offers CSV/JSON; the streaming pipeline (Readable.from → transform → toJsonArray → gzip → GCS) needs only a different transform stage to emit rows, preserving constant memory.

Free-text review bodies in CSV are a classic injection and mangling risk (formula injection in spreadsheets from a leading =), and multi-language text needs an explicit BOM or encoding declaration to survive Excel.

Builds on the AI review summary pipeline behind GET /hotels/:id/reviews/summary and on AccessManager.licensedSources, which already gates the source_data export with the tooltip "Upgrade to a plan with the source data addon…".

This is the highest legal-risk story in the epic: republishing verbatim OTA review text is a redistribution question, not a technical one, and the feature should not ship without source-by-source legal sign-off encoded in licensedSources.

Closes the mismatch between HotelReviewExport (strips reviewer) and the read endpoint plus HotelReviews.vue (both display reviewer.name). The accessLogs TTL of one year is the only retention policy that exists today; review documents themselves have none.

Review documents are one array per hotel, so a single-review deletion is a document rewrite; at scale, deletion requests would need a tombstone approach or the per-review collection proposed in REVW-11.