# KB Permissions

> Canonical path: `specs/kb/kb-permissions.md`
> Status: living product spec
> Scope: Knowledge Base grants, source access, repository access boundary, and agent availability.

## 1. Product Boundary

KB permissions are MeshX product permissions. AGS repository permissions are
repository permissions. A user may need both, but they answer different
questions.

MeshX decides:

- who can see a KB;
- who can manage KB metadata and sources;
- who can retrieve or read through KB product APIs;
- which agents may use a KB.

AGS decides:

- who can read, write, or administer a repository;
- who can operate issues, pull requests, wiki, labels, releases, and settings at
  the repository level.

Repository Access Tokens are AGS repository credentials, not KB grants. Their
scope, lifecycle, and Git data-plane behavior are defined in
[Repository Access Tokens](../workflow/repository-access-tokens.md). Source and
insights repository access are separate execution-plane capabilities; granting
one does not implicitly grant the other.

## 2. Roles

KB human member roles are product roles. The UI should render them with
user-facing labels equivalent to “Owner”, “管理”, “读写”, “读”, and
“不可访问”.

| Role     | UI meaning | View and retrieve | Maintain sources | Manage grants | Delete or transfer                        |
| -------- | ---------- | ----------------- | ---------------- | ------------- | ----------------------------------------- |
| `owner`  | Owner      | Yes               | Yes              | Yes           | Yes                                       |
| `manage` | 管理       | Yes               | Yes              | Yes           | No, unless a later product rule allows it |
| `edit`   | 读写       | Yes               | Yes              | No            | No                                        |
| `view`   | 读         | Yes               | No               | No            | No                                        |
| `none`   | 不可访问   | No                | No               | No            | No                                        |

`none` is a first-class explicit human member override. Selecting it creates or
updates a per-user deny and prevents inheritance from the workspace-member
default. It is not available for the all-workspace-members default because every
KB is workspace-public.

An active organization owner or organization administrator implicitly has KB
`manage` on every KB in a workspace owned by that organization. This authority
does not require or create a KB grant, overrides an explicit KB `none` grant,
and does not imply source or insights repository access. Workspace owners and
workspace administrators retain the same implicit KB management authority.
Consequently these administrators see every Draft in the workspace collection,
may open another user's Draft setup editor, and may run the confirmed
Official-to-Draft transition. KB owners or managers without that workspace-level
authority cannot convert an Official KB to Draft.

Draft visibility is intentionally narrower than ordinary KB visibility. While a
KB is in `draft` publication state, its owner, explicit human `manage` or `edit`
maintainers, and the workspace/organization administrators described above may
see it, open its detail/setup surfaces, read its activity, and use it through
retrieval APIs subject to source-repository authorization. Workspace-member
defaults, explicit human `view` or `none` grants, and agent grants do not disclose
Drafts. Maintainers retain their normal role capabilities while collaborating on
the Draft; publication approval and workspace-governance actions keep their
separate authorization rules.

Official editing and Official-to-Draft conversion are separate capabilities. A
KB owner may open the isolated Official editor and save its reviewed working
revision while readers continue to use the previous publication. Workspace and
organization owners/admins may do the same through implicit KB management.
An ordinary KB manager may not edit Official unless it also has that governance
authority, and only the workspace/organization governance roles may convert an
Official KB to Draft.

KB Settings is a manager surface. Only `owner`, `manage`, or an equivalent
`canManage=true` response may show Settings tabs, source settings shortcuts,
source creation controls, grant management, and lifecycle actions. `view` and
`edit` users may open readable content surfaces but must not see Settings as a
disabled page; direct Settings URLs must fall back to the default readable KB
surface.

Agent grants use the same grant table shape but keep the KB product role fixed at
`view`. User-facing agent controls expose this dimension as “Accessible” or “No
access”, never as the human “View” or “Edit” roles. Agent grants do not support
`none`; removing agent access deletes or deactivates the agent grant.

