Agent workflows

Use Inkfinite’s command-line tools to inspect, validate, and change documents.

Workflow

For a saved file, follow the same sequence for every change:

1. Run inspect --summary --json and keep the returned heads.
2. Use query --detail --limit N --json to read only the relevant records.
3. Build the smallest transaction that satisfies the request.
4. Run the mutation with --dry-run --json.
5. Apply it only after the dry run passes.
6. Validate the document and render the affected page, role, or selection.

Prefer semantic roles, names, and tags over coordinates when they identify one record. If a selector matches multiple shapes, narrow it with an exact ID. Do not guess which one the human meant.

Live documents

For a document open in the desktop app, add --app to a structured shape, connect, or layout command instead of changing its file. Validated live edits commit immediately. Use the permissioned MCP interface when model-controlled changes require authorization or review.

Permissions

Shape and layer locks apply to every CLI transaction. Do not work around a lock by editing a child or bypassing the CLI. The direct CLI does not enforce agent_editable or hide records in invisible layers. Permissioned integrations can use that metadata as part of their own policy.

MCP access

Run inkfinite-mcp as a local stdio server. It discovers open desktop sessions through authenticated local IPC. Pass standalone files as command arguments, or list them in INKFINITE_MCP_DOCUMENTS using the platform path separator:

inkfinite-mcp board.inkfinite research.inkfinite

The server exposes tools to list sessions and documents, inspect heads and metadata, query records, preview or apply ordered mutations, import SVG, and submit desktop proposals. Start with inkfinite_capabilities, then select a source and inspect its current heads. Use dry_run: true before a direct mutation. inkfinite_propose sends a validated transaction to an open desktop session, and inkfinite_proposal_status reports the review outcome. Standalone files do not have a review store.

The server defaults to read-only access. Set INKFINITE_MCP_POLICY to a JSON policy when a model needs write access. The default rule and per-session rules use read, create, modify, delete, layout, and propose scopes. Per-document rules are keyed by canonical path and per-session rules by desktop session ID.

{
	"default": {
		"permissions": {
			"read": true,
			"create": true,
			"modify": true,
			"delete": false,
			"layout": true,
			"propose": true
		},
		"hidden_layers": "deny",
		"require_agent_editable": true
	}
}

MCP filters hidden layers unless hidden_layers is allow, and changes to existing shapes require agent_editable by default. inkfinite-core still checks document, layer, shape, and ancestor locks. Policy failures use authorization_denied; lock and validation failures retain their document error codes. A denied MCP operation is not permission to switch to the direct CLI.

Raw app apply validates and commits a prepared transaction.

Conflicts

Document heads are preconditions. If a file mutation exits with code 5, inspect the current heads, query the affected records again, and rebuild the transaction from that state. Do not remove lock files, copy an older document over the current file, or silently drop intervening edits.

Record-version preconditions protect individual objects in the same way. A failed version check means the object changed after the agent inspected it.

Skill

The repository includes an installable agent skill at .agents/skills/inkfinite. It covers CLI, MCP, and reviewed desktop workflows and points agents to generated help and tool schemas.