Knowledge Bases

Knowledge Bases are tenant-owned, independently published document collections. They are separate from Company Knowledge: Company Knowledge remains Topline's product memory and organizational context, while a Knowledge Base is a release-bound retrieval resource for people, applications, and approved agent harnesses.

Product flow

1. Open Knowledge Bases in the top-level rail.
2. Create a private draft. The new base opens on Overview, where the live release and any unpublished changes are shown separately.
3. Open Content, choose Add content, and import sanitized HTML, an HTML/Markdown/text file, one HTTPS page, a same-origin sitemap of up to 100 pages, or a ready bedrock_managed_kb source. URL and sitemap imports may refresh daily, weekly, or every 30 days. Every refresh creates draft changes; it never replaces the live release automatically. The import list shows durable progress and supports bounded retry.
4. The initial retrieval adapter requires every attached source to resolve to the same customer-owned Bedrock knowledge base and region; an ambiguous provider configuration fails closed. The control plane stores document metadata and s3:// content references, not the document body, in Postgres.
5. From Overview, validate the draft to create a candidate. The release freezes document identity, title, source reference and URL, source binding, content reference and integrity hash, sensitivity, freshness, citation, per-document access policy, audience, and provider configuration. Validation reads and hashes every release-bound object and runs a Bedrock retrieval smoke query whose result must resolve to a document in that candidate. Failed evidence remains visible and Retry validation reruns that exact candidate instead of creating a duplicate.
6. Open Quality to inspect complete added, changed, and removed document lists plus before/after audience and connection changes. Add representative retrieval questions, select their expected documents, and choose whether each test blocks publishing. A base may save up to 100 cases with at most 20 enabled, and only one bounded evaluation run may execute at a time. Disable an enabled test to free an execution slot; delete an obsolete disabled test to free a saved-test slot. Prior run results keep their recorded case IDs after deletion. Required tests must pass for that exact candidate; optional failures remain visible without becoming a gate. A failed run shows expected versus retrieved documents and coverage per question.
7. Review and publish the validated candidate. The current live pointer changes atomically; the prior active release is retained.
8. Open Connections to choose the HTML endpoint audience and approve exact grants for a workspace, one conversation's AgentCore runtime, an artifact app, or a service client. Workspace and app pickers use their visible names; runtime and service-client IDs stay in the advanced connection paths.

Document-level access

Each draft document defaults to All approved connections. During ingestion, an owner may explicitly choose Only selected connections, which requires at least one exact connection. The Content inventory names those connections and provides a draft-only edit action. That allowlist is frozen into the release beside the content hash and is enforced after base authorization for browse, search, and fetch. Provider search results are post-filtered against both release membership and the frozen document policy; fetching a hidden document returns the same not-found result as an unknown document.

Account readers may still inspect policies in the management UI. Anonymous and external OAuth consumers see only documents open to all approved connections. A public candidate cannot contain a connection-restricted document. Revoking a connection immediately removes its base grant, while policy edits remain draft-only until a new release is published.

External MCP with OAuth

The External MCP card exposes https://<topline-host>/knowledge/<slug>/mcp. Compatible clients discover protected-resource metadata at /.well-known/oauth-protected-resource/knowledge/<slug>/mcp, register a public client, and complete OAuth 2.1 authorization-code flow with PKCE S256 and the exact MCP resource indicator.

Supported scopes are knowledge:list, knowledge:search, and knowledge:fetch. Access and refresh tokens are hashed at rest, tenant-bound, resource-bound, revocable, and refresh tokens rotate. A token issued for one Knowledge Base is rejected at another base even within the same account. Internal Topline/AgentCore projection continues to use short-lived binding grants; external OAuth supplements that path and does not widen an internal binding.

The tenant-bound OAuth migration revokes pre-existing MCP OAuth grants whose tenant ownership was not recorded. Those clients must authorize once more; the migration never guesses an account for a legacy token.

Use a Knowledge Base in chat

In a workspace chat or thread, type @ and choose a Knowledge Base from the Knowledge Bases section. The same choices are available from Add > Attach a resource. Topline shows only live bases already granted to that workspace or conversation. Choosing one inserts its readable name into the message and adds a removable Knowledge Base chip labeled as knowledge for that message.

The chip is structured turn context, not a permission grant. Topline revalidates it when the message is sent; a revoked, paused, archived, unpublished, cross-tenant, or otherwise unavailable base is rejected with a visible remove-and-retry message. For that turn, AgentCore receives tools only for the selected base or bases. When no Knowledge Base is explicitly selected, the existing seamless behavior remains: AgentCore receives all live bases already granted to the conversation or workspace.

