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.
3. Attach one or more ready bedrock_managed_kb sources. 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.
4. Register sanitized HTML documents. The control plane stores metadata and s3:// content references; it does not store the document body in Postgres.
5. Create a candidate. The release freezes document identity, title, source reference and URL, source binding, content reference and integrity hash, sensitivity, freshness, citation, 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.
6. Publish the validated candidate. The current live pointer changes atomically; the prior active release is retained.
7. Approve exact grants for a workspace, one conversation's AgentCore runtime, an artifact app, or a service client.

Use a Knowledge Base in chat

In a workspace chat or thread, type @ and choose a Knowledge Base from the Knowledge Bases section. 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 to the composer.

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.

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 always requires a short-lived signed grant and exposes only the operations approved for that grant.

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_field_manuals",
      "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.

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.