Repository access is a separate agent dimension. An accessible agent may receive
`read` or `write` repository access for mapped source and insights repositories.
“Read/write” means the agent may modify those underlying repositories; it does
not grant KB source management, permission management, or lifecycle capability.
Agent-centric and KB-centric controls must use the same agent access API and show
both dimensions explicitly.

## 3. Visibility

A KB is visible to a user when it is Official and:

- the user created it;
- the user has an active explicit KB grant whose role is not `none`;
- the user is an active member of the workspace that owns the KB and does not
  have an explicit `none` override;
- the user is an active owner or administrator of the organization that owns
  the workspace.

If the KB is Draft, it is visible only when:

- the user created it or has an active explicit human `owner`, `manage`, or
  `edit` grant for it;
- the user is an active owner or administrator of the owning workspace or
  organization.

Official KB visibility is workspace-public. The workspace-member default is
`view` when unspecified and may be configured only as `view`, `edit`, or
`manage`. Legacy empty, invalid, or `none` defaults resolve to `view` and are
backfilled to `view` by migration, but Draft rows ignore this inherited default.

Explicit user grants remain the source of elevated KB roles. A workspace-visible
user with no explicit KB grant inherits the current workspace-member default for
KB list, detail, source detail, and retrieval/read authorization. An explicit
`none` grant denies inherited workspace-member access, except that organization
and workspace administrator authority still resolves to implicit `manage`.

List APIs must filter in MeshX. Web and generic AgentTeam transport must not cache or
recompute KB visibility. AgentTeam forwarder routes for KB control-plane APIs must
bind requests to the current workspace before forwarding; MeshX must not treat a
client-supplied workspace header as independent proof of workspace membership.

## 4. KB Permission And Repository Permission Inheritance

A human's KB role and repository access are independent settings shown in the
same product surface:

- the KB role controls product visibility, retrieval, metadata, source, and KB
  grant-management operations;
- repository access controls AGS collaborator permissions on repositories mapped
  from KB sources;
- repository access alone does not grant KB visibility or KB management;
- a KB role does not imply direct AGS repository access unless a KB-owned
  repository access profile or repository-row override materializes it.

For an explicit human KB grant, MeshX stores a KB-level repository access default
and optional repository-row overrides. The effective repository permission for a
KB source repository row, including source and `insights` repository roles, is
resolved by the precedence rules in
[`kb-repository-access-grants.md`](./kb-repository-access-grants.md):

1. KB-level repository access default;
2. workspace repository access profile, when a deployment/product profile
   explicitly provides one;
3. explicit override for that grant, source, and repository role;
4. agent binding/grant policy for agent materialization.

An explicit override may narrow or broaden the inherited repository permission.
A `none` override is an explicit repository-row deny for KB-owned repository
materialization. Removing an override restores inheritance from the weaker
precedence level.

The all-workspace-members KB default does not materialize AGS repository access
for every workspace member. Repository access materialization is created only for
explicit human or agent grants that carry a repository access intent.

Repository access inheritance and materialization rules are defined in
[`kb-repository-access-grants.md`](./kb-repository-access-grants.md).

## 5. Source Operations

Adding, editing, syncing, or indexing a source requires KB `edit` or higher;
removing a source requires KB `manage` or higher. Importing or overwriting that
source's UA Dashboard additionally requires a live workspace `owner` or `admin`
role. UA Dashboard read uses KB `view` or higher. The import is a MeshX-owned
mutation against the system-managed insights repository and does not require
the browser principal to hold or receive an AGS write token.

Opening a source detail requires KB `view` or higher and repository readability
for the repository-backed operation being performed. Repository `read`, `write`,
or `manage` can satisfy repository readability, but none of them bypasses the KB
visibility check.

Creating a repository-backed source also ensures the required AGS repositories
and records the initiating user's repository access as durable, observable
intent for reconciliation. This intent does not replace KB permissions; it only
materializes the repository primitive when the product surface needs it.