Selecting a Knowledge Base addresses the Topline orchestrator. It is removed if the composer is redirected to an active Coding agent, because Coding tasks use the workspace grants captured when that task starts rather than chat-turn mentions.

Cookbook: attach a Knowledge Base to an AgentCore harness

Suppose the Field Operations workspace already has an AgentCore-backed chat and the Field manuals Knowledge Base has a live release. The goal is to let that workspace search and read the manuals without giving the model a tenant ID, provider configuration, bearer token, or storage reference.

1. Open Knowledge Bases > Field manuals > Connections and choose Add connection.
2. Set Connect to to Workspace, choose Field Operations, and name the connection Field operations assistant.
3. Under Allowed operations, enable Search and Read. Leave Browse disabled unless the assistant must enumerate the entire release.
4. Choose Approve connection. This changes the next release only; it does not expand the currently published AgentCore grant.
5. Return to Overview, choose Validate draft, and wait for validation to pass.
6. Choose Review & publish. Confirm that the frozen review shows the expected connection count, documents, sensitivity, sources, and audience, then publish the candidate.
7. Open a chat in Field Operations. No MCP URL, token, or AgentCore environment variable needs to be copied. Topline projects a remote MCP server named knowledge_field-manuals into the harness with only the approved operations.

For example, the operator can send:

@Field manuals What eye protection is required before servicing a line?

The mention narrows that turn to Field manuals. The harness may first call:

@knowledge_field-manuals/search_knowledge_base
{"query":"eye protection before servicing a line","limit":5}

If the answer needs the full cited procedure, it may follow with the opaque document ID returned by search:

@knowledge_field-manuals/fetch_knowledge_document
{"documentId":"kbd_exampleOpaqueId"}

The model receives release-bound results and citations, not the provider or storage configuration. Without an explicit @ selection, the workspace's live Knowledge Base grants remain available automatically. Selecting a base only narrows the set; it never creates or expands a grant.

To limit access to one conversation instead of the whole workspace, use the advanced AgentCore runtime connection with that exact Topline conversation identity. Do not enter an AgentCore Runtime ARN, session ID, tenant ID, or a value inferred from logs. Publish a new candidate after approving the connection. A connection created after candidate validation is not part of that frozen candidate and remains unavailable until a later candidate containing it is published.

Verification is intentionally observable:

• In Connections, the live release and next-release audience remain distinct.
• In the publish review, Connections reports the frozen approved count.
• In chat, typing @ shows Field manuals only after the published grant is live for that workspace or conversation.
• Revoking the connection removes it from harness projection immediately and invalidates older signed grants.
• Pausing or archiving the Knowledge Base disables both its endpoint and AgentCore tools.

Draft changes never alter a live release. A draft/index/provider failure leaves the last known-good release online unless an operator paused or archived the base. Publish and rollback rotate all enabled binding generations, rollback reactivates one retained release, and pause/archive fail closed so existing bearer grants stop working.

Detaching a source is an urgent revocation: the base pauses, affected draft documents are tombstoned, and grants rotate immediately. An operator may then build and publish a clean release while delivery remains paused, followed by an explicit resume. Restoring an archived base returns an existing published base to paused state rather than silently making it live.

Delivery routes

For a base with slug field-manuals:

GET  /knowledge/field-manuals/
GET  /knowledge/field-manuals/search?q=term
GET  /knowledge/field-manuals/documents/{opaqueDocumentId}
GET  /knowledge/field-manuals/versions/{version}/
GET  /knowledge/field-manuals/manifest.json
POST /knowledge/field-manuals/mcp

The HTML routes are server rendered and work without JavaScript. Private mode permits a tenant reader or an exact signed grant. Selected mode requires an exact signed grant. Anonymous delivery is accepted only when the release was explicitly published as public. MCP requires either a short-lived internal binding grant or a standards-native OAuth bearer token bound to that exact MCP resource. The server exposes only the operations represented by the binding or OAuth scopes.

HTML responses include immutable release version, ETag, Last-Modified, manifest discovery, noindex, stable document data IDs, citations, and freshness metadata. Registered HTML is size-limited and allowlist-sanitized; scripts, forms, frames, embedded media, inline handlers, and unsafe URLs are removed. Public requests are limited to 60 operations per minute and authenticated consumers to 240, scoped independently by tenant, base, consumer, and operation.

Stable responses use opaque kb_... and kbd_... identifiers. They do not return tenant IDs, database UUIDs, Bedrock IDs, regions, S3 paths, signed object URLs, or credentials.

Canonical read tools

All consumers call one release-aware service:

• list_knowledge_documents
• search_knowledge_base
• fetch_knowledge_document

