# AGS Resource Permission Matrix for KB, KB Source, Skill, and Memory

This document links the resource-specific matrices and records the
cross-cutting authorization rules that must remain true across AgentTeam, MeshX,
Desktop, and AGS.

Resource-specific matrices:

- KB / KB source: [`../kb/kb-ags-permission-matrix.md`](../kb/kb-ags-permission-matrix.md)
- Skill / Memory: [`../../SKILL_MEMORY_AGS_PERMISSION_MATRIX.md`](../../SKILL_MEMORY_AGS_PERMISSION_MATRIX.md)

## 1. Cross-resource authorization invariants

Product decisions confirmed on 2026-06-25:

- MeshX product permissions are the source of truth; AGS repository permissions
  are only the repository execution plane.
- Memory and Skill AGS repositories are not workspace-directory resources by
  default and do not imply human direct AGS operations. Human product actions go
  through MeshX-mediated product surfaces unless a durable access intent
  explicitly materializes repository access.
- Memory and Skill human roles exposed by the product are `owner`, `manage`,
  `view`, and `none`; `edit` is a legacy compatibility value and must not be
  produced by new UI or grants.
- Skill is not a workspace catalog by default; the workspace-member default is
  `none` / not visible. Workspace-wide Skill visibility must be represented by
  an explicit workspace subject grant, not by treating every Skill repository as
  a workspace directory resource.
- Memory and Skill agent access uses short-lived sync leases rather than
  long-lived collaborators.

1. A AgentTeam user, agent, workspace, or project must not gain AGS repository, wiki,
   source, insight, token, or local managed-copy access unless a server-side
   authorization source says that subject is allowed.
2. Browser-facing routes must derive workspace authority from the AgentTeam current
   workspace gate or trusted forwarded claims. Raw workspace headers from an
   untrusted client are not proof of membership.
3. Agent-control routes must prove the acting user owns or controls the target
   agent before listing or mutating that agent's KB, Skill, or Memory access.
   Read paths fail closed the same way mutation paths do.
4. Grant mutations that change product access must be auditable and must not rely
   on UI-only best-effort notifications. Where local Desktop state must refresh,
   the server-side asset-access outbox remains the durable delivery mechanism.
5. Revocation must fail closed. A transient `unknown` state is not `unbound`: it
   must not silently authorize access, and it must not destroy local state as if
   a definitive revoke had been observed.

## 2. Resource ownership and AGS materialization

| Product resource | Product source of truth | AGS / local materialization | Primary authorization fact |
| --- | --- | --- | --- |
| KB | `knowledge_bases` + `knowledge_base_grants` | MeshX control-plane resource; no standalone user-visible repo | Workspace membership plus explicit KB grants |
| KB source | `knowledge_base_sources` + `resource_repositories` | Canonical or mirror AGS repository; optional insights wiki/repo | KB role and source repository access profile |
| Memory | `Memory` + `MemoryGrant` + `MemoryAgentBinding` | Canonical `.mem` AGS repo plus Desktop vault clone; no default human AGS direct entry | Memory `owner`/`manage`/`view`/`none` role and owned-agent binding |
| Skill | `Skill` + explicit grant/visibility model + `SkillAgentBinding` | Canonical `.sk` AGS repo plus Desktop managed-skill clone; not a default workspace catalog | Skill `owner`/`manage`/`view`/`none` role, optional workspace `view` grant, and owned-agent binding |

## 3. Human-facing permission boundaries

- KB metadata and retrieval can be workspace-visible, but source mutations,
  permission mutations, and repository access materialization require the role
  specified in the KB matrix.
- Memory and Skill product roles no longer expose `edit`; content maintenance and
  grant mutation require `manage` or `owner`, while `view` is read-only.
- Skill is fail-closed by default: no workspace-member default visibility, and
  workspace-wide visibility is granted only by an explicit workspace subject
  grant.
- Cross-workspace human grantee validation requires a shared workspace
  membership authority for MeshX and must not be patched ad hoc in individual
  resources.

## 4. Agent-facing permission boundaries

- KB agent-control listing and grant mutation require trusted owned-agent proof.
  Runtime retrieval remains authorized by agent KB grant intersection and
  agent-thread/request attestation.
- Memory and Skill agent-access read APIs now require ownership for every target
  agent in a request. Batch reads fail closed when any requested agent is not
  owned by the caller.
- Agent binding/unbinding retains the asset-access invariant: server-side
  mutation and asset-access outbox intent are committed together.

## 5. Review checklist

- Verify every browser-accessible KB route runs behind the current-workspace
  forwarder gate before MeshX sees the request.
- Verify KB, Memory, and Skill agent-access read paths fail closed without
  trusted owned-agent proof.
- Verify grant mutation roles match the resource-specific matrix and do not let
  lower roles create higher privilege.
- Verify outbox and Desktop refresh semantics are preserved when changing
  repository-backed asset access.
- Verify known risks remain documented and are not silently widened by a change.

## 6. Known follow-ups outside this matrix

- Shared workspace membership authority for validating human grantees across KB,
  Skill, and Memory surfaces.
- Deployment audit for direct MeshX exposure and trusted JWT policy.
- Skill local clone retention or deletion policy on revoke.
- Product communication for non-hot-loaded Skill binding changes.