Post-creation human repository access grants are managed through KB-level
repository access defaults plus source/repository-role overrides. Repository
`manage` maps to AGS `admin`; it grants repository administration capability for
that mapped repository only and does not make the subject a KB manager.

## 6. Retrieval And Reads

KB retrieval and reads always go through MeshX product APIs.

Each Knowledge Base has a manager-controlled
`allow_knowledge_qa_without_source_access` switch, disabled by default. When it
is enabled, an active workspace member with an effective non-`none` KB role may
select that KB or its Sources in server-hosted Knowledge Q&A even when the
member has no materialized source-repository collaborator grant. An explicit
human KB grant with role `none` remains an authoritative deny and is never
overridden by the switch.

This switch is a narrow hosted-Q&A retrieval authority. It does not create,
broaden, repair, or revoke repository access intents, AGS collaborators,
credentials, or tokens. It does not authorize repository trees, blobs, clone,
download, issues, pull requests, wiki browsing, generic KB retrieval APIs, or
other direct source operations. Existing independent repository access remains
authoritative for those operations. Knowledge Q&A may still return the bounded
quotations and citations required to support its answer through its
owner-bound, server-side evidence path.

Opening a retained citation always performs a fresh authorization check. A
member with independent source-repository read authority keeps the ordinary
immutable-revision file route. A member authorized only by
`allow_knowledge_qa_without_source_access` receives an evidence-only preview:
the exact cited path, immutable revision, cited line range, and no more than the
original hosted read envelope (1,000 lines and 96 KiB). That response carries
no repository route, repository identity, credential, tree, full-file, raw,
download, history, or expand capability. A missing historical revision fails
closed instead of falling forward to current content.

MeshX must:

- authenticate the user or agent;
- validate KB grant and source policy;
- intersect agent access with explicit agent KB grants;
- resolve repository mappings;
- re-check either direct repository readability or the narrow hosted-Q&A
  evidence authority whenever repository content is involved;
- bind returned citations to revisions when reproducibility matters.

A returned URL, citation URI, or product route is not proof of authorization.
Read APIs must re-check permissions.

## 7. Agent Availability

An agent can use a KB only when MeshX has an active grant for that agent and KB.
The first supported role is `view`.
Agent-centric human control-plane operations (listing an agent's KB availability,
changing an agent's KB grants, or adding an agent grant through the KB
permissions surface) require the authenticated user to prove ownership/control of
the target agent through trusted AgentTeam-forwarder claims. Missing or stale
agent-ownership claims must fail closed.

Generic message, thread, channel, or session transport must not become the
source of truth for KB grants. Agent grants define the standing agent retrieval
scope. Acting-user attestations bind ordinary Agent requests to the initiating
Human and delivery target, but they must not add that Human's KBs or repository
access to the Agent's retrieval scope.

Ordinary Agent KB MCP request bodies must not carry `kb_ids`, `source_ids`,
repository, path, ref, revision, or target fields. `kb_search(query,
max_results?)` resolves the explicitly agent-granted KB set from the current
AgentTeam actor/turn scope, returns opaque `citation_id` values, defaults
`max_results` to 10, and clamps at 50. `kb_fetch(citation_ids,
max_chars_per_item?)` resolves those opaque citation ids server-side and
re-checks permissions before returning content. Agent-free Knowledge Q&A
sessions continue to resolve the current user's accessible KB set and may expose
separate source filters/evidence tools inside that dedicated session boundary.

Agent bulk permission updates also use `kb_ids` for the submitted selection. The
response may spell out the resulting set as `knowledge_base_ids`, but requests
must not carry both field names for the same selection.

## 8. Clean Boundary

Do not model KB permissions through:

- channel shares;
- Project membership;
- repository naming conventions;
- generic thread/session fields;
- client-side repository discovery.

KB grants live in the KB product model. Repository collaborators live in AGS.
`resource_repositories` connects product resources to repository identities.