# Knowledge Base Setup And Publication Governance > Canonical path: `specs/kb/setup-publication-governance.md` > Status: living product and architecture spec > Scope: Draft/Official publication, recoverable KB setup, generated Wiki requests, Uploaded UA setup, and publication approval. ## 1. Purpose Knowledge Base setup is a recoverable editing workflow for assembling one or more Sources and preparing their optional artifacts before the KB becomes workspace-official knowledge. It extends the KB product model; it does not turn a KB into an AGS repository or replace Group and Tag taxonomy. The workflow has five steps: 1. Basic info 2. Sources 3. Wiki 4. Dashboard 5. Review The same components edit a Draft and an isolated working revision of an Official KB. Normal KB reading continues to use the existing Overview, Browse, Documents, Dashboard, Automation, and Settings surfaces. ## 2. Publication Model Every active KB has one publication state: - `draft`: the working KB revision has not been approved as workspace-official knowledge; - `official`: an immutable published revision is the current reader-visible revision. Publication is independent of Group, Tags, and activity state but intentionally narrows visibility while the KB is Draft. Group and Tags continue to organize the collection. `Official` is the workspace-public reader state: KB grants and source-repository authorization still apply to every Official list, read, preview, and retrieval operation. `Draft` is visible only to the KB owner, explicit human `manage` or `edit` Maintainers, and workspace/organization administrators. Workspace-member defaults, human `view` or `none` grants, and agent grants are ignored until publication makes the KB Official again. A setup session identifies: - the KB and workspace; - mode: `create_draft` or `edit_official`; - working revision and, for Official editing, the current published revision; - active step used to resume the workflow; - an exact version used to reject stale cross-device mutations; - the last confirmed updater and timestamp. Step readiness is a projection over durable KB, Source, Source revision, artifact, request, and approval facts. It is not a second persisted truth. ### 2.1 Draft creation Choosing Add immediately starts setup: it atomically creates an untitled Draft KB visible only to its creator, explicitly added Maintainers, and workspace/organization administrators, its creator Owner grant, and a setup session, then opens the Basic info step in the edit-mode dialog. Basic information is edited in that recoverable workflow rather than in a separate creation form. A Draft can be left and resumed. Server-confirmed state is authoritative after refresh or on another device. Draft deletion remains available through the normal KB settings surface; the setup editor does not expose a destructive deletion action. ### 2.2 Official editing The KB owner, or a workspace or organization owner/admin with implicit KB `manage`, may start an Official edit. An ordinary KB manager without that governance authority may not. The server creates an isolated working revision from the published revision. Readers continue to see the previous published revision until the replacement is atomically saved from Review. ### 2.3 Official-to-Draft conversion A workspace or organization owner/admin has implicit KB `manage` and may convert an active Official KB to Draft after explicit confirmation. Ordinary KB owners and managers without workspace-level governance authority may not run this transition. The server atomically removes the reader-visible Official, clears its published pointer, creates a fresh working revision from the current Official state, and resets the recoverable setup session to `create_draft`. The action therefore also works for legacy Official rows that do not have a published-revision pointer. Conversion immediately removes the KB from default Knowledge Q&A and Official reader scope and hides it from ordinary members and view-only grantees. Existing `manage` and `edit` Maintainers may continue collaborating through the normal Draft setup flow; it becomes Official again only after the new exact revision passes publication approval. An incomplete legacy Official editor is replaced rather than merging hidden working metadata into the new Draft. The confirmation must explain the temporary reader impact, and the transition writes an audit event. Normal metadata and collection-classification mutations must not bypass this workflow for an Official KB. Name, Description, Group, and Tags change only in the isolated Official working revision or after a confirmed conversion to Draft. Adding or removing a Source mutates managed repositories and is not undone by leaving setup. Destructive actions require confirmation and an audit event. ## 3. Navigation And Collection The Knowledge secondary sidebar keeps these workspace entries: - Knowledge Q&A; - the existing Activity entry; - Official KBs; - a Draft section that is collapsed by default, displays the total visible Draft count, and shows at most the five most recently updated Drafts when expanded; - recent Knowledge Q&A threads. The Draft section provides a View all action that opens the collection filtered to Draft KBs. Existing per-KB permission management remains in Settings; the Maintainers field in setup is a focused projection of those grants, not a replacement permission surface. Approval state and actions do not depend on an Activity inbox. Official/Draft is the first collection partition; Group shelves and Tag filters remain available within each partition. Draft and Official rows both open the normal reader workbench. A manager enters or resumes setup through the workbench's edit-mode action; Draft rows no longer open the setup workflow implicitly. Only Official KBs that pass current KB and source authorization enter the default Knowledge Q&A scope; Drafts may be selected only through an explicitly defined and authorized scope. Setup uses a focused modal editor over the normal reader workbench. Its compact step rail keeps one active step at a time; ready steps remain available for review or editing. Basic information saves automatically, but readiness does not advance the editor away from Basic info; moving to the next step is explicit. The active step remains in the setup session and route so reloads and deep links resume the same modal context. Closing the editor returns to the reader workbench and refreshes the KB detail and overview projections, so newly available Documents, Dashboard, Browse, or Automation tabs appear without a page reload. The same step list is available at every viewport width and collapses above the editor content on narrow viewports. ## 4. Basic Info Basic info includes: - required Name; - Description; - required Group; - Tags; - Maintainers, projected from existing `manage` and `edit` KB grants. Owner transfer is not part of setup. Maintainers must not create a parallel role table. Editable fields save individually or in small bounded batches. UI may display `saving`, `saved`, or `failed` only from the corresponding server result. A failed value remains visibly unsaved and must not overwrite the confirmed value in other surfaces. Setup-session and field mutations use optimistic version fences. ## 5. Sources Sources render as one vertical list. Every source row contains its name, type or provider, remote/ref summary, usability, import progress, retry, and permitted removal actions. Import progress remains the existing source-scoped projection and is not copied into setup state. The final row is always Add source. It exposes the existing New repository, Import repository, and Import data source flows. These creation actions exist only in edit mode; the normal reader Overview shows the resulting source list without repository or data-source creation entry points. Selecting one opens a secondary page inside the setup editor, while the step rail remains visible but disabled. The secondary page owns one scrollable form and one footer with Back to sources and Add source actions; it must not open another modal above setup. A successful addition returns to Sources, renders the new source as a normal row, and leaves Add source as the final row. Removal retains the managed repository lifecycle contract: delete managed AGS repositories before deleting MeshX metadata, retain metadata and mappings when an external deletion fails, and record compensation state when persistence fails after an external mutation. The Sources step is ready when there is at least one required Source and every required import phase is usable. Optional Wiki or Dashboard failure, skip, or absence never changes Source usability. ## 6. Wiki Wiki is an optional, Source-scoped generated artifact. Its request lifecycle is: ```text not_requested -> pending_approval -> queued -> running -> ready | | | v | v rejected | failed pending_approval -> withdrawn | pending_approval -> stale <-------------+ not_requested/rejected/failed -> skipped ``` A Member with KB edit access submits a `kb_wiki_generation` approval subject. The frozen payload contains at least workspace, KB, Source, source revision, scope, language, reason, requester, payload digest, and idempotency key. An open approval is the authority for `pending_approval`; it must not be duplicated as an unrelated KB publication state. The Source Wiki setup page owns request submission, pending state, withdrawal, rejection reason, Admin decision controls, generation progress, retry, and Preview. Approval only enqueues a generation job; it does not mean Wiki content is ready. A Workspace owner/admin who has the required KB access may directly request Wiki generation without creating an approval instance. Direct execution and approved execution use the same revision-fenced generation service. When the source revision changes, an open or approved request for the prior revision becomes stale and cannot publish. Failed, rejected, stale, or skipped Wiki state does not make the Source unusable. `ready` previews the existing source-scoped Documents/Wiki route under its normal authorization checks. ## 7. Uploaded UA Dashboard Dashboard retains the Uploaded Understand Anything contract. It is a human-uploaded `.zip`, `.tar.gz`, or `.tgz` archive; it is not generated by a model and does not create a Dashboard approval instance or durable generation job. Per-Source setup state is derived as `empty`, synchronous `uploading`, `ready`, `reimport_required`, or explicit `skipped`: - Members see a disabled future approval affordance and may only skip; - a Workspace owner/admin with required KB access may directly import or replace the archive; - `ready` previews the existing source-scoped Dashboard reader; - import failure and skip do not change Source usability. `uploading` describes only the current request/browser transfer. Durable truth starts with the atomically published Source revision metadata defined by `uploaded-ua-dashboard.md`. When direct import is unavailable, the Dashboard row is visually muted while the explicit Skip action remains available. ## 8. Review And Approval Draft Review summarizes Basic info, Source readiness, Wiki and Dashboard states, skipped artifacts, and warnings. Submitting creates a `kb_publication` approval bound to the exact working revision and payload digest. Submission freezes the review payload; later mutations cannot be silently included in that approval. The Review page owns pending state, request identity, applicant, timestamps, assigned approvers, withdrawal, Admin approve/reject controls, rejection reason, stale state, and publication success. Rejection requires a reason and returns the Draft to editable state. Approval atomically publishes the frozen revision and moves the KB to Official. Request withdrawal is visually separated from the grouped approve/reject decision controls, with the primary approval action kept at the end of the decision group. Official Review shows the delta from the current published revision. The KB owner, or an authorized Workspace/organization owner/admin, atomically saves the working revision as the new Official revision without creating a second approval. The save is bound to the exact Review content digest in addition to the setup version and revision pointers, so concurrent Source or artifact changes must be reviewed before retry. Failure leaves the previous Official revision reader-visible. An administrator may instead run the distinct Official-to-Draft transition. That action creates a new Draft Review rather than a privileged direct-save Review. The converted KB follows the same exact-revision publication approval contract as every other Draft; there is no reader-visible Official fallback while it is being revised. ## 9. Approval And Authorization Contract KB governance integrates with the AgentTeam Approval domain through subject adapters for: - `kb_wiki_generation`; - `kb_publication`. Each subject binds `workspaceId`, `kbId`, optional `sourceId`, immutable revision, payload digest, applicant, assignment, decision, reason, timestamps, correlation ID, and idempotency key. Submit, decide, and withdraw are idempotent. Source deletion, revision change, KB archival, or authorization revocation makes affected pending work stale or cancelled. Browser controls are not an authorization boundary. Every mutation rechecks: - authenticated workspace membership; - the action-specific KB role; - Workspace owner/admin authority when required; - source-repository authorization where a repository operation follows; - the frozen revision and request version. Approval review may expose a time- and payload-scoped read-only review view. It does not grant general KB or repository access. Generation and publication use server-owned credentials and never expose AGS write tokens to the browser. KB approval notifications are a retryable projection of the Approval record. Only the exact pending assignments receive actionable reviewer cards; the applicant receives a pending receipt. At a terminal decision, pending cards are resolved and the applicant receives a read-only approved, rejected, withdrawn, or stale result deep-linked to the corresponding Source Wiki or Review page. Wiki approval is labelled as queued rather than complete. Wiki generation completion and failure are separate job-terminal notifications to the requester. Ready, failed, and execution-time stale delivery is a durable, idempotent projection of the exact terminal generation-request version. The projection reloads canonical sanitized facts, addresses only the requester's active Human workspace membership, and never includes raw worker diagnostics. ## 10. Bounded Reads And Mutations Collection endpoints filter publication and permissions in the database before pagination. Setup detail work is bounded by one explicitly requested KB and at most the product Source-page limit. Source, current-revision, disposition, and request hydration use bounded batch queries; the UI must not add a per-Source first-paint request fanout. Status polling is enabled only while setup contains active asynchronous work and stops at terminal state or component teardown. Raw worker errors, tokens, credentials, and local paths are never returned as request summaries. ## 11. Accessibility And Responsive Behavior - Step disclosure headers, Source rows, Add/remove actions, and approval controls are reachable by keyboard and use semantic controls. - Focus moves to the page title or error summary after route/state changes. - Critical states use text and iconography, not color alone. - Loading, empty, failed, stale, and permission-denied states are explicit. - Forms collapse to one column below 980px and footer actions do not overflow. ## 12. Related Specs - [`workspace-knowledge-base.md`](./workspace-knowledge-base.md) — KB, Source, taxonomy, collection, and normal detail surfaces. - [`kb-permissions.md`](./kb-permissions.md) — KB roles and AGS repository authorization boundary. - [`repository-import-progress.md`](./repository-import-progress.md) — Source import and generation progress vocabulary. - [`uploaded-ua-dashboard.md`](./uploaded-ua-dashboard.md) — Dashboard archive import and immutable publication.