Help center

Purpose#

Resolves contextual help for the tenant admin — knowledge-base search, in-product tooltips, changelog delivery decisions, and feedback/editorial-backlog routing — filtered by audience, role, domain, surface, and locale. It is the help workspace (group: configuration) in @oshun/navigation.

Entry points#

• Shell sidebar Configuration › Help item (TenantSidebar, shortLabel: 'Help', path /help).
• Direct URL /help (bookmarkable; scope-gated).

Layout regions#

Wrapped in <TenantShell session currentWorkspaceId="help">:

• Sidebar / Header: standard chrome (header crumb "Help center").
• Main (<section data-testid="tenant-help-panel" data-tenant-id={...}>):
  • <h1>Help center</h1> + subtitle on contextual resolution by audience / role / domain / surface / locale.
  • styles.summaryGrid of three tiles: Search results (searchResults.length), Tooltips (contextual.tooltips.length), Changelog (Send/Skip from changelogDelivery).
  • styles.list — one <li> per search result (<strong>{title}</strong> + summary) plus one <li> per feedback item (<strong>Editorial backlog</strong> + joined missingSubjectCounts keys).

States#

• Loading — N/A; synchronous server render from searchHelp, resolveInProductHelp, aggregateFeedback, shouldDeliverChangelog over one hard-coded HelpArticle + seed inputs (no fetch).
• Empty — the article matches the seeded query (term: 'seats', surface /members, domain metis), so searchResults has ≥ 1 item; a non-matching query would yield an empty list (no <li> rendered, tile reads 0).
• Populated (short) — one search result ("Manage seats") + one editorial backlog item (missing subject scim). Changelog tile reads "Send" (entrySeverity: 'major' ≥ subscription minSeverity: 'minor').
• Populated (long) — N/A; single-article seed; maxResults: 5 caps search.
• Error (recoverable) — N/A; no query.
• Error (unrecoverable) — no custom handler; render throw → Next default.
• Offline — N/A (server-rendered).
• Gated — no session → redirect('/unauthorized?reason=missing-session&returnTo=/help'); middleware blocks unauthenticated requests upstream.
• Standalone PWA — N/A; no manifest. (verify.)

Interactions#

• Summary tiles (styles.summaryItem × 3) — display-only (Search results / Tooltips / Changelog Send|Skip); not focusable, no telemetry.
• Help list items (styles.listItem — search results + editorial backlog)
  • Function: render-only; search rows show title + summary, backlog rows show missing-subject keys. No search input, article opener, or feedback form exists in code — the query is hard-coded; this is a read-only resolved view.
  • Keyboard: list is not interactive.
  • Screen reader: list semantics; <strong> titles.
  • Touch target: N/A.
  • Mobile (≤ 640 px): workspace.module.css list styling.
  • Disabled when: N/A.
  • Offline behavior: N/A.
  • Telemetry: None.

Data & contracts#

• Reads / pure-function calls (all from @oshun/tenant-console, hard-coded seed input, no BFF call):
  • searchHelp({ articles, query }) → ranked HelpArticle results for the viewer context.
  • resolveInProductHelp({ context, tooltips, walkthroughs, videos, articles }) → { tooltips, ... } applicable to surface /members.
  • aggregateFeedback([...]) → editorial backlog with missingSubjectCounts.
  • shouldDeliverChangelog({ subscription, entrySeverity, entryLocale }) → boolean (severity/locale gating).
• Writes: None. (No feedback-submit surface in code.)
• Realtime: None.
• Caching: SSR (dynamic; cookie read). Deterministic per tenant id.
• Auth/role check: middleware.ts + page getTenantServerSession() → canEnterTenantShell.

Cross-references#

• Domain logic: libs/oshun/tenant-console/src/help-center/index.ts (searchHelp, resolveInProductHelp, aggregateFeedback, shouldDeliverChangelog, HelpArticle).
• Workspace model: libs/oshun/navigation/src/tenant-ia.ts (help, group: configuration).
• Sibling routes: home.md, content.md, agents.md. /notifications (channel prefs + templates) lacks a file yet.

Open questions / known gaps#

• Articles, tooltips, query, and feedback are hard-coded seed data; no BFF read of the knowledge base or feedback write path is wired. Document the eventual content source and feedback-submit endpoint.
• No search input or article reader UI — the page renders a fixed precomputed query. Confirm interactive help search is a later phase.