Files
agent-lib/docs/proposals/client-labels.md
T

6.1 KiB

Proposal: client labels — deliver content to a subset of clients

Status: proposed (14.11.2026)

Problem

A work repository serves every client the same content. Organisations with teams want relevant content per team: finance needs finance skills, sales needs sales agents, and nobody benefits from all of it. A long skill list also hurts routing quality of small models.

Today the only way to split is one repository or one branch per team. Both force shared content to be maintained N times (merges, drift) and cannot serve a client that belongs to two teams — a client pulls exactly one ref.

Decision in one sentence

Content items may carry labels in the work repository; clients carry labels in their config; sync delivers an item when it is unlabeled or shares at least one label with the client.

agent-lib stays generic: it knows "label" and "item", never "department", "role" or any organisation's vocabulary. What a label means and who gets it is decided outside agent-lib (curator: which item has which label; fleet tooling: which client has which label).

This revises the v2 non-goal "client-side selection or profiles": labels are a selection, but no profiles — there is no per-label content, overrides or inheritance, only a filter over the one shared inventory.

Repository side: agent-lib.labels.json

Optional file in the work repository root, next to agent-lib.lock.json. JSON keeps the binary free of a YAML dependency (frontmatter is hand-parsed today) and matches the lockfile and client config.

{
  "version": 1,
  "labels": {
    "sales":   ["crm-agent", "quote-writer"],
    "finance": ["officecli-financial-model", "invoice-check"],
    "dev":     ["grilling", "to-spec"]
  }
}

Rules:

  • Unlabeled = everyone. Only items that should be restricted appear in the file. Adding an item to the repository without touching the file delivers it to all clients — same as today.
  • An item may appear under several labels (OR).
  • Entries are deployed item names (after vendor renames), matched across types: foo covers the skill foo and the command foo alike. Type- qualified entries are not needed until a real collision appears.
  • Label form ^[a-z0-9][a-z0-9-]*$; lists must be non-empty.
  • Names may also refer to MCP fragments. The binary never deploys MCP, but fleet tooling can read the same file to scope MCP servers — one source of truth for "who gets what".
  • Unknown top-level keys are an error (typo protection); version is required.

Client side: labels in the client config

{
  "repo_url": "https://git.example.com/company/agent-content.git",
  "ref": "main",
  "labels": ["sales", "leadership"]
}
labels Effect
field absent no filtering — every item, as today (backward compatible)
[] only unlabeled items
["a","b"] unlabeled items plus items labeled a or b

Client labels that no item uses are fine (no warning): a client may be labeled ahead of content.

Admin-pinned labels

Today the first config found wins as a whole, and the user-level config precedes the admin default. For labels that would let a user widen their own selection. Rule:

If the admin default config exists and contains labels, that value applies — whichever config supplied repo_url. User-level and env configs cannot set or override labels while an admin value exists. Without an admin value, labels from the chosen config applies (personal machines keep full control).

--labels a,b as a flag is deliberately not offered for sync; for testing use --config with a file that has no admin counterpart, i.e. on a machine without an admin default.

Labels are a relevance filter, not access control: the whole repository revision is still fetched into the local cache. Confidential content needs a separately authenticated repository.

Sync behaviour

  1. Build the inventory as today.
  2. Read agent-lib.labels.json from the same revision.
    • Absent → no filtering.
    • Invalid (parse error, bad label form, empty list, unknown key, unknown version) → sync aborts before any change with a clear error. Never fall back to "deliver everything".
    • A name that matches no item → warning in sync log/status, not fatal (the curator-side validate is the hard gate).
  3. Drop items whose labels do not intersect the client labels before hashing/planning (internal/client/sync.go, loop over inv.Deployable()).
  4. Planning is unchanged. A previously deployed item that is no longer selected is handled exactly like an upstream deletion: unmodified → remove; locally modified → skip + warn (--force removes). The plan reason and toast text say "not selected for this client's labels" instead of "upstream deleted" so users understand why.

Status

status --json gains:

"labels": { "client": ["sales"], "source": "admin", "filtered": 12 }

source is admin | user | env | flag | none. Human output prints one line: labels: sales (admin) — 12 items not selected.

Curator side

agent-lib validate checks agent-lib.labels.json when present: schema/version, label form, non-empty lists, every name resolves to an inventory item (own or external, any type including MCP). Errors are fatal, so a broken file never reaches clients through CI.

No new curator command is required; the file is edited by hand. A later agent-lib labels list (item → labels table) is a nice-to-have.

Tests

  • planner/sync: absent field, [], single/multi label, item under two labels, label removed from client → remove unmodified / keep modified, --force.
  • config: admin labels beat user labels; user labels apply without admin value; absent everywhere → no filtering.
  • labels file: absent, invalid variants (abort, no disk change), unknown name (warning).
  • validate: each error class.
  • e2e: second run is a byte-level no-op with labels active.

Rollout

Additive and backward compatible: old clients ignore the file, new clients without labels ignore the file. Fleet tooling adds the field after pinning the release that understands it.