alter design

The design document (ALTER_INTEGRATION.md) records how an integration uses Alter — the goal, the runtime identity (app vs agent), the key type, principals, providers, and how grants are acquired — in machine-checkable YAML frontmatter. alter design validate runs a deterministic rule set over it so identity mistakes (for example, an app runtime key serving an agent workload) fail before anything is provisioned. Pair with alter verify, which re-validates the design and then checks the implementation against it.

alter design validate [--design <path>] [--remote] [--app <app-id-or-name>] [--output json|jsonl|table]

validate

Validates the design document. Local by default — no network and no login required, so it can gate automation. Exit code 0 means the design passed (warnings allowed); 1 means rule violations; 4 means the design file was not found.

Flag	Default	Description
--design <path>	./ALTER_INTEGRATION.md	Path to the design document.
--remote	off	Additionally verify the design’s providers against the app’s actual configuration. Requires alter auth login and an app (pass --app, link a workspace, or set ALTER_APP_ID).
--app <app-id-or-name>	resolved app	App for --remote; falls back to ALTER_APP_ID or the linked workspace.
--output <format>	json	json, jsonl, or table. Because the report is one object, jsonl falls back to pretty-printed JSON.

The rules enforced include:

• Identity ↔ key type — runtime_identity: agent requires key_type: agent (a per-agent key from alter agents mint-key); runtime_identity: app requires key_type: runtime (from alter keys mint).
• Goal ↔ grant acquisition — user-data acquires grants via browser consent; backend-secret via managed-secret grants; agent via delegation or an agent-bound managed-secret grant (created via the CLI or dashboard — never the SDK).
• Principal hygiene — user and agent principals never share one credential path.
• Human-owned trust steps declared — idp: jwt-resolution requires identity-provider setup to be listed in dashboard_steps. The field records that an operator must confirm this trust decision; the operator may run alter identity-providers create or use the dashboard. Identity-provider update and deletion remain dashboard-only.

JSON output reports status, the rules_version, and each violation’s rule, severity, and message.