Beam logoBeam

Reference Contracts

Stable JSON shapes connect CLI, MCP, cache, and cloud.

Design context, snapshots, asset manifests, compare results, warnings, and evidence models use explicit schema versions and deterministic fields.

Design context responses include source metadata, snapshot summary, implementation brief, image path, warnings, estimated token count, confidence, and build readiness.

Snapshots persist source, hash, Beam version, mode, timestamps, and paths to raw payloads, briefs, images, and asset manifests.

Asset manifests list exported assets with node IDs, names, formats, scale, output paths, and source URLs. Compare results report score, target URL, differences, and artifact paths.

json
1{2  "schemaVersion": "1.0",3  "source": {4    "fileKey": "abc",5    "nodeId": "1:2",6    "url": "https://www.figma.com/file/..."7  },8  "snapshot": {9    "id": "snapshot_01J...",10    "fromCache": true11  },12  "brief": {13    "frame": {},14    "layout": {},15    "components": [],16    "tokens": {},17    "assets": [],18    "implementationNotes": []19  },20  "warnings": [],21  "estimatedTokens": 1800022}

Run Sequence

  1. Add schemaVersion to every shared object.
  2. Keep CLI JSON, MCP responses, local cache files, and cloud sync shapes aligned.
  3. Add warnings for omitted or uncertain data instead of dropping fields silently.
  4. Preserve local file paths so agents can open exported images, assets, manifests, and compare artifacts.

Expected Output

A contract response should be deterministic, parseable, credential-safe, and stable enough for agents and scripts to consume without scraping human text.

Files And Artifacts

  1. .beam/cache/briefs/<snapshot-id>.json
  2. .beam/cache/snapshots/<snapshot-id>.json
  3. .beam/cache/assets/<snapshot-id>.manifest.json
  4. .beam/cache/compare/<compare-id>/result.json

Next Step

When a field changes, update CLI output, MCP output, tests, and docs together.

Recovery Paths

  1. If a script breaks after a contract change, verify schemaVersion and migration behavior.
  2. If a field contains a secret, remove it from the contract and rotate affected credentials.
  3. If agents need more detail, add explicit fields rather than embedding prose-only instructions.