MCP Tools Reference

This is the full searchable reference for Cruxible MCP tools. MCP is a curated agent connector, not full CLI parity. The HTTP API/client remain the broader remote product surface; CLI keeps shell-only utilities such as context, config views --update-readme, export edges, and local receipt explain.

Permission Modes

Mode	Env value	Meaning
READ_ONLY	read_only	Query, inspect, receipts, samples, evaluation, lint, snapshots listing.
GOVERNED_WRITE	governed_write	READ_ONLY plus workflow and procedure runs, procedure/group proposals, claim attestations, outcomes, decision records, snapshot creation, and source artifact registration. Reaching the feedback tools is permitted at this tier, but every feedback ACTION now requires GRAPH_WRITE — see below.
GRAPH_WRITE	graph_write	GOVERNED_WRITE plus raw graph mutation, canonical workflow apply, group resolution/trust updates, procedure resolution/retirement, attestation dispositions, and feedback adjudication (approve / reject / correct).
ADMIN	admin	Full lifecycle, config reload, locks, snapshots, clone, state publication/pull, ingest, constraints, and policies.

tools/list advertises only tools allowed by the active CRUXIBLE_MODE; call-time permission checks still enforce the same tiers as a backstop.

The Permission line on each tool below is the tier needed to call it, which is not always enough to succeed. Two surfaces additionally gate on the payload: the feedback tools require GRAPH_WRITE for the adjudication actions approve / reject / correct — which is all of them, so their GOVERNED_WRITE call floor admits no completable action — and the direct-write tools honor a type's config-declared write_tier.

Tool Catalog Curation

Set CRUXIBLE_MCP_PROFILE to shrink the advertised catalog for focused clients:

Profile	Meaning
full	Default. Advertise every tool allowed by the active permission mode.
state_authoring	Tools for creating, inspecting, querying, and directly loading state.
review	Tools for queries, receipts, feedback, attestations, outcomes, and proposal-group review.

Set CRUXIBLE_MCP_TOOLS or CRUXIBLE_MCP_TOOL_ALLOWLIST to a comma-separated list of exact tool names for an explicit allowlist. Profile and allowlist curation are both intersected with CRUXIBLE_MODE.

Tool Prompt Style

Tool descriptions are written for non-coding MCP clients. Each description starts with when to use the tool, uses kit-user vocabulary, and avoids implementation details that do not help with tool choice.

Self-Describing Tool Descriptions

Where the loaded kit answers a question a tool leaves open, the served description also names it, so an agent can discover the config's vocabulary from the tool surface instead of being told it out of band:

Tool	Kit facts appended
cruxible_query, cruxible_list_queries, cruxible_describe_query	Named query names
cruxible_lock_workflow, cruxible_plan_workflow	Registered provider names
cruxible_run_workflow, cruxible_propose_procedure	Registered provider names and contract names with a short field preview

The Purpose lines documented below are the reviewed static descriptions; kit facts are appended to them and are never part of a tool's SCHEMA, which does not vary by kit. Long lists are truncated with a total.

The kit is resolved from local state only, so tools/list keeps answering when no daemon is reachable: the config named by CRUXIBLE_MCP_KIT_CONFIG, otherwise — in local mode only — the sole locally registered instance. A server pointed at a remote daemon (CRUXIBLE_SERVER_URL or CRUXIBLE_SERVER_SOCKET) describes only what CRUXIBLE_MCP_KIT_CONFIG names: a local registry record on that host belongs to some unrelated instance and says nothing about the kit the daemon serves. With no local instance, more than one, a remote transport and no explicit config, or an unreadable config, the static descriptions are served unchanged.

Working-Set Capture

Set CRUXIBLE_WORKING_SET_DIR to a directory path to opt the MCP server into agent-local working-set capture: entity/edge-shaped results returned by the read tools (cruxible_query, cruxible_query_inline, cruxible_get_entity, cruxible_inspect_entity, cruxible_list, cruxible_sample, cruxible_get_relationship) are ALSO recorded as revision-stamped working-set records rooted at that directory — the same record format, dedupe, and credential-scoped instance keys as the CLI's --ws capture (see the cruxible ws section of docs/cli-reference.md). Capture happens in the MCP server process, which is a client co-located with the agent; the daemon stays blind to it, and tool results are never changed by it.

When the variable is unset, capture is a hard no-op — zero behavior or performance change. Precedence for the cache root everywhere (including the cruxible ws verbs): explicit CRUXIBLE_WORKING_SET_DIR > the default ~/.cruxible/working-set.

The cache is NON-AUTHORITATIVE and its files are same-user-writable by design: any same-user process can rewrite records undetected. Directory/file permission hygiene (0700/0600) and symlink refusal reduce accidents, not adversaries; verify records with cruxible ws verify before trusting them.

cruxible_version

Permission: READ_ONLY

Purpose: Use when you need to confirm which cruxible build this MCP server is running.

Arguments: none.

Returns: Returns a JSON object with dynamic keys.

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_server_info

Permission: READ_ONLY

Purpose: Use when you need live daemon details such as state directory, version, and how many instances are loaded.

Arguments: none.

Returns: Top-level fields: server_required, state_dir, version, instance_count, auth_enabled, auth_required

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_init

Permission: READ_ONLY

Purpose: Use when you need to create a governed instance from a config or reconnect to an existing instance after a daemon restart.

Arguments:

Name	Required	Type	Description
root_dir	yes	string
config_path	no	string	null
config_yaml	no	string	null
data_dir	no	string	null
kits	no	array	null
bare	no	boolean	Skip the configured default base kit on kit init.

Returns: Top-level fields: instance_id, status, warnings

Side Effects: Creates a new instance or reloads an existing one.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_instance_backup

Permission: ADMIN

Purpose: Use when you need a portable same-identity backup of an instance, including its authoritative state database.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
artifact_path	yes	string
label	no	string	null

Returns: The backup artifact path and the instance identity it captured.

Side Effects: Writes a portable backup artifact to disk; does not mutate instance state.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_instance_restore

Permission: ADMIN

Purpose: Use when you need to restore a daemon-backed instance from a same-identity backup artifact.

Arguments:

Name	Required	Type	Description
artifact_path	yes	string
root_dir	no	string	null

Returns: The restored instance id and status.

Side Effects: Creates an instance directory from the artifact and registers it with the daemon.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_instance_relocate

Permission: ADMIN

Purpose: Use when you need to move a healthy daemon-backed instance to a new directory while preserving its identity; the registry is repointed to the new location.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
to_dir	yes	string
remove_source	no	boolean

Returns: The instance id and its new on-disk location.

Side Effects: Moves the instance directory and repoints the registry to the new location.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_validate

Permission: READ_ONLY

Purpose: Use when you need to check whether a Cruxible config is valid before creating or reloading an instance.

Arguments:

Name	Required	Type	Description
config_path	no	string	null
config_yaml	no	string	null

Returns: Top-level fields: valid, name, entity_types, relationships, named_queries, warnings

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_state_create_overlay

Permission: ADMIN

Purpose: Use when you need a local overlay instance based on a published upstream state release.

Arguments:

Name	Required	Type	Description
root_dir	yes	string
transport_ref	no	string	null
state_ref	no	string	null
kit	no	string	null
no_kit	no	boolean

Returns: Top-level fields: instance_id, manifest

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_lock_workflow

Permission: ADMIN

Purpose: Use when workflow inputs, providers, or artifacts changed and you need to refresh the workflow lock before running it.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
force	no	boolean

Returns: Top-level fields: lock_path, config_digest, providers_locked, artifacts_locked

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_plan_workflow

Permission: READ_ONLY

Purpose: Use when you need to preview the concrete steps a configured workflow would run without executing those steps.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
workflow_name	yes	string
input_payload	no	object	null

Returns: Top-level fields: plan

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_run_workflow

Permission: GOVERNED_WRITE