Search results are filtered against the active release membership before they are returned. Fetch reads the immutable content reference captured by that release. A provider result for another base or release is discarded.

Workspace and conversation grants are projected into Topline AgentCore as a separate per-base remote MCP server named knowledge_{slug}. Coding tasks receive the same server only when their workspace grant was present when the task started. An empty tool allowlist suppresses these servers.

An explicit chat mention narrows this projection for one turn. The server stores the selected opaque public IDs in the user message's source metadata after validating them; it never treats mention prose or a client-supplied ID as authority.

Artifact apps

Normal artifact apps may declare:

{
  "knowledgeBases": [
    {
      "alias": "manuals",
      "knowledgeBaseId": "kb_7Kp3qV9mN2xR5tY8",
      "release": "current_published",
      "operations": ["list", "search", "fetch"]
    }
  ]
}

The artifact must already have an enabled exact artifact_app grant for that opaque base ID. Deployment validation rejects missing, stale, cross-tenant, non-live, or operation-expanded bindings. At runtime the artifact uses these platform routes:

GET /_artifact/knowledge/manuals
GET /_artifact/knowledge/manuals/search?q=term
GET /_artifact/knowledge/manuals/documents/{opaqueDocumentId}

The platform broker applies artifact viewer authorization and the base delivery policy, then calls the canonical service as that artifact. It never forwards a KB bearer token or provider/storage identifier to browser JavaScript. Hosted MCP artifacts cannot declare knowledgeBases; machine-ingress artifacts remain isolated from Topline-owned data.

Example: private manual finder

Create or identify the artifact first, then use Knowledge Bases > Connections > Add connection to choose the app by name and approve its exact artifact_app grant. That approval is draft-only. Create and validate a fresh Knowledge Base candidate after the approval, confirm the artifact appears in the candidate's frozen connection review, and publish that version before validating or deploying the artifact. Never reuse a candidate created before the connection. The manifest may request only operations included in the published grant. Use the opaque kb_... public ID supplied by the authorized Knowledge Base workflow; never derive it from the slug, HTML endpoint, tenant, database, or provider configuration.

The app calls the broker relatively so draft, version, live, and custom-domain routing remain intact:

async function searchManuals(query) {
  const response = await fetch(
    `./_artifact/knowledge/manuals/search?q=${encodeURIComponent(query.trim())}`,
    { cache: "no-store" },
  );
  if (!response.ok) throw new Error(`manual_search_${response.status}`);
  return response.json();
}

async function fetchManual(documentId) {
  const response = await fetch(
    `./_artifact/knowledge/manuals/documents/${encodeURIComponent(documentId)}`,
    { cache: "no-store" },
  );
  if (!response.ok) throw new Error(`manual_fetch_${response.status}`);
  return response.json();
}

Validate an empty query in the browser. Treat 403 or 404 as an unavailable release, delivery policy, or exact grant; treat 429 as a bounded retry; and preserve the last successful view for 502 or 503. Never fall back to hardcoded documents, Company Knowledge, the public /knowledge/<slug> endpoint, or a model-generated answer.

The Build skill contains the complete knowledge-base-backed-app worked example, including manifest shape, safe rendering, tests, revocation smoke, and the hosted-MCP boundary.

Existing Bedrock connector reconciliation

bedrock_managed_kb remains the provisioning and provider-health adapter. A source and its connection hold the customer-owned Bedrock configuration. A Knowledge Base attachment references that source and snapshots a minimal server-only provider configuration into each release.

This implementation does not provision or migrate AWS resources. Existing connectors can be attached to new private drafts without changing their Bedrock knowledge base or data source. Customer-account and region selection remain explicit and fail closed. A future migration may create private draft records for existing connectors, but it must not publish them automatically.

Audit, usage, and billing

Creation, edits, source attachment, document indexing, candidate validation, publish, rollback, grant approval/revocation, pause, and archive write immutable business-audit records. Read events record tenant, base, release, binding/grant/subject, consumer, operation, duration, result count, provider request IDs, outcome, and an optional query hash. Raw queries and document bodies are not written to audit records.

Provider cost and customer charge are nullable. New events start with reconciliation_status = unpriced; unknown cost is never treated as zero. Reconciliation and pricing decisions are separate rollout work.

Operational boundaries

• Source integration, shared Topline deployment, AWS/customer-runtime changes, and customer rollout are separate operations.
• This code path uses the configured Topline object-storage bucket for registered HTML. It does not create a customer bucket or Bedrock resource.
• No deployment or customer rollout is implied by merging these source changes.
• Public delivery has a bounded application-layer rate limit, but public-mode customer rollout should remain disabled operationally until takedown, caching, monitoring, and abuse-response procedures have separate approval.