# Glossary

## Hub

Hub is the authority layer. It owns the server-side state for Artifact, Workspace, context collaboration, and aggregated attestation data.

This is the architectural center of gravity for the whole project. If a page explains clumsies as a set of local files plus some helper commands, it is missing the point.

## Rule

A rule is a behavioral instruction for an agent. It answers one question: how should the agent act?

In clumsies, the behavioral layer in Artifact has two main forms:

| Type | Meaning |
| --- | --- |
| Rule | an individual constraint or policy |
| Workflow | an ordered set of constraints that implies execution flow |

When the docs mean a single behavioral instruction, they should usually say `rule`, not `prompt`.

`Prompt` still exists as an umbrella term in some parts of the system, especially in protocol naming and identity fields such as `prompt_id`. But that broader term should not replace `rule` when the actual meaning is narrower.

Rule is not the same thing as project knowledge. A rule tells the agent what to do. It does not tell the agent what the project is.

## Workflow

A workflow is an ordered behavioral structure rather than a single rule. It groups multiple constraints into an execution path that implies sequence or discipline rather than one isolated instruction.

That is why a workflow belongs in the same behavioral layer as rules, but it should not be collapsed into the same concept.

## Bundle

A bundle is a reusable selection unit inside Artifact. It packages rule or workflow choices so a workspace can adopt a coherent set rather than hand-picking everything one item at a time.

Bundles matter because they are the bridge between organization-level curation and workspace-level adoption.

## Context

Context is project knowledge owned by a workspace. It answers a different question: what is this project, why is it shaped this way, and what do we currently know?

Specs, ADRs, research notes, and design material are all context. They give the agent evidence and background. They do not directly impose behavior.

Context is not managed by Artifact. That boundary matters. If project knowledge were flattened into the shared behavioral layer, workspace ownership and collaboration would become much harder to reason about.

## Artifact

Artifact is the organization-level source of rules, workflows, and bundles. It is not a cache and not a loose pile of copies. It owns rule identity, current path, content hash, and review history.

Once Artifact stops being authoritative, cross-workspace convergence becomes fragile. Rule history, rule review, and attestation aggregation all become harder to trust.

## Workspace

Workspace is the project boundary where rules, workflows, bundles, and context are combined for real work. A workspace does not own Artifact behavior content. It selects a subset from Artifact and combines it with workspace-owned context.

| Part of a workspace | Ownership |
| --- | --- |
| selected rules, workflows, and bundles | references to Artifact |
| context files | workspace-owned |
| local drafts | local working state |
| manifest | Hub-maintained index of current state |

That is why a workspace is not just a folder and not simply a git repository. It is the collaboration boundary around a project.

Workspace also has its own membership model. Org-level maintainers exist above it, while workspace admins and members control project-level collaboration inside it.

## Manifest

Manifest is the current indexed snapshot of workspace state. It bridges Hub and local runtime by recording which rules, workflows, bundles, and context files belong to the workspace and which content hashes are current.

That matters because sync, cache refresh, rename handling, and non-blocking local reads all depend on it.

## Attestation

Attestation is the event stream produced when agents discover and load
Artifact behavior, then refer to it during real work.

Attestation is not decorative analytics. It is the feedback signal for the rule lifecycle and the broader improvement loop around Artifact content. Without it, teams are left guessing which constraints actually mattered and which ones were only present in theory.

Older specs and pages may still call this layer `Trace`. The current codebase and newer docs are moving toward `Attestation`.

## Adapter

Adapter is the host integration layer. It connects clumsies to coding agents such as Codex or Claude Code by installing the hooks, config, skills, and runtime glue needed for the protocol to actually run.

Adapter is not the Hub and not the MCP protocol itself. It is the layer that makes the runtime usable inside a specific host.

## MCP

MCP is the agent-facing protocol surface. It is the runtime path through which an agent discovers Artifact content and context, loads content, and declares the constraints it actually applied.

MCP is not just a transport detail. It is the mechanism that turns rule and context management into a live runtime system with traceable usage.

The current implementation exposes concise tools such as `memsetup`,
`memdisc`, `memload`, `memref`, `artifact`, `agentreport`, and
`agentrejected`. That is the runtime contract the docs should describe.

## Draft and PR

A draft is local in-progress work. It can target either a Artifact rule or workflow, or a workspace context file. A pull request is the collaboration object that moves those changes back to the authority layer.

Draft is local state. PR is shared workflow.

For Artifact content, PR is the path back into org-level shared truth. For workspace context, PR is the path back into workspace mainline knowledge. Those are related patterns, but not the same authority boundary.
