First Class Modules
Knowledge finder
Search accessible Knowledge Core articles, filter publication state, preview current text, and open the native article page.
module.knowledge-finderUse Knowledge finder for everyday article lookup. This read-only view does not create, edit, publish, archive, or remove articles; Open article takes you to the native Knowledge Core page for those separately authorized actions.
The bundled renderer key is module.knowledge-finder. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.
What it does
Search accessible Knowledge Core articles, filter publication state, preview current text, and open the native article page.
Key capabilities
- Enter a search and choose All accessible articles, Published, Draft, or Archived in Publication state, then select Search articles.
- Use Previous article page and Next article page to browse the applied search and publication-state filter.
- Preview an article to read its current publication state, authority level, revision, summary, and article text.
- Draft and archived previews explicitly say they are unavailable as published citations. Selecting a filter never grants access to those articles.
- Open article resolves the record's persisted native page choices. If no destination is available, use the displayed unavailable-state guidance rather than guessing a route.
- Try again retries the failed search page or article preview using current permissions.
Common uses
- Find an operating procedure by its title or search text.
- Review an accessible draft before opening Knowledge Core.
- Check an article's current revision and publication state.
How it connects
Knowledge finder uses the existing secured Knowledge Core list and detail services. It displays the current article text and opens the same canonical record in its owning page; it does not generate AI answers or queue indexing.
Where applicable, its records use the universal RecordId conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.
Security and data boundary
The verified user, tenant organization, SaaS app, and persisted page identity determine the current request. Knowledge Core applies its record, Personal ownership, DataRole, location, private-record, and action-specific permissions. Search terms, publication filters, menu labels, and client-supplied IDs are query targets, never authorization proof.
- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.
Add it to an app
- Add the validated
module.knowledge-finderblock to an active, entitled published page. - Reuse the page across UserType menus with the labels each audience needs.
- Ensure the intended native Knowledge Core pages are associated with their records, then test the Open article choices.
- Test empty, loading, retry, page navigation, preview, and denied access with representative users, including the distinction between readable drafts and published citations.
Build a professional Knowledge finder dashboard
These six registry-backed presentation blocks let a designer turn the secured Knowledge finder API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at /api/modules/knowledge-articles; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.
The ZIP contains this feature's fictional design composition at pages/first-class/knowledge-finder-sample.json, its executable authenticated page at pages/first-class/knowledge-finder-live.json, and the catalog-driven FirstClassPresentationGallery.tsx. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.
| Payload kind | Runtime block | Useful Knowledge finder projection |
|---|---|---|
metric-set | core.metric-strip | Published, draft, due-review, stale, and gap counts |
entity-list | core.entity-list | Important articles, owners, freshness, and use |
progress-list | core.progress-list | Distribution by freshness, lifecycle, category, or owner |
series-chart | core.series-chart | Draft, publish, review, use, and gap activity |
data-grid | core.presentation-grid | One bounded article page with lifecycle evidence |
timeline | core.timeline | Revision, publication, review, retrieval, feedback, gap, and archive |
Copy/paste design preview: all six blocks
This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.
Copy the complete six-block page JSON
{
"blocks": [
{
"_id": "knowledge-finder-metrics",
"_type": "core.metric-strip",
"props": {
"title": "Knowledge finder",
"asOfUtc": "2026-09-04T18:00:00Z",
"items": [
{
"key": "published",
"label": "Published",
"value": 684,
"format": "number",
"tone": "success"
},
{
"key": "review",
"label": "Review due",
"value": 31,
"format": "number",
"tone": "warning"
},
{
"key": "draft",
"label": "Drafts",
"value": 24,
"format": "number",
"tone": "neutral"
},
{
"key": "gaps",
"label": "Open gaps",
"value": 12,
"format": "number",
"tone": "danger"
}
]
},
"children": []
},
{
"_id": "knowledge-finder-recent",
"_type": "core.entity-list",
"props": {
"title": "Knowledge needing attention",
"hasMore": true,
"items": [
{
"id": "knowledge-finder-sample-1",
"recordId": "knowledge-finder-record-1",
"primary": "Escalation playbook",
"secondary": "Support operations - owner: Maya Chen",
"status": {
"key": "review-due",
"label": "Review due",
"tone": "warning"
},
"trailing": "14 uses"
},
{
"id": "knowledge-finder-sample-2",
"recordId": "knowledge-finder-record-2",
"primary": "Escalation playbook - Follow-up",
"secondary": "Support operations - owner: Maya Chen - Updated two hours ago by the assigned owner",
"status": {
"key": "in-review",
"label": "In review",
"tone": "primary"
},
"trailing": "Today"
},
{
"id": "knowledge-finder-sample-3",
"recordId": "knowledge-finder-record-3",
"primary": "Escalation playbook - West region",
"secondary": "Support operations - owner: Maya Chen - Related to three visible records at the Reno location",
"status": {
"key": "on-track",
"label": "On track",
"tone": "success"
},
"trailing": "3 related"
},
{
"id": "knowledge-finder-sample-4",
"recordId": "knowledge-finder-record-4",
"primary": "Escalation playbook - Customer response",
"secondary": "Support operations - owner: Maya Chen - Waiting for an external response before work can continue",
"status": {
"key": "scheduled",
"label": "Scheduled",
"tone": "warning"
},
"trailing": "Tomorrow"
},
{
"id": "knowledge-finder-sample-5",
"recordId": "knowledge-finder-record-5",
"primary": "Escalation playbook - Regional operations review with a deliberately long title",
"secondary": "Support operations - owner: Maya Chen - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
"status": {
"key": "needs-attention",
"label": "Needs attention",
"tone": "danger"
},
"trailing": "Review",
"tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
},
{
"id": "knowledge-finder-sample-6",
"recordId": "knowledge-finder-record-6",
"primary": "Escalation playbook - Completed preview",
"secondary": "Support operations - owner: Maya Chen - Closed after review with its related evidence retained",
"status": {
"key": "complete",
"label": "Complete",
"tone": "success"
},
"trailing": "Closed"
}
]
},
"children": []
},
{
"_id": "knowledge-finder-bystatus",
"_type": "core.progress-list",
"props": {
"title": "Knowledge freshness",
"items": [
{
"key": "current",
"label": "Current",
"value": 611,
"maximum": 684,
"displayValue": "611",
"tone": "success",
"status": {
"key": "current",
"label": "Current",
"tone": "success"
}
},
{
"key": "due",
"label": "Due soon",
"value": 42,
"maximum": 684,
"displayValue": "42",
"tone": "warning",
"status": {
"key": "due",
"label": "Due soon",
"tone": "warning"
}
},
{
"key": "stale",
"label": "Stale",
"value": 31,
"maximum": 684,
"displayValue": "31",
"tone": "danger",
"status": {
"key": "stale",
"label": "Stale",
"tone": "danger"
}
}
]
},
"children": []
},
{
"_id": "knowledge-finder-trend",
"_type": "core.series-chart",
"props": {
"title": "Knowledge lifecycle",
"variant": "bar",
"defaultPeriodKey": "d7",
"periods": [
{
"key": "d7",
"label": "7 days",
"labels": [
"Fri",
"Sat",
"Sun",
"Mon",
"Tue",
"Wed",
"Thu"
],
"series": [
{
"key": "primary",
"label": "Published",
"tone": "primary",
"values": [
8,
5,
4,
12,
15,
11,
17
]
},
{
"key": "secondary",
"label": "Reviewed",
"tone": "success",
"values": [
6,
4,
3,
9,
12,
10,
14
]
}
]
}
]
},
"children": []
},
{
"_id": "knowledge-finder-table",
"_type": "core.presentation-grid",
"props": {
"title": "Authorized knowledge",
"columns": [
{
"key": "article",
"label": "Article",
"type": "text",
"align": "left"
},
{
"key": "owner",
"label": "Owner",
"type": "text",
"align": "left"
},
{
"key": "freshness",
"label": "Freshness",
"type": "status",
"align": "left"
},
{
"key": "uses",
"label": "Uses",
"type": "number",
"align": "right"
},
{
"key": "review",
"label": "Next review",
"type": "date",
"align": "left"
}
],
"rows": [
{
"id": "knowledge-finder-row-1",
"recordId": "knowledge-finder-record-1",
"cells": {
"article": "Escalation playbook",
"owner": "Maya Chen",
"freshness": {
"key": "due",
"label": "Review due",
"tone": "warning"
},
"uses": 14,
"review": "2026-09-10T00:00:00Z"
}
},
{
"id": "knowledge-finder-row-2",
"recordId": "knowledge-finder-record-2",
"cells": {
"article": "Escalation playbook - Follow-up",
"owner": "Maya Chen",
"freshness": {
"key": "in-review",
"label": "In review",
"tone": "primary"
},
"uses": 15,
"review": "2026-09-04T15:42:00Z"
}
},
{
"id": "knowledge-finder-row-3",
"recordId": "knowledge-finder-record-3",
"cells": {
"article": "Escalation playbook - West region",
"owner": "Maya Chen",
"freshness": {
"key": "on-track",
"label": "On track",
"tone": "success"
},
"uses": 16,
"review": "2026-09-04T12:18:00Z"
}
},
{
"id": "knowledge-finder-row-4",
"recordId": "knowledge-finder-record-4",
"cells": {
"article": "Escalation playbook - Customer response",
"owner": "Maya Chen",
"freshness": {
"key": "scheduled",
"label": "Scheduled",
"tone": "warning"
},
"uses": 17,
"review": "2026-09-03T21:07:00Z"
}
},
{
"id": "knowledge-finder-row-5",
"recordId": "knowledge-finder-record-5",
"cells": {
"article": "Escalation playbook - Regional operations review with a deliberately long title",
"owner": "Maya Chen - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
"freshness": {
"key": "needs-attention",
"label": "Needs attention",
"tone": "danger"
},
"uses": 18,
"review": "2026-09-03T16:31:00Z"
}
},
{
"id": "knowledge-finder-row-6",
"recordId": "knowledge-finder-record-6",
"cells": {
"article": "Escalation playbook - Completed preview",
"owner": "Maya Chen",
"freshness": {
"key": "complete",
"label": "Complete",
"tone": "success"
},
"uses": 19,
"review": "2026-09-02T19:14:00Z"
}
}
],
"page": {
"pageNumber": 1,
"pageSize": 6,
"totalRecords": 684,
"totalIsExact": true,
"hasMore": true
}
},
"children": []
},
{
"_id": "knowledge-finder-timeline",
"_type": "core.timeline",
"props": {
"title": "Knowledge activity",
"hasMore": true,
"items": [
{
"id": "knowledge-finder-event-1",
"recordId": "knowledge-finder-record-1",
"occurredUtc": "2026-09-04T17:58:00Z",
"title": "Review requested",
"description": "Escalation playbook entered its scheduled review window.",
"actor": "Knowledge Core",
"tone": "warning"
},
{
"id": "knowledge-finder-event-2",
"recordId": "knowledge-finder-record-2",
"occurredUtc": "2026-09-04T15:42:00Z",
"title": "Review requested - Follow-up",
"description": "Escalation playbook entered its scheduled review window. Updated two hours ago by the assigned owner.",
"actor": "Avery Patel",
"tone": "primary"
},
{
"id": "knowledge-finder-event-3",
"recordId": "knowledge-finder-record-3",
"occurredUtc": "2026-09-04T12:18:00Z",
"title": "Review requested - West region",
"description": "Escalation playbook entered its scheduled review window. Related to three visible records at the Reno location.",
"actor": "Sam Rivera",
"tone": "success"
},
{
"id": "knowledge-finder-event-4",
"recordId": "knowledge-finder-record-4",
"occurredUtc": "2026-09-03T21:07:00Z",
"title": "Review requested - Customer response",
"description": "Escalation playbook entered its scheduled review window. Waiting for an external response before work can continue.",
"actor": "Maya Chen",
"tone": "warning"
},
{
"id": "knowledge-finder-event-5",
"recordId": "knowledge-finder-record-5",
"occurredUtc": "2026-09-03T16:31:00Z",
"title": "Review requested - Regional operations review with a deliberately long title",
"description": "Escalation playbook entered its scheduled review window. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
"actor": "Automation",
"tone": "danger"
},
{
"id": "knowledge-finder-event-6",
"recordId": "knowledge-finder-record-6",
"occurredUtc": "2026-09-02T19:14:00Z",
"title": "Review requested - Completed preview",
"description": "Escalation playbook entered its scheduled review window. Closed after review with its related evidence retained.",
"actor": "Jordan Lee",
"tone": "success"
}
]
},
"children": []
}
]
}Copy/paste React composition
Copy InteractivePresentationComponents.tsx and its optional CSS from the Professional Foundation Developer Kit, then add this module-specific composition. It is semantic and unstyled by default; pass styled after importing interactive-presentation-components.css for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.
import {
EntityList,
MetricStrip,
PresentationGrid,
ProgressList,
SeriesChart,
Timeline,
} from "./InteractivePresentationComponents";
export interface KnowledgeFinderPresentationData {
readonly metrics: unknown;
readonly recent: unknown;
readonly byStatus: unknown;
readonly trend: unknown;
readonly table: unknown;
readonly timeline: unknown;
}
export interface KnowledgeFinderPresentationProps {
/** Pass only the already-authorized presentation document returned by the API. */
readonly data?: KnowledgeFinderPresentationData | null;
readonly loading?: boolean;
readonly error?: boolean;
readonly styled?: boolean;
/** Record identity is navigation context; the detail API must authorize it again. */
readonly onOpenRecord?: (recordId: string) => void;
}
export function KnowledgeFinderPresentation({
data,
loading = false,
error = false,
styled = false,
onOpenRecord,
}: KnowledgeFinderPresentationProps) {
if (error) return <p role="alert">The Knowledge finder presentation could not be loaded.</p>;
if (loading || !data) return <p role="status">Loading Knowledge finder presentation...</p>;
return (
<main className={styled ? "bwhq-api-example" : undefined}>
<header>
<p>Knowledge finder</p>
<h1>Knowledge finder</h1>
<p>Fictional article-discovery design data; the live page searches accessible articles and opens their native owner.</p>
</header>
<MetricStrip data={data.metrics} styled={styled} />
<div className={styled ? "bwhq-api-example__split" : undefined}>
<ProgressList data={data.byStatus} styled={styled} />
<EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
</div>
<SeriesChart data={data.trend} styled={styled} />
<PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
<Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
</main>
);
}Copy the live, authenticated module page
This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls /api/modules/knowledge-articles, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.
Copy the executable live page
{
"blocks": [
{
"_id": "knowledge-finder-live",
"_type": "module.knowledge-finder",
"props": {},
"children": []
}
]
}The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.
Keep article lifecycle work in Knowledge Core. This search page is not an AI answer, and an accessible draft is not automatically eligible for a published citation.
A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.
Capability review: 2026-09-14. For exact current technical availability, use the generated API Map and first-class module inventory.