# GlueBolt

> GlueBolt certifies that a team knows how to safely command AI, then enforces
> that certification every time an AI acts on a person's behalf - with an audit
> ledger. It is AI-agnostic: your agent (Claude, OpenClaw, any MCP client or
> HTTP tool-caller) consults GlueBolt's gate before doing anything consequential.

Key concepts: an Account is the customer team. A Member is a human on it.
Members earn certification by passing training; certification sets their
capability tier (read_only < guarded_write < write; write is only ever granted
by an admin, never derived). Consequential actions flow propose -> gate ->
human consent -> execute -> audit. A denial is recorded, not discarded.

## API

- [OpenAPI spec](/api/openapi.json): machine-readable REST contract
- [API docs](/api/docs): human-readable version with curl examples

Authentication: `Authorization: Bearer gbk_...` on every request. The key
authenticates the account; each call names the member the agent acts for
(actor: {email} or {provider, external_id}), and the gate checks THAT person's
tier.

Endpoints:
- GET /api/v1/capability?email=jane@acme.com - the member's tier, its source,
  and per-curriculum certification record. Consult before consequential work.
- POST /api/v1/actions {kind, actor, payload} - propose a governed action.
  Returns status `denied` (tier insufficient; the member should certify) or
  `proposed` with a blast_radius. Nothing executes at propose time.
- POST /api/v1/actions/:id/confirm {actor} - execute, only after the proposing
  member has seen the blast radius and consented. Proposer-only.
- POST /api/v1/actions/:id/cancel {actor} - abandon a proposal. Proposer-only.
- GET /api/v1/actions and /api/v1/actions/:id - the audit ledger. Filter with
  ?kind= and ?status= (kind=runner_tool&status=denied lists every tool call the
  runner's governance gate refused; tool in payload.tool, why in denial_reason).

Action kinds today: `broadcast` (payload: {message}) - announce to the whole
team through each member's own channels (Slack DM or email); `email`
(payload: {to, subject, message}) - a governed email, only to a VERIFIED
address on this account (`to: "self"` mails the member themselves - read_only-
safe and immediate; a teammate needs guarded_write plus confirmation).

## MCP

POST /api/mcp is an MCP server (Streamable HTTP, stateless; same Bearer auth).
Tools: check_capability, request_action, confirm_action, cancel_action,
get_action, list_actions, list_workspace_files, read_workspace_file,
start_preview, preview_status, stop_preview. Add it to Claude with:

    claude mcp add gluebolt https://gluebolt.com/api/mcp --transport http \
      --header "Authorization: Bearer $KEY"

Contract for agents: call check_capability before consequential work; relay
denials as policy (tell the human how to certify), never as errors; never call
confirm_action without showing the human the blast radius and getting an
explicit yes.

The workspace tools are a read-only window onto what Bolty built in one chat:
list_workspace_files / read_workspace_file take a conversation_id plus the
member's identity and only answer for conversations that member is actually in.

The preview tools run what Bolty built: start_preview boots the workspace's app
(npm start when a package.json has a start script, a jailed static file server
otherwise) and returns the url where it answers on the runner host;
preview_status reports running/mode/url plus the last log lines; stop_preview
shuts it down. Same participant-only scoping as the workspace tools.