Purpose: Use when you need to execute a configured workflow and receive its output, receipts, traces, and apply instructions if it is a preview.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
workflow_name	yes	string
input_payload	no	object	null
decision_record_id	no	string	null

Returns: Top-level fields: workflow, output, receipt_id, mode, workflow_type, canonical, apply_digest, head_snapshot_id, committed_snapshot_id, apply_previews, query_receipt_ids, read_metadata, trace_ids, receipt, traces

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_apply_workflow

Permission: GRAPH_WRITE

Purpose: Use when a workflow preview returned an apply digest and you are ready to commit that exact workflow result.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
workflow_name	yes	string
expected_apply_digest	yes	string
expected_head_snapshot_id	no	string	null
input_payload	no	object	null
decision_record_id	no	string	null

Returns: Top-level fields: workflow, output, receipt_id, mode, workflow_type, canonical, apply_digest, head_snapshot_id, committed_snapshot_id, apply_previews, query_receipt_ids, read_metadata, trace_ids, receipt, traces

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_test_workflow

Permission: GOVERNED_WRITE

Purpose: Use when you need to run workflow tests declared by the active config.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
name	no	string	null

Returns: Top-level fields: total, passed, failed, cases

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_query

Permission: READ_ONLY

Purpose: Use when you need to run a named query from the active config and receive matching items plus a receipt. First call cruxible_list_queries or cruxible_describe_query when you do not know the query name, required params, result shape, or examples. For traversal queries, params must include the entry_point primary-key field, such as {'vehicle_id': 'V-123'} when the entry point is Vehicle and its primary key is vehicle_id; cruxible_schema shows entity primary keys. Items default to the compact output profile; ask for profile='standard' or 'full' when you need provenance or actor context. Pass layout='graph' for multi-row traversal reads: it returns each entity and relationship once as nodes/edges with results as ordered references, instead of duplicating them per row.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
query_name	yes	string
params	no	object	null
limit	no	integer	null
offset	no	integer	Number of results to skip before the returned window.
relationship_state	no	string	null
lifecycle_status	no	string	null
decision_record_id	no	string	null
profile	no	string	null
layout	no	string	Transport layout: rows (default, per-row items) or graph (normalized transport: nodes/edges carry each unique entity and relationship once, results preserves row order as index references, paths holds step-ref sequences; compact graph also interns repeated non-empty include maps in include_sets, referenced by integer includes values).

Returns: An object-rooted envelope {"result": ...} (MCP output schemas must be object-rooted; this result is a union of shapes). Inside result: items, receipt_id, receipt, total, limit, offset, truncated, limit_truncated, path_truncated, truncation_reasons, max_paths, max_paths_per_result, total_path_count, retained_path_count, steps_executed, result_shape, dedupe, relationship_state, lifecycle_status, param_hints, policy_summary (rows layout). With layout='graph' the items field is replaced by layout, nodes, edges, results, and paths; compact graph with retained includes also returns include_sets. Every other field is unchanged.

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_query_inline

Permission: READ_ONLY

Purpose: Use when you need a one-off bounded graph query without adding it to the config. Inline definitions use the configured named-query JSON shape plus a required name; promote repeated or workflow-critical queries into config. Items default to the compact output profile; ask for profile='standard' or 'full' when you need provenance or actor context. Pass layout='graph' to receive deduplicated nodes/edges with results as ordered references instead of per-row items.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
definition	yes	InlineQueryDefinition	Inline query definition object: same JSON shape as a configured named query (mode, returns, traversal, where, select, order_by, include, limit, max_paths, max_paths_per_result, ...) plus a required name.
params	no	object	null
limit	no	integer	null
relationship_state	no	string	null
lifecycle_status	no	string	null
decision_record_id	no	string	null
profile	no	string	null
layout	no	string	Transport layout: rows (default, per-row items) or graph (normalized transport: nodes/edges carry each unique entity and relationship once, results preserves row order as index references, paths holds step-ref sequences; compact graph also interns repeated non-empty include maps in include_sets, referenced by integer includes values).

Returns: An object-rooted envelope {"result": ...} (MCP output schemas must be object-rooted; this result is a union of shapes). Inside result: items, receipt_id, receipt, total, limit, offset, truncated, limit_truncated, path_truncated, truncation_reasons, max_paths, max_paths_per_result, total_path_count, retained_path_count, steps_executed, result_shape, dedupe, relationship_state, lifecycle_status, param_hints, policy_summary (rows layout). With layout='graph' the items field is replaced by layout, nodes, edges, results, and paths; compact graph with retained includes also returns include_sets. Every other field is unchanged.

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_list_queries

Permission: READ_ONLY

Purpose: Use when you need to discover the named queries available in the active config. Returns bounded summaries (name, entry point, required params); call cruxible_describe_query for one query's full definition. Pass detail='full' only when you truly need every definition expanded. If truncated is true, pass the returned continuation_token back as continuation to fetch the next page.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
detail	no	string	summary (default) returns bounded discovery cards; full returns complete definitions.
limit	no	integer
offset	no	integer
continuation	no	string	null

Returns: An object-rooted envelope {"result": ...} (MCP output schemas must be object-rooted; this result is a union of shapes). Inside result: items, total, limit, offset, truncated, read_revision, continuation_token

read_revision is the instance's monotonic state revision at read time — the freshness marker for pagination and caching. Receipts prove a computation happened; they never prove its inputs are still current.

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Stale continuation token after a mutation (409) or malformed token (422). - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_describe_query

Permission: READ_ONLY

Purpose: Use when you need the purpose, parameters, and result shape for one named query.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
query_name	yes	string

Returns: Top-level fields: name, mode, entry_point, required_params, returns, result_shape, dedupe, relationship_state, allow_relationship_state_override, select, order_by, include, limit, max_paths, max_paths_per_result, description, example_ids

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_receipt

Permission: READ_ONLY

Purpose: Use when you need to inspect the proof record for a previous query, write, workflow, feedback, or outcome.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
receipt_id	yes	string

Returns: Returns a JSON object with dynamic keys.

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_get_trace

Permission: READ_ONLY

Purpose: Use when you need the execution trace for one provider or workflow step.

Arguments:

Name	Required	Type	Description
instance_id	yes	string	Governed instance ID or local instance root.
trace_id	yes	string	Provider execution trace ID, usually returned by workflow run/apply/propose results.

Returns: Returns the persisted trace with provider metadata, retained input/output payload fields, payload digest/size metadata, status, timings, and error details when present. Payload fields follow the instance config's runtime.trace_payloads retention policy.

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Trace ID not found. - Permission mode too low for this tool.

cruxible_list_traces

Permission: READ_ONLY

Purpose: Use when you need to browse execution traces by workflow, provider, or page.

Arguments:

Name	Required	Type	Description
instance_id	yes	string	Governed instance ID or local instance root.
workflow_name	no	string	null
provider_name	no	string	null
limit	no	integer	Maximum trace summaries to return.
offset	no	integer	Number of summaries to skip.

Returns: Top-level fields: items, total, limit, offset, truncated

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Invalid limit or offset.

cruxible_feedback

Permission: GOVERNED_WRITE

Purpose: Use when a person or reviewer agent adjudicated one explicit relationship and you need to record support, rejection, or a correction. To record a DOUBT without adjudicating, use cruxible_attest with stance 'contradict' instead. Use edge_key only to disambiguate multiple stored edges with the same relationship tuple; receipt_id is optional for explicit-coordinate feedback.

Action tier: every live action this tool accepts — accept / reject / correct — adjudicates a claim and requires GRAPH_WRITE, so a GOVERNED_WRITE caller cannot successfully complete any of them (the tool's own GOVERNED_WRITE floor is the first gate, not a sufficient one; a refused adjudication also rolls back the FeedbackRecord it would have written). Deprecated approve delegates to accept with a structured warning; deprecated flag is accepted only to return its structured refusal and never mutates state. While CRUXIBLE_REFUSE_DIRECT_WRITES is set, accept / correct are refused too. correct requires a non-empty corrections object. To record a doubt at GOVERNED_WRITE without adjudicating, use cruxible_attest with stance contradict.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
receipt_id	no	string
action	yes	enum: accept, reject, correct, approve, flag	Deprecated approve delegates to accept; deprecated flag is a refused compatibility alias.
from_type	yes	string
from_id	yes	string
relationship_type	yes	string
to_type	yes	string
to_id	yes	string
edge_key	no	integer	null
reason	no	string
reason_code	no	string	null
scope_hints	no	object	null
corrections	no	object	null
group_override	no	boolean	Deprecated compatibility write; use force_review.
claim_id	no	string	null
source	no	string	null

Returns: Top-level fields: feedback_id, applied, receipt_id, deprecation_warnings

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_feedback_from_query

Permission: GOVERNED_WRITE

Purpose: Use when a query receipt and result index identify the relationship that needs feedback. This path requires receipt_id because the receipt/result selection is the target selector.

Action tier: every live action this tool accepts — accept / reject / correct — adjudicates a claim and requires GRAPH_WRITE, so a GOVERNED_WRITE caller cannot successfully complete any of them (the tool's own GOVERNED_WRITE floor is the first gate, not a sufficient one; a refused adjudication also rolls back the FeedbackRecord it would have written). Deprecated approve delegates to accept with a structured warning; deprecated flag is accepted only to return its structured refusal and never mutates state. While CRUXIBLE_REFUSE_DIRECT_WRITES is set, accept / correct are refused too. correct requires a non-empty corrections object. To record a doubt at GOVERNED_WRITE without adjudicating, use cruxible_attest with stance contradict.

Arguments:

Name	Required	Type	Description
instance_id	yes	string	Governed instance ID or local instance root.
receipt_id	yes	string	Query receipt ID.
result_index	yes	integer	Zero-based query result row index.
action	yes	enum: accept, reject, correct, approve, flag	Deprecated approve delegates to accept; deprecated flag is a refused compatibility alias.
reason	no	string	Reason for feedback.
reason_code	no	string	Structured feedback reason code.
scope_hints	no	object	Structured feedback scope hints.
corrections	no	object	Edge property corrections for action="correct".
group_override	no	boolean	Deprecated compatibility write; use force_review.
path_index	no	integer	Zero-based path segment index for path rows.
path_alias	no	string	Traversal alias for the selected path segment.
source	no	string	Deprecated and ignored; actor kind is derived from actor_context.

Returns: Top-level fields: feedback_id, applied, receipt_id, deprecation_warnings

Side Effects: Creates normal feedback records and feedback receipts through the existing edge-feedback path.

Common Errors: - Receipt is missing, not a query receipt, or result index is out of range. - Entity-shaped query rows do not contain relationship evidence. - Multi-hop path rows require exactly one of path_index or path_alias. - Selected path alias is missing or duplicated, or selected edge is no longer in the graph.

cruxible_feedback_batch

Permission: GOVERNED_WRITE

Purpose: Use when you need to record several relationship feedback decisions from the same review session.

Action tier: every live action this tool accepts — accept / reject / correct — adjudicates a claim and requires GRAPH_WRITE, so a GOVERNED_WRITE caller cannot successfully complete any of them (the tool's own GOVERNED_WRITE floor is the first gate, not a sufficient one; a refused adjudication also rolls back the FeedbackRecord it would have written). Deprecated approve in any item delegates to accept with a structured warning; deprecated flag is accepted only to return its structured refusal and never mutates state. While CRUXIBLE_REFUSE_DIRECT_WRITES is set, accept / correct are refused too. correct requires a non-empty corrections object. To record a doubt at GOVERNED_WRITE without adjudicating, use cruxible_attest with stance contradict.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
items	yes	array

Returns: Top-level fields: feedback_ids, applied_count, total, receipt_id, deprecation_warnings

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_outcome

Permission: GOVERNED_WRITE

Purpose: Use when you need to record what happened after a decision, query, workflow, or reviewed relationship.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
outcome	yes	enum: correct, incorrect, partial, unknown
receipt_id	no	string	null
anchor_type	no	enum: resolution, receipt
anchor_id	no	string	null
outcome_code	no	string	null
scope_hints	no	object	null
outcome_profile_key	no	string	null
detail	no	object	null
source	no	string	null

Returns: Top-level fields: outcome_id, deprecation_warnings

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_list

Permission: READ_ONLY

Purpose: Use when you need a paged list of entities, relationships, receipts, feedback, or outcomes with optional filters. Use resource_type='entities' with entity_type and optional fields to reduce payload size; use where for bounded property predicates such as {'status': {'eq': 'active'}}. Entity and edge items default to the compact output profile; ask for profile='standard' or 'full' when you need provenance or actor context. Always check truncated: when true, pass the returned continuation_token back as continuation (same filters) to fetch the next page; a stale-continuation error means state changed - restart from the first page. read_revision on the envelope is the state freshness marker; receipts prove computation, never freshness.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
resource_type	yes	enum: entities, edges, receipts, feedback, outcomes
entity_type	no	string	null
relationship_type	no	string	null
query_name	no	string	null
receipt_id	no	string	null
limit	no	integer
offset	no	integer
property_filter	no	object	null
where	no	object	null
operation_type	no	string	null
fields	no	array[string]	null
relationship_state	no	string	null
lifecycle_status	no	string	null
profile	no	string	null
continuation	no	string	null

Returns: Top-level fields: items, total, limit, offset, truncated, read_revision, continuation_token

continuation_token is present iff the page is truncated and resumable — the pagination loop is: check truncated, pass continuation_token back as continuation with the same filters. read_revision is the instance's monotonic state revision at read time; receipts prove computation, never freshness.

Side Effects: Read-only.

For entity lists, fields is an opt-in projection that reduces payload size after the caller has selected an entity type. It trims entity properties but always keeps entity_type and entity_id; it is not topic search. Use where for bounded property predicates on entity or edge lists, for example {"status": {"eq": "active"}} or {"dependency_basis": {"contains": "schema"}}. This is not semantic search. For resource_type="edges", this is a stored-relationship inspection surface: it may return pending, rejected, or otherwise non-live stored edges. Named queries are logical-state reads and apply relationship_state filtering, so use cruxible_query when you need live/reviewable truth rather than store inspection.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_evaluate

Permission: READ_ONLY

Purpose: Use when you need graph quality findings such as orphaned entities, coverage gaps, constraint issues, or candidate opportunities.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
max_findings	no	integer
exclude_orphan_types	no	array or null
severity_filter	no	array	Optional list of error, warning, or info severities to return.
category_filter	no	array	Optional list of evaluate categories to return.

Returns: Top-level fields: entity_count, edge_count, findings, summary, constraint_summary, quality_summary

Filtered calls still return full pre-filter summary, constraint_summary, and quality_summary counts. Agent triage example: request severity_filter=["error"] with max_findings=1 to check whether any error-level finding exists.

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_stats

Permission: READ_ONLY

Purpose: Use when you need quick counts of entity and relationship types in an instance.

Arguments:

Name	Required	Type	Description
instance_id	yes	string

Returns: Top-level fields: entity_count, edge_count, entity_counts, relationship_counts, head_snapshot_id

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_lint

Permission: READ_ONLY

Purpose: Use when you need a combined quality report for config, graph state, feedback, and outcome coverage.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
max_findings	no	integer
analysis_limit	no	integer
min_support	no	integer
exclude_orphan_types	no	array	null

Returns: Top-level fields: config_name, config_warnings, compatibility_warnings, evaluation, feedback_reports, outcome_reports, summary, has_issues

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_get_feedback_profile

Permission: READ_ONLY

Purpose: Use when you need the allowed feedback codes and guidance for a relationship type.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
relationship_type	yes	string

Returns: Top-level fields: found, relationship_type, profile

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_analyze_feedback

Permission: READ_ONLY

Purpose: Use when you need patterns from recorded feedback, such as common corrections or recurring review issues.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
relationship_type	yes	string
limit	no	integer
min_support	no	integer
decision_surface_type	no	string	null
decision_surface_name	no	string	null
property_pairs	no	array	null

Returns: Top-level fields: relationship_type, feedback_count, action_counts, source_counts, reason_code_counts, coded_groups, uncoded_feedback_count, uncoded_examples, constraint_suggestions, decision_policy_suggestions, quality_check_candidates, provider_fix_candidates, warnings

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_get_outcome_profile

Permission: READ_ONLY

Purpose: Use when you need the allowed outcome codes and guidance for a decision surface.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
anchor_type	yes	enum: resolution, receipt
relationship_type	no	string	null
workflow_name	no	string	null
surface_type	no	string	null
surface_name	no	string	null

Returns: Top-level fields: found, profile_key, anchor_type, profile, deprecation_warnings

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_analyze_outcomes

Permission: READ_ONLY

Purpose: Use when you need patterns from recorded outcomes for a query, workflow, relationship, or decision surface.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
anchor_type	yes	enum: resolution, receipt
relationship_type	no	string	null
workflow_name	no	string	null
query_name	no	string	null
surface_type	no	string	null
surface_name	no	string	null
limit	no	integer
min_support	no	integer

Returns: Top-level fields: anchor_type, outcome_count, outcome_counts, outcome_code_counts, coded_groups, uncoded_outcome_count, uncoded_examples, trust_adjustment_suggestions, workflow_review_policy_suggestions, query_policy_suggestions, provider_fix_candidates, debug_packages, workflow_debug_packages, warnings

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_schema

Permission: READ_ONLY

Purpose: Use when you need the active entity types, relationships, queries, workflows, and governance settings.

Arguments:

Name	Required	Type	Description
instance_id	yes	string

Returns: Returns a JSON object with dynamic keys.

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_sample

Permission: READ_ONLY

Purpose: Use when you need example entities of one type before writing a query or review. Items default to the compact output profile; ask for profile='standard' or 'full' for complete property bags and metadata.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
entity_type	yes	string
limit	no	integer
fields	no	array[string]	null
profile	no	string	null

Returns: Top-level fields: items, total, limit, offset, truncated, entity_type

Side Effects: Read-only.

fields is an opt-in projection for compact samples. It trims entity properties but always keeps entity_type and entity_id.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_inspect_entity

Permission: READ_ONLY

Purpose: Use when you need everything relevant about one entity within a bounded number of hops — the generic neighborhood read beneath named queries. Anchor on the entity, then expand: depth (1-4) sets the hop horizon; max_nodes and max_edges are explicit budgets and the response reports truncated with truncation_reasons instead of silently clipping. Filter with relationship_types and target_types; state selects relationship visibility exactly like query traversal (default all — every stored edge with its review/lifecycle markers, so pending edges in governed overlays are visible by default; an explicit state filters like traversal and edges_hidden_by_state counts edges at the explored frontier hidden by state alone). projection trims neighbor properties; payloads default to the compact output profile — ask for profile='standard' or 'full' when you need provenance or actor context. When the expanded read reports truncated on a budget, pass the returned continuation_token back as continuation (same parameters) to resume the expansion where it stopped; a stale-continuation error means state changed - restart the read.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
entity_type	yes	string
entity_id	yes	string
direction	no	string	incoming, outgoing, or both (default).
relationship_type	no	string	null
limit	no	integer	null
depth	no	integer	null
relationship_types	no	array	null
target_types	no	array	null
state	no	string	null
projection	no	array	null
max_nodes	no	integer	null
max_edges	no	integer	null
profile	no	string	null
continuation	no	string	null

Returns: An object-rooted envelope {"result": ...} (MCP output schemas must be object-rooted; this result is a union of shapes). Inside result: Legacy calls (no neighborhood argument): found, entity_type, entity_id, properties, metadata, neighbors, total_neighbors, read_revision. Expanded calls: found, entity_type, entity_id, properties, metadata (the anchor card), depth, state, nodes (each with depth and lifecycle markers), edges (each with review/lifecycle markers), truncated, truncation_reasons (node_budget/edge_budget/depth), nodes_returned, edges_returned, edges_hidden_by_state (edges at the explored frontier that passed every other filter but were excluded solely by an explicit state; always present, 0 under state=all), read_revision, continuation_token (present iff truncated on a budget — depth-horizon truncation is a different read, not a resumable page; the resumed pages are disjoint and their union is exactly the untruncated result set). read_revision marks state freshness; receipts prove computation, never freshness.

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_inspect_entity_history

Permission: READ_ONLY

Purpose: Use when you need receipt-derived property changes for one entity type or entity.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
entity_type	yes	string
entity_id	no	string	null
limit	no	integer
offset	no	integer

Returns: Top-level fields: entity_type, entity_id, items, total, legacy_entity_write_count, warnings

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_inspect_ontology

Permission: READ_ONLY

Purpose: Use when orienting before a query or a write: compact entity and relationship property contracts, enum vocabularies, topology, and configured write policies.

Arguments:

Name	Required	Type	Description
instance_id	yes	string

Returns: Top-level fields: view, payload

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_inspect_workflows

Permission: READ_ONLY

Purpose: Use when you need to understand the workflows declared by the active config.

Arguments:

Name	Required	Type	Description
instance_id	yes	string

Returns: Top-level fields: view, payload

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_inspect_queries

Permission: READ_ONLY

Purpose: Use when you need to understand configured queries and their parameters.

Arguments:

Name	Required	Type	Description
instance_id	yes	string

Returns: Top-level fields: view, payload

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_inspect_governance

Permission: READ_ONLY

Purpose: Use when you need to review feedback, outcome, group, and policy settings.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
limit	no	integer

Returns: Top-level fields: view, payload

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_inspect_overview

Permission: READ_ONLY

Purpose: Use when you need a single high-level summary of the instance.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
limit	no	integer

Returns: Top-level fields: view, payload

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_add_relationship

Permission: GRAPH_WRITE

Purpose: Use when you need to add or update a small number of explicit relationships and the endpoint entities already exist. Set pending=true when the edge should enter relationship review state instead of immediately becoming live.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
relationships	yes	array
dry_run	no	boolean	false

Each relationship may pass citation_handles beside the unchanged source_evidence locators. Handles are resolved to canonical revision-pinned source evidence before mutation guards run.

Returns: Top-level fields: added, updated, pending_conflicts, updated_group_backed_edges, receipt_id

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_add_entity

Permission: GRAPH_WRITE

Purpose: Use when you need to add or update a small number of explicit entities.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
entities	yes	array
dry_run	no	boolean	false

Returns: Top-level fields: entities_added, entities_updated, identity_warnings, receipt_id. A config-declared identity_hint match leaves the write successful and adds identity_warnings[].similar_existing_entity with the existing entity ID and matched properties. Config-declared unique_by and id_pattern violations are typed DataValidationError failures instead.

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_batch_direct_write

Permission: GRAPH_WRITE

Purpose: Use when you need to validate or apply one coherent batch of explicit entities and relationships; set dry_run first.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
payload	yes	BatchDirectWritePayload	Object with entities (entity inputs), relationships (relationship inputs, each optionally carrying citation_handles and referencing shared_evidence_keys), and shared_evidence (map of key to shared evidence refs, source evidence, or citation handles).
dry_run	no	boolean	Validate the payload without mutating graph state.

Returns: Top-level fields: dry_run, valid, entities_added, entities_updated, relationships_added, relationships_updated, validation_errors, validation_warnings, identity_warnings, evidence_sources_used, pending_conflicts, updated_group_backed_edges, receipt_id. A config-declared identity_hint match leaves the batch valid and adds identity_warnings[].similar_existing_entity; unique_by and id_pattern remain hard typed validation failures.

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_supersede_claim

Permission: GRAPH_WRITE

Purpose: Use when the settled, receipted adjudication replaces one claim with an already-existing live same-type successor.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
claim_id	yes	string	Predecessor claim; must be lifecycle-active with review not pending/rejected.
successor_claim_id	yes	string	Existing live claim of the SAME relationship type. This verb links, it never creates the successor.
reason	yes	string	Required. A settled transition with no reason is refused — the corpus would be starving itself.
evidence_ref	no	EvidenceRef	null

Returns: Top-level fields: action, claim, reason, successor, receipt_id

Side Effects: A settled adjudication. Writes typed claim_id supersession pointers in BOTH directions (successor.supersedes, predecessor.superseded_by), moves the predecessor to superseded, stamps closed_at/closed_by, and records one mutation receipt naming the subject, transition, reason, and successor. The predecessor stays resolvable by claim_id afterwards. Properties are carried verbatim from the exact addressed edge; parallel siblings on the same tuple are untouched.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Empty reason; self-supersession; successor missing, not live, of a different relationship type, or already superseding another claim; predecessor not lifecycle-active or under pending/rejected review.

cruxible_retract_claim

Permission: GRAPH_WRITE

Purpose: Use when the settled, receipted adjudication withdraws a claim without a successor.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
claim_id	yes	string	Claim to retract; must be lifecycle-active with review not pending/rejected.
reason	yes	string	Required.
evidence_ref	no	EvidenceRef	null

Returns: Top-level fields: action, claim, reason, receipt_id

Side Effects: A settled adjudication. Moves the claim to retracted, stamps closed_at/closed_by, and records one mutation receipt. Content is carried verbatim — a retraction never rewrites properties, and it succeeds even when the type's schema has since grown a required property. The claim_id stays resolvable with its settled state.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Empty reason; the claim is already settled, or its review is pending/rejected.

cruxible_supersede_entity

Permission: GRAPH_WRITE

Purpose: Use when the settled, receipted adjudication replaces one entity with an already-existing live same-type successor; edges do not migrate.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
entity_type	yes	string	Predecessor entity type.
entity_id	yes	string	Predecessor entity ID; must be live.
successor_entity_type	yes	string	Must equal entity_type — cross-type supersession is a modeling error.
successor_entity_id	yes	string	Existing live entity. May be a DIFFERENT id from the predecessor (rename-via-supersession).
reason	yes	string	Required.
evidence_ref	no	EvidenceRef	null

Returns: Top-level fields: action, entity, reason, successor, stranded_live_edge_count, receipt_id

Side Effects: A settled adjudication. Writes typed entity_type/entity_id supersession pointers in BOTH directions, moves the predecessor to superseded, stamps closed_at/closed_by, and records one mutation receipt. Inbound edges do NOT migrate: a renamed successor starts with zero edges and re-pointing is the caller's job, so a rename can look "broken" until you re-point.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Empty reason; self-supersession; successor missing, not live, of a different entity type, or already superseding another entity; predecessor not live.

cruxible_retire_entity

Permission: GRAPH_WRITE

Purpose: Use when the settled, receipted adjudication retires an entity without cascading edges.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
entity_type	yes	string	Entity type.
entity_id	yes	string	Entity ID; must be live.
reason	yes	string	Required.
evidence_ref	no	EvidenceRef	null

Returns: Top-level fields: action, entity, reason, stranded_live_edge_count, receipt_id

Side Effects: A settled adjudication. Moves the entity to retired, stamps closed_at/closed_by, and records one mutation receipt. Reports stranded_live_edge_count — still-live attached edges, which stay visible in edge-level reads but drop out of traversals; cascade is deliberately not performed. The retired entity_id is preserved rather than freed: a later DIRECT add/update of that id is refused instead of minting a doppelganger with none of the history, while governed sources (workflow apply, group resolve) still reach it pending the deferred reinstate verb.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Empty reason; the entity is already retired or superseded.

cruxible_add_constraint

Permission: ADMIN

Purpose: Use when you need to add a graph quality rule that future evaluations should check.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
name	yes	string
rule	yes	string
severity	no	enum: warning, error
description	no	string	null

Returns: Top-level fields: name, added, config_updated, warnings

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_add_decision_policy

Permission: ADMIN

Purpose: Use when you need to record a policy that affects how a decision surface should be handled.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
name	yes	string
applies_to	yes	enum: query, workflow
relationship_type	yes	string
effect	yes	enum: suppress, require_review
match	no	DecisionPolicyMatchInput	null
description	no	string	null
rationale	no	string
query_name	no	string	null
workflow_name	no	string	null
expires_at	no	string	null

Returns: Top-level fields: name, added, config_updated, warnings

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_reload_config

Permission: ADMIN

Purpose: Use when you need to replace or reload the active config for an instance.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
config_path	no	string	null
config_yaml	no	string	null
allow_orphans	no	boolean	Allow stored graph types absent from the incoming config (default false: strandings refuse the reload with per-type counts).
config_source_manifest	no	object	Source paths and digests for uploaded composed YAML. File-based handlers build this automatically.

Returns: Top-level fields: config_path, updated, warnings, type_delta, strandings

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_config_status

Permission: READ_ONLY

Purpose: Use when you need to check source drift or active config integrity.

Arguments: instance_id is required. current_source_manifest is optional; without it, only the active materialized digest is checked.

Returns: status, config_path, materialized_matches, sources_checked, composed_matches, changed_sources, and recorded provenance.

cruxible_propose_workflow

Permission: GOVERNED_WRITE

Purpose: Use when a workflow proposes reviewable relationship changes instead of writing them directly.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
workflow_name	yes	string
input_payload	no	object	null
decision_record_id	no	string	null

Returns: Top-level fields: workflow, output, receipt_id, mode, workflow_type, canonical, group_id, group_status, review_priority, suppressed, suppressed_members, query_receipt_ids, read_metadata, trace_ids, prior_resolution, policy_summary, receipt, traces

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_create_decision_record

Permission: GOVERNED_WRITE

Purpose: Use when you need to open a tracked decision before gathering evidence, running workflows, or recording outcomes.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
question	yes	string
subject_type	no	string	null
subject_id	no	string	null
opened_by	no	string	null

Returns: Top-level fields: record, events, receipt_id, deprecation_warnings

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_get_decision_record

Permission: READ_ONLY

Purpose: Use when you need the current state and optional event history for one decision.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
decision_record_id	yes	string
include_events	no	boolean

Returns: Top-level fields: record, events, receipt_id

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_list_decision_records

Permission: READ_ONLY

Purpose: Use when you need to find decision records by status, subject, class, or page.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
status	no	string	null
subject_type	no	string	null
subject_id	no	string	null
decision_class	no	string	null
limit	no	integer
offset	no	integer

Returns: Top-level fields: items, total, limit, offset, truncated

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_list_decision_events

Permission: READ_ONLY

Purpose: Use when you need the event timeline for decisions, optionally filtered by receipt.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
decision_record_id	no	string	null
receipt_id	no	string	null
trace_id	no	string	null
status	no	string	null
limit	no	integer
offset	no	integer

Returns: Top-level fields: items, total, limit, offset, truncated

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_finalize_decision_record

Permission: GOVERNED_WRITE

Purpose: Use when a tracked decision has a final answer and rationale.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
decision_record_id	yes	string
final_decision	yes	string
decision_class	yes	enum: recommended, rejected, deferred, escalated
rationale	no	string

Returns: Top-level fields: record, events, receipt_id

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_abandon_decision_record

Permission: GOVERNED_WRITE

Purpose: Use when a tracked decision should be closed without a final decision.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
decision_record_id	yes	string
reason	no	string

Returns: Top-level fields: record, events, receipt_id

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_attest

Permission: GOVERNED_WRITE

Purpose: Use when you observed evidence supporting, contradicting, or leaving you unsure about one relationship claim. Supply evidence for support or contradict; a note is optional but encouraged for unsure. If the claim does not exist yet, a 'support' stance CREATES it as a pending (unreviewed) claim from 'properties' — 'contradict' and 'unsure' are refused on an absent claim.

Arguments:

Name	Required	Type	Description
instance_id	yes	string	Governed instance ID.
relationship_type	yes	string	Relationship type of the target claim.
from_type	yes	string	Source endpoint entity type.
from_id	yes	string	Source endpoint entity ID.
to_type	yes	string	Target endpoint entity type.
to_id	yes	string	Target endpoint entity ID.
stance	yes	string	support, contradict, or unsure.
observed_at	yes	string	ISO-8601 time when the world was observed; it cannot be in the future.
evidence_refs	no	array or null	Evidence pointers; at least one is required for support and contradict.
edge_key	no	integer or null	Unstable disambiguation hint; tuple coordinates remain authoritative.
claim_id	no	string or null	Stable claim identity; the preferred disambiguator, taking precedence over edge_key. Supplying both with disagreeing values is refused.
properties	no	object or null	Required relationship properties when absent support creates a pending claim; ignored on attach.
note	no	string or null	Optional observation note, encouraged for unsure.
idempotency_key	no	string or null	Retry-safe key scoped to the claim tuple and resolved actor.

Returns: The immutable attestation, pending-claim creation marker, warnings, replay marker, and receipt ID.

Side Effects: Appends an attestation and receipt; absent support may also create one pending claim.

cruxible_list_attestations

Permission: READ_ONLY

Purpose: Use when you need immutable observation history for one claim tuple or stance.

Arguments:

Name	Required	Type	Description
instance_id	yes	string	Governed instance ID.
relationship_type	no	string or null	Relationship type; provide all five claim coordinates together.
from_type	no	string or null	Source endpoint type; provide all five claim coordinates together.
from_id	no	string or null	Source endpoint ID; provide all five claim coordinates together.
to_type	no	string or null	Target endpoint type; provide all five claim coordinates together.
to_id	no	string or null	Target endpoint ID; provide all five claim coordinates together.
stance	no	string or null	Optional support, contradict, or unsure filter.
limit	no	integer	Maximum records.
offset	no	integer	Records to skip.

Returns: Standard list envelope with immutable records, latest dispositions, and tuple-resolution markers.

Side Effects: Read-only.

cruxible_attestation_queue

Permission: READ_ONLY

Purpose: Use when a reviewer needs live claims with open current-content contradictions, aggregated per claim.

Arguments:

Name	Required	Type	Description
instance_id	yes	string	Governed instance ID.
limit	no	integer	Maximum per-claim entries.
offset	no	integer	Entries to skip.

Returns: Standard list envelope with per-claim contradiction counts, a distinct_actor_count (the plain number of distinct attesting actors — it is not weighted, discounted, or otherwise scored), and latest observation time.

Side Effects: Read-only.

cruxible_resolve_attestation

Permission: GRAPH_WRITE

Purpose: Use when a reviewer needs to uphold, correct, or invalidate an attestation without changing its immutable history.

Arguments:

Name	Required	Type	Description
instance_id	yes	string	Governed instance ID.
attestation_id	yes	string	Immutable attestation being reviewed.
verdict	yes	string	upheld, corrected, or invalidated.
note	no	string or null	Optional reviewer explanation.
follow_up_receipt_id	no	string or null	Receipt for a follow-up correction or re-adjudication.

Returns: The appended disposition and receipt ID.

Side Effects: Appends a disposition and receipt; never mutates the target claim or attestation.

cruxible_open_outcome_contract

Permission: GOVERNED_WRITE

Purpose: Use when a decision is about to be accepted and you need to state in advance what result counts as success, how it will be measured, when to check it, and when the commitment expires.

Preconditions: The subject already exists, and its entity type is covered by a requires_resolution_contract mutation guard on the accepting transition; otherwise opening is refused. See the outcome_tracking adoption convention.

Arguments:

Name	Required	Type	Description
instance_id	yes	string	Governed instance ID.
entity_type	yes	string	Subject entity type; the subject must already exist.
entity_id	yes	string	Subject entity ID.
description	yes	string	Free-text success criterion that survives mechanical rot.
check_at	yes	string	ISO-8601 time when the outcome is first checked; must precede expires_at.
expires_at	yes	string	ISO-8601 time when an unresolved contract ages into overdue.
measurement	yes	object	{kind: query, query_name, params, expect} or {kind: attestation, relationship_type, from_type, from_id, to_type, to_id}; validated against the live config at open.
idempotency_key	no	string or null	Retry-safe key scoped to the subject and resolved actor.

Returns: The prepared contract, the idempotent-replay marker, and the receipt ID.

Side Effects: Appends a contract and receipt; never mutates the subject. Multiple open contracts on one subject are legal. A query measurement pins both the query definition digest and the effective execution options, so a later run under a different relationship_state cannot resolve it.

cruxible_resolve_outcome

Permission: GOVERNED_WRITE

Purpose: Use when you checked an outcome contract and need to record what reality said: satisfied, contradicted, or indeterminate.

Preconditions: The contract was activated by a successful requires_resolution_contract-guarded acceptance. A prepared contract that was never activated has nothing to resolve and simply expires.

Arguments:

Name	Required	Type	Description
instance_id	yes	string	Governed instance ID.
contract_id	yes	string	Activated contract being answered.
verdict	yes	string	satisfied, contradicted, or indeterminate.
observed_at	yes	string	ISO-8601 observation time; satisfied requires it at or after check_at. It is recorded, but the cited evidence's own timestamps are what bind the verdict.
evidence_refs	no	array or null	Evidence pointers; at least one is required for satisfied and contradicted.
note	no	string or null	Observation note; required for contradicted.
resolving_query_receipt_id	no	string or null	Receipt of the query run that observed a query-measured outcome.
resolving_attestation_ids	no	array or null	Attestation ids backing an attestation-measured outcome.

Returns: The immutable resolution and receipt ID.

Side Effects: Appends one resolution and receipt; never mutates the subject. A contract accepts exactly one standing resolution until a reviewer overturns it. Cited evidence must postdate the contract's opening by its own clock (and, for satisfied, the declared check time); a query receipt must carry a read_revision stamp and match the pinned execution options, and an attestation invalidated by a reviewer cannot be cited.

cruxible_list_outcome_contracts

Permission: READ_ONLY

Purpose: Use when you need the outcome contracts on a subject with their status, activation, and standing answer.

Arguments:

Name	Required	Type	Description
instance_id	yes	string	Governed instance ID.
entity_type	no	string or null	Filter to one subject entity type.
entity_id	no	string or null	Filter to one subject entity ID.
status	no	string or null	Filter the returned page by derived status: prepared, open, or resolved.
limit	no	integer	Maximum contracts per page.
offset	no	integer	Contracts to skip.

Returns: Standard list envelope with per-contract status, activation, standing resolution, disposition, expiry, and subject-drift markers.

Side Effects: Read-only.

cruxible_outcome_due

Permission: READ_ONLY

Purpose: Use when you need the outcome work list: contracts due for checking, overdue contracts, or contradicted outcomes awaiting a reviewer.

Arguments:

Name	Required	Type	Description
instance_id	yes	string	Governed instance ID.
queue	no	string	due (past check_at), overdue (past expires_at), or contradicted (undisposed).
limit	no	integer	Maximum entries.
offset	no	integer	Entries to skip.

Returns: Standard list envelope of activated contracts on live subjects, oldest check time first.

Side Effects: Read-only.

cruxible_dispose_outcome_resolution

Permission: GRAPH_WRITE

Purpose: Use when a reviewer needs to uphold or overturn a recorded outcome; an overturn re-opens the contract for one new answer.

Arguments:

Name	Required	Type	Description
instance_id	yes	string	Governed instance ID.
resolution_id	yes	string	Immutable resolution being reviewed.
verdict	yes	string	upheld or overturned.
note	no	string or null	Optional reviewer explanation.

Returns: The appended disposition and receipt ID.

Side Effects: Appends a disposition and receipt; an overturned verdict re-opens the contract for exactly one further resolution. Dispositions are latest-wins: a further disposition on the same resolution supersedes the previous one (unless that one was an overturn a later resolution already answered). Never mutates the subject.

cruxible_propose_procedure

Permission: GOVERNED_WRITE

Purpose: Use when you need to propose a bounded composition of procedure-exported actions for independent review.

Arguments:

Name	Required	Type	Description
instance_id	yes	string	Governed instance ID.
definition	yes	object	Restricted procedure definition.
supersedes_procedure_id	no	string or null	Immutable procedure being replaced.
evidence_refs	no	array or null	Distillation evidence refs.

Returns: The pending procedure record, transition receipt ID, and warnings: non-blocking authoring lint findings (declared-but-unused contract_in fields, read-implying names backed by side-effecting providers, stringified JSON-object step inputs, a declared string field passed whole into an arguments parameter, read steps bundled with side-effecting ones or more than five provider steps in one procedure, and provider-call budget headroom the run can never reach). Statically impossible definitions are refused rather than warned about.

Side Effects: Persists a pending procedure and receipt.

cruxible_list_procedures

Permission: READ_ONLY

Purpose: Use when you need to find governed procedures by lifecycle status or page and compare their run-ledger track records before choosing one.

Arguments:

Name	Required	Type	Description
instance_id	yes	string	Governed instance ID.
status	no	string or null	pending, live, rejected, or retired.
limit	no	integer	Maximum records.
offset	no	integer	Records to skip.

Returns: Standard list envelope with procedure records. Each record carries a track_record block summarizing its run ledger: runs, the exhaustive verdict buckets succeeded, failed, refused, budget_exceeded, and in_flight (started but not yet finalized, so runs always equals their sum), last_succeeded_at, the most frequent top_refusal_reason, and linked_outcomes (reserved, always null). top_refusal_reason is null when a procedure has never been refused and for refusals recorded before the reason was tracked. These buckets are read state, so running a procedure advances read_revision (once at start, once at finalization, refusals included) and a truncated page cannot be resumed across an invocation.

Side Effects: Read-only.

cruxible_get_procedure

Permission: READ_ONLY

Purpose: Use when you need one procedure's definition, resolved input field schema, budget, precondition, lifecycle, and run-ledger track record.

Arguments:

Name	Required	Type	Description
instance_id	yes	string	Governed instance ID.
procedure_id	yes	string	Procedure ID.

Returns: A procedure object envelope carrying the same track_record block as the list surface, plus contract_in_schema, the contract_in shape resolved against the active config: the contract description, fields (each with name, type, required, and any default, enum, enum_ref, description, and the nested json_schema a json-typed field is validated against), allow_extra, and input_example — a worked payload carrying every key the caller must supply, filled with type-appropriate values (an enum's first value, a declared default, a literal the field description quotes, else a placeholder for the type). A field carrying a default is reported as not required and is absent from input_example. input_example is {} for a contract that declares no fields but accepts extras (cruxible.JsonObject) and is omitted for one that accepts no payload at all (cruxible.EmptyInput). contract_in_schema is null when the definition's contract_in no longer resolves in the active config.

Side Effects: Read-only.

cruxible_resolve_procedure

Permission: GRAPH_WRITE

Purpose: Use when an independent reviewer needs to accept or reject a pending procedure.

Arguments:

Name	Required	Type	Description
instance_id	yes	string	Governed instance ID.
procedure_id	yes	string	Procedure ID.
action	yes	string	accept or reject.
expected_version	yes	integer	Optimistic lifecycle version.
reason	no	string or null	Required when rejecting.

Returns: The transitioned procedure and receipt ID.

Side Effects: Accepts or rejects a pending procedure and writes a receipt.

cruxible_withdraw_procedure

Permission: GOVERNED_WRITE

Purpose: Use when you changed your mind about a procedure YOU proposed and it is still pending: withdraw it instead of proposing a renamed variant. The name is immediately free to re-propose.

Arguments:

Name	Required	Type	Description
instance_id	yes	string	Governed instance ID.
procedure_id	yes	string	Procedure ID.
expected_version	yes	integer	Optimistic lifecycle version.
reason	no	string or null	Optional note on why it was withdrawn.

Returns: The withdrawn procedure and receipt ID.

Side Effects: Moves a pending proposal to withdrawn and writes a receipt. Withdrawing your own proposal needs only this tool's GOVERNED_WRITE floor; withdrawing another actor's pending proposal is refused below GRAPH_WRITE.

cruxible_retire_procedure

Permission: GRAPH_WRITE

Purpose: Use when a reviewer needs to retire a live immutable procedure.

Arguments:

Name	Required	Type	Description
instance_id	yes	string	Governed instance ID.
procedure_id	yes	string	Procedure ID.
expected_version	yes	integer	Optimistic lifecycle version.
reason	yes	string	Non-empty retirement reason.

Returns: The retired procedure and receipt ID.

Side Effects: Retires a live procedure and writes a receipt.

cruxible_run_procedure

Permission: GOVERNED_WRITE

Purpose: Use when you need to execute one live procedure through the generic receipted runner.

Arguments:

Name	Required	Type	Description
instance_id	yes	string	Governed instance ID.
procedure_id	yes	string	Procedure ID.
input_payload	yes	object	Input validated against the procedure contract.

Returns: Procedure, run, output, receipt, and step-output fields.

Side Effects: Writes a crash-safe run record, provider traces where applicable, and a receipt.

cruxible_list_procedure_runs

Permission: READ_ONLY

Purpose: Use when you need invocation history or crash-visible started tombstones for one procedure.

Arguments:

Name	Required	Type	Description
instance_id	yes	string	Governed instance ID.
procedure_id	yes	string	Procedure ID.
limit	no	integer	Maximum records.
offset	no	integer	Records to skip.

Returns: Standard list envelope containing finalized runs and status: started/verdict: null tombstones. A refused run also carries the refusal_reason classification that the procedure's top_refusal_reason counts; it is null on every other verdict and on refusals recorded before the reason was tracked.

Side Effects: Read-only.

cruxible_propose_group

Permission: GOVERNED_WRITE

Purpose: Use when you need to create a review group for candidate relationship changes.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
relationship_type	yes	string
members	yes	array
thesis_text	no	string
thesis_facts	no	object	null
analysis_state	no	object	null
signal_sources_used	no	array	null
suggested_priority	no	string	null
expected_pending_version	no	integer	null
proposed_by	no	string	null

Each member and each nested signal may pass citation_handles beside the unchanged source_evidence locators.

Returns: Top-level fields: group_id, signature, status, review_priority, member_count, prior_resolution, suppressed, suppressed_members, policy_summary, receipt_id, deprecation_warnings

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_resolve_group

Permission: GRAPH_WRITE

Purpose: Use when a reviewer approves, rejects, or otherwise resolves a pending group.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
group_id	yes	string
action	yes	enum: approve, reject
expected_pending_version	yes	integer
rationale	no	string
stamp_existing	no	boolean	On approve, bless each surviving pre-existing edge (member tuple already live) with this group's review status and provenance instead of skipping it.
resolved_by	no	string	null

Returns: Top-level fields: group_id, action, edges_created, edges_skipped, resolution_id, receipt_id, skipped_members (per-member skip explanations: identity plus skip_kind, reason, stamped), edges_stamped, deprecation_warnings

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_update_trust_status

Permission: GRAPH_WRITE

Purpose: Use when you need to mark a prior group resolution as trusted, invalidated, or otherwise updated.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
resolution_id	yes	string
trust_status	yes	enum: trusted, watch, invalidated
reason	no	string

Returns: Top-level fields: resolution_id, trust_status, receipt_id

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_get_group

Permission: READ_ONLY

Purpose: Use when you need the details and members for one candidate relationship group.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
group_id	yes	string

Returns: Top-level fields: group, members, resolution, bucket_status, member_review

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_list_groups

Permission: READ_ONLY

Purpose: Use when you need to find candidate relationship groups by type, status, or page.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
relationship_type	no	string	null
status	no	enum: pending_review, applying, resolved, withdrawn, auto_resolved	null
limit	no	integer
offset	no	integer

Returns: Top-level fields: items, total, limit, offset, truncated

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_list_resolutions

Permission: READ_ONLY

Purpose: Use when you need to review past group decisions by relationship type or action.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
relationship_type	no	string	null
action	no	enum: approve, reject	null
limit	no	integer
offset	no	integer

Returns: Top-level fields: items, total, limit, offset, truncated

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_group_status

Permission: READ_ONLY

Purpose: Use when you need the latest status for a group or for a known group signature.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
group_id	no	string	null
signature	no	string	null

Returns: Top-level fields: signature, relationship_type, thesis_text, thesis_facts, latest_trust_status, accepted_tuple_count, pending_delta_count, pending_group_id, pending_version, latest_approved_resolution_id, approved_history

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_state_publish

Permission: ADMIN

Purpose: Use when you need to publish the current instance state as an immutable release.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
transport_ref	yes	string
state_id	yes	string
release_id	yes	string
compatibility	yes	enum: data_only, additive_schema, breaking

Returns: Top-level fields: manifest

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_create_snapshot

Permission: GRAPH_WRITE

Purpose: Use when you need to mark the current state with a named snapshot.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
label	no	string	null

Returns: Top-level fields: snapshot

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_list_snapshots

Permission: READ_ONLY

Purpose: Use when you need to browse available snapshots for an instance.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
limit	no	integer
offset	no	integer

Returns: Top-level fields: items, total, limit, offset, truncated

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_register_source_artifact

Permission: GOVERNED_WRITE

Purpose: Use when you need to register a source document so relationship evidence can cite stable chunks from it.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
source_path	yes	string	Path to the local source document.
source_artifact_id	no	string	null
source_kind	no	enum: markdown	Only markdown is currently supported.
source_retention	no	enum: manifest_only, archive	manifest_only stores chunk hashes only; archive also stores the document content.
original_uri	no	string	null
label	no	string	null

Returns: Top-level fields: source_artifact_id, artifact_revision_id, revision_handle, revision, source_kind, source_retention, original_uri, label, content_hash, byte_count, parser_version, archived, archive_content_hash, chunks (each chunk includes citation_handle)

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Invalid or duplicate caller-supplied source_artifact_id. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_dereference_source_evidence

Permission: READ_ONLY

Purpose: Use when you need to read back a registered source evidence chunk and verify its expected content hash.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
source_artifact_id	yes	string	Artifact ID returned by cruxible_register_source_artifact.
artifact_revision_id	no	string	null
chunk_id	no	string	null
heading_path	no	array	null
block_selector	no	string	null
expected_content_hash	no	string	null

Returns: Top-level fields: status (one of available, drifted, unavailable, revision_bytes_not_retained — a pinned read of a superseded revision whose bytes were never archived, which is not drift), source_artifact_id, chunk_id, content_hash, expected_artifact_hash, current_artifact_hash, body_origin, body, reason, chunk, artifact_revision_id, revision_unpinned

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_clone_snapshot

Permission: ADMIN

Purpose: Use when you need a new local instance created from an existing snapshot. On auth-enabled daemons the result carries a one-time admin_credential token for the new instance - save it immediately; it is never shown again.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
snapshot_id	yes	string
root_dir	yes	string

Returns: Top-level fields: instance_id, snapshot, admin_credential (auth-enabled daemons only: a one-time ADMIN token for the new instance — deliver it to the operator immediately; it is never shown again)

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_state_status

Permission: READ_ONLY

Purpose: Use when you need to see whether an overlay is connected to an upstream state and whether pulls are available.

Arguments:

Name	Required	Type	Description
instance_id	yes	string

Returns: Top-level fields: upstream

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_state_diff

Permission: READ_ONLY

Purpose: Use when you need the structured difference between two state coordinates - a snapshot vs current, current vs the materialized upstream release, or two snapshots. The complete body is persisted and content-addressed by diff_digest; treat the result as a reviewable plan only when artifact_complete is true, and re-read the whole body with artifact_digest.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
from_coordinate	no	string	current, a snap_ id, upstream, or origin; defaults to the parent of the head snapshot.
to_coordinate	no	string	Defaults to current. added means present here only.
sections	no	array	Restrict to entities / edges / procedures.
entity_types	no	array	Restrict entities to these types.
relationship_types	no	array	Restrict edges to these relationship types.
buckets	no	array	Report only these buckets; counts stay whole.
changed_only	no	boolean	Suppress added/removed items.
max_items_per_bucket	no	integer	Per-bucket cap for the returned view (default 500, minimum 1); the persisted artifact is never capped.
artifact_digest	no	string	Re-read a persisted artifact by content address instead of computing a diff.

Returns: Top-level fields: diff_digest, view_digest, artifact_complete, artifact_ref, diff_engine_version, artifact_schema_version, artifact_trust, normalizations, liveness, selector, from_coordinate, to_coordinate, omitted_sections, context, sections, summary, view, default_basis, receipt_id

Side Effects: Reads are not side-effect-free: persists a state_diff receipt and a content-addressed artifact under .cruxible/diffs/. Neither touches graph state or advances read_revision. Both persistence failures fail the read.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_state_pull_preview

Permission: READ_ONLY

Purpose: Use when you need to preview upstream state changes before applying them.

Arguments:

Name	Required	Type	Description
instance_id	yes	string

Returns: Top-level fields: current_release_id, target_release_id, compatibility, apply_digest, warnings, conflicts, lock_changed, upstream_entity_delta, upstream_edge_delta

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_state_pull_apply

Permission: ADMIN

Purpose: Use when a pull preview returned an apply digest and you are ready to apply it.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
expected_apply_digest	yes	string

Returns: Top-level fields: release_id, apply_digest, pre_pull_snapshot_id, receipt_id

Side Effects: May create governed state, graph state, config changes, snapshots, or audit records according to its permission tier.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_get_entity

Permission: READ_ONLY

Purpose: Use when you need to fetch one entity by type and ID. The payload defaults to the compact output profile; ask for profile='standard' or 'full' for the complete property bag and metadata.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
entity_type	yes	string
entity_id	yes	string
profile	no	string	null

Returns: Top-level fields: found, entity_type, entity_id, properties, metadata

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_get_relationship

Permission: READ_ONLY

Purpose: Use when you need to fetch one relationship by endpoints and relationship type.

Arguments:

Name	Required	Type	Description
instance_id	yes	string
from_type	yes	string
from_id	yes	string
relationship_type	yes	string
to_type	yes	string
to_id	yes	string
edge_key	no	integer	null

Returns: Top-level fields: found, from_type, from_id, relationship_type, to_type, to_id, edge_key, properties, metadata

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Missing config names, stale locks, invalid workflow/query/group identifiers, or invalid request shape where applicable.

cruxible_relationship_lineage

Permission: READ_ONLY

Purpose: Use when you need the provenance, review state, feedback, and receipts for one relationship.

Arguments:

Name	Required	Type	Description
instance_id	yes	string	Governed instance ID or local instance root.
from_type	yes	string	Source entity type.
from_id	yes	string	Source entity ID.
relationship_type	yes	string	Relationship type.
to_type	yes	string	Target entity type.
to_id	yes	string	Target entity ID.
edge_key	no	integer	null

Returns: Top-level fields: found, relationship, provenance, group, resolution, source_workflow_receipt_id, source_trace_ids, warnings

Side Effects: Read-only.

Common Errors: - Unknown instance_id or missing daemon configuration. - Permission mode too low for this tool. - Ambiguous relationship tuple without edge_key.