Account – Knowledge bases

Route

• Path: /account/knowledge-bases
• Parent: README.md
• Children:
  • knowledge-base.md
• Status: Implemented (v1): global knowledge-base hub with workspace/group/status filters, card/table views, and shared table controls.

Purpose (business goal)

Provide an org-wide (cross-workspace) knowledge base finder so users can locate a specific KB and manage it efficiently.

This page lists all knowledge bases the user is authorized to access, across all workspaces they can view.

User roles & permissions

• Workspace Admin, Manager (edit), Analyst (read)
• Permissions: kb.view, kb.edit, kb.publish (TBD)

Reference: Roles & Permissions Model

Layout structure

• Merged top section: Title “Knowledge bases” + count badge with database icon. This top badge always shows the total number of knowledge bases available on the page, regardless of active filters.
• In the same top section, below the title row and with no divider, render a single PageListToolbar row (src/components/page-list-toolbar.tsx) with:
  • Left (filters slot):
    • One MultiSelectCombobox — “All workspaces” (with cards_star icon). When no workspaces are selected, show all knowledge bases from all workspaces (the page is the main hub of all existing KBs). When one or more workspaces are selected, show only KBs that belong to those workspaces (kb.workspaceId in the selected set). Empty selection = show all.
    • One “All groups” filter trigger (with stacks icon) for KB groups. This control is disabled until at least one workspace is selected so group names are not shown without workspace context. On hover/focus while disabled, show a tooltip explaining that the user must select one or more workspaces first. When the workspace selection changes, any previously selected KB groups are cleared.
    • One single-select KB status filter (Select) with options:
      1. All statuses (default)
      2. Incomplete
      3. Complete The status filter applies to both card and table views after workspace/group filters.
  • Middle (viewSwitcher slot): ViewSwitcherPill (card / table). View mode is persisted to localStorage under the key "knowledge-bases-view". Default is "card".
  • Right (actions slot): Primary CTA <Button asChild variant="default" className={PAGE_LIST_TOOLBAR_CTA_CLS}> wrapping a <Link> to the default workspace open page. Label: “Add knowledge base”. MVP: navigates to /account/workspaces/${DEFAULT_WORKSPACE_ID} so the user can add a KB there.
• Content: Either a card grid or a table depending on the active view. Data source: all knowledge bases from all existing workspaces (from the app’s KB store, e.g. WorkspacesContext.state.knowledgeBases), filtered by the “All workspaces” selection when the user has selected one or more workspaces.

View modes

Mode	Behaviour
Card view	Grid of Knowledge Base cards (see Component: Knowledge Base Card).
Table view	Single shadcn table with section header (title “Knowledge bases”, live count with database icon, column visibility icon). This section count reflects the currently visible filtered dataset. Columns are synchronized with card view: Name, Workspace, Group, Status, Linkage, Objectives, Documents. Column headers are sortable (click to toggle ascending/descending).

Table column visibility popover

The view_column icon button opens a popover listing all columns. Each column row uses a pill-style toggle switch (role="switch", size="sm") — not a checkbox — consistent with the Channels page ColumnVisibilityPopover. The first column (Name) is always visible and its toggle is disabled (opacity-60, pointer-events-none). Implementation: add a local Toggle component to knowledge-base-table.tsx matching the one in channels/page.tsx (same sm sizing and styling).

Navigation/entry points:

• Users can also access KBs from Workspace → Knowledge base (workspace-knowledge-base.md) and land here pre-filtered to a workspace (UX behavior TBD).

Components used

• Knowledge Base Card: Component: Knowledge Base Card — includes an overflow menu (three-dots on hover) with Edit, Set as default, Duplicate, and Delete actions. Delete is disabled when the workspace has only one KB. “Set as default” is disabled when the KB is already the workspace default.

States

• Empty: centered empty state with icon, title “No knowledge bases found”, and supportive body copy. When workspace/group/status filters are active, use a search-style empty state with a Clear filters action; otherwise use the database icon and onboarding-oriented copy.
• Loading: fetching KB list
• Error: permission denied / service unavailable
• Complete: list displayed

Business logic (high-level)

• Data source: The page must display all knowledge bases from all existing workspaces — i.e. the full list from the app’s KB store (e.g. useWorkspaces().state.knowledgeBases), not only seed data. This makes the page the main hub for all KBs.
• Workspace filter: When the user selects one or more workspaces in the “All workspaces” combobox, filter the displayed KBs to those whose workspaceId is in the selected set. When the selection is empty, show all KBs (no filter).
• KB status filter: All statuses shows all records; Incomplete and Complete restrict the list to KBs with matching status.
• KB publish boundary controls app behavior.
• Results must be constrained to workspaces the user is authorized to view/manage.
• KB card overflow menu actions: The card’s Edit action opens the Edit knowledge base dialog (title “Edit knowledge base”; fields: Name, Workspace, Group; footer Cancel / Save). On Save, the page calls updateKnowledgeBase(kb.id, { name, workspaceId }) and, if the selected workspace’s group was changed in the dialog, updateWorkspace(workspaceId, { groupId }), then closes the dialog. “Set as default” calls updateWorkspace(kb.workspaceId, { defaultKbId: kb.id }) to set this KB as the workspace’s default KB. Duplicate creates a new KB in the same workspace with name "{kb.name} (Copy)" via addKnowledgeBase. Delete removes the KB via deleteKnowledgeBase(kb.id) and is disabled when canDelete is false (workspace has only one KB — see business rule 7 in Default Workspace, Knowledge Base & Agent). canDelete is derived from the full (unfiltered) KB list so the count is accurate even when the workspace filter is active.

Table and card data parity

• Table and card views use the same core KB fields: Name, Workspace, Group, Status, Linkage, Objectives, Documents.
• Objectives are derived from kbDraft.objectivesVoice by counting filled Primary/Secondary objective fields (0..2), with fallback to kb.objectivesCount when draft data is unavailable.
• Documents come from kb.kbDocuments?.length with fallback to kb.documentsCount.

Domain refs: Domain: Knowledge Bases

API dependencies

• GET /knowledge-bases (supports filter params such as workspace_id where applicable) (TBD)
• POST /knowledge-bases

Enterprise constraints

• Knowledge bases are workspace-scoped and must not leak across workspaces/brands.
• Publishing may impact multiple apps (Comment Responder, Chatti Live); changes must be auditable.

Edge cases

• User has access to a subset of workspaces; ensure results reflect only authorized workspaces.
• Workspace has no KBs; prompt creation and explain activation dependency (TBD).
• Large KB counts; pagination/search performance constraints are TBD.

Security & compliance considerations

• Audit publish events

Reference: Security & Compliance

Analytics events (if applicable)

• kb.created
• kb.published

Reference: Analytics Events (MVP)