Context Activation¶

Context activation lets you explicitly prepare a bounded slice of a project's context — scoped to one project, one context module, and one platform — and get back either the prepared content (so you can paste it into an agent session) or a machine-readable reason it wasn't prepared. That scoping is what bounds the slice in this version: the paths and budget fields on the request are validated and recorded, but do not further narrow which sources are selected or how much prepared content comes back — see the request-field table below. Every successful preparation is backed by a durable, integrity-checked receipt recording what was prepared, when, and from which sources.

This is a local preparation step, not delivery. Context activation never writes files, never claims a platform "consumed," "injected," or "auto-loaded" anything, and never touches your project directory. You still copy the returned content into your agent session yourself.

Default-off¶

Context activation is disabled by default. Both the API endpoint and the CLI command require the server operator to explicitly turn the feature on:

export SKILLMEAT_CONTEXT_ACTIVATION_ENABLED=true

or in your server config:

context_activation_enabled = true

With the flag off, the API endpoint is not registered at all (404 Not Found, not a 403 or a 501) and the CLI command reports that the feature isn't enabled on the server.

What gets prepared¶

Only two delivery modes actually return content:

Delivery mode	Behavior
`prompt_prelude`	Returns prepared content as a string, ready to paste into a prompt.
`manual_export`	Returns prepared content as a string, for you to save/export manually.

Two additional delivery-mode values are recognized by the request schema but always reject:

Delivery mode	Behavior
`native_file`	Not delivered in this version. Rejects with a typed `delivery_mode_not_prepared` error before any source content is touched.
`native_reference`	Not delivered in this version. Same rejection behavior as `native_file`.

Native activation and materialization — writing prepared content directly into a target platform's native config location, or having a platform automatically load it — is not delivered in this version. If you need content written to disk for a specific platform, use SkillMeat's existing deployment/materialization commands instead; context activation is a separate, additive capability focused on explicit, receipt-backed preparation.

How source selection works¶

Context activation selects sources in two steps:

It looks up which context entities are eligible for your project, context module, and platform — filtering out anything belonging to a different project, a different context module, or that doesn't target the platform you specified.
Only entities that passed step 1 have their content loaded, in a stable, deterministic order.

A source that doesn't match your project, module, or platform is never touched at the content level, regardless of what else exists in your collection.

Every prepared result has a receipt¶

Prepared content is never returned without first being recorded in a durable, append-only local receipt. Each receipt captures:

A generated receipt ID (car_...)
The project, context module, platform, work kind, delivery mode, and budget that were requested
The exact set of source IDs whose content went into the output
A content digest (SHA-256) of what was prepared
A creation timestamp

The digest is an integrity check, not tamper-evidence. It is an unkeyed SHA-256, so it detects corruption, truncation, and accidental modification when a receipt is read back — but it does not defend against an actor who can rewrite the receipt file and recompute the digest. Treat receipts as a durable record of what you prepared, not as cryptographic proof against a motivated local adversary.

If the receipt can't be durably written for any reason, no prepared content is returned — you get a typed receipt_unpersisted error instead. This receipt store is POSIX-only by design: it anchors every write to a directory file descriptor so a same-user process racing to swap a directory for a symlink can't redirect where receipts are written. On a platform without POSIX dir_fd support, the receipt store fails closed with a typed error rather than silently falling back to a less-safe write path.

API¶

Prepare a context activation¶

POST /api/v1/context-activations

Requires the artifact:write scope. In enterprise deployments, you must also have access to the target project (the same project-access check used elsewhere in the API).

Request body:

{
  "project_id": "your-project-id",
  "context_module_id": "your-context-module-id",
  "platform": "claude_code",
  "work_kind": "implementation",
  "paths": ["skillmeat/api/routers/context_packing.py"],
  "budget": 1200,
  "delivery_mode": "prompt_prelude",
  "invocation_ref": "optional-correlation-id"
}

Field	Required	Notes
`project_id`	yes	The project to activate context for.
`context_module_id`	yes	The context module to activate.
`platform`	yes	One of the registered platform identifiers (`claude_code`, `codex`, `gemini`, `cursor`, `bob`, `remote_git`, `other`).
`work_kind`	yes	One of `implementation`, `review`, `debugging`, `planning`.
`paths`	yes	One or more relative paths the activation concerns. Must not be absolute and must not contain `..`. Validated and recorded on the receipt as request metadata; in this version it does not narrow source selection — it does not filter which sources are eligible or which content is loaded (see "How source selection works" above).
`budget`	yes	Positive integer token budget. Validated and recorded on the receipt; in this version it does not bound the prepared output — the renderer concatenates all eligible source content regardless of this value.
`delivery_mode`	yes	`prompt_prelude`, `manual_export`, `native_file`, or `native_reference` (see above).
`invocation_ref`	no	Optional caller-supplied correlation reference.

The request body is closed — any field not listed above is rejected with 422 Unprocessable Entity, not silently dropped.

A successful preparation returns:

{
  "ok": true,
  "content": "...",
  "source_ids": ["ctx_abc123"],
  "receipt": {
    "receipt_id": "car_...",
    "project_id": "your-project-id",
    "context_module_id": "your-context-module-id",
    "platform": "claude_code",
    "delivery_mode": "prompt_prelude",
    "budget_tokens": 1200,
    "source_ids": ["ctx_abc123"],
    "content_digest": "sha256-hex..."
  },
  "error": null
}

A non-prepared result (e.g. a native delivery mode, or a persistence failure) returns ok: false with a typed error object instead — always as 200 OK, since it's a well-formed response, not a client-request error:

{
  "ok": false,
  "content": null,
  "source_ids": [],
  "receipt": null,
  "error": {
    "code": "delivery_mode_not_prepared",
    "reason": "native_delivery_mode",
    "message": "Delivery mode 'native_file' does not prepare content in this version",
    "details": {"delivery_mode": "native_file"}
  }
}

Status	Meaning
`200`	Request was well-formed; check `ok` for whether content was actually prepared.
`403`	Missing `artifact:write` scope, or denied project access.
`422`	Closed-request validation failure (missing/invalid field, or an undefined field).
`404`	The endpoint isn't registered — `context_activation_enabled` is off on this server.
`501`	The server edition doesn't support the receipt store for this request (enterprise editions do not yet ship a receipt store).

CLI¶

skillmeat context activate \
  --project-id your-project-id \
  --module-id your-context-module-id \
  --platform claude_code \
  --work-kind implementation \
  --path skillmeat/api/routers/context_packing.py \
  --budget 1200 \
  --delivery-mode prompt_prelude

Repeat --path for multiple paths. Add --invocation-ref <id> for an optional correlation reference, and --format json to get the raw JSON response instead of a formatted summary.

If the server has the feature disabled, the command reports that plainly instead of a raw connection error.

Context Entities — manage the underlying spec files, rule files, and other context entities that context activation selects from.
Context Modules — group and configure the context modules that context activation is scoped to.
Memory & Context System — the broader context-packing feature; context activation is a separate, additive capability and does not replace it.