---
summary: "DesignMD Foundry Pi adapter integration contract."
read_when:
  - "Before changing DesignMD Foundry extension tools or skill behavior."
system4d:
  container: "Pi-facing adapter over DesignMD Foundry CLI workflows."
  compass: "Expose verified design-contract operations without pretending optional external tools are installed."
  engine: "Pi tool request -> DesignMD CLI command -> structured tool result."
  fog: "Foundry path or optional external CLIs may be missing on an operator machine."
---

# Integration contract

`pi-designmd-foundry` is a Pi adapter over the DesignMD Foundry CLI. It should not duplicate parser/linter/exporter logic.

## Stable initial tool boundary

The extension exposes operations that are readiness-verified in DesignMD Foundry:

- `designmd_lint`
- `designmd_export`
- `designmd_agent_prompt`
- `designmd_oat_visual_snapshot`
- `designmd_openpencil_prompt`
- `designmd_openpencil_info`
- `designmd_openpencil_lint`
- `designmd_openpencil_export` for verified formats only: `svg`, `png`, `jpg`, `webp`, `fig`
- `designmd_import_penpot`
- `designmd_palette_from_text`
- `designmd_penpot_mcp_inspect` for read-only active-file bridge-board snapshots through official Penpot MCP
- `designmd_penpot_mcp_bridge` for plan-by-default / explicit-apply DesignMD canvas bridge board create/update operations through official Penpot MCP
- `designmd_penpot_mcp_export` for read-only SVG export of an existing DesignMD bridge board through official Penpot MCP
- `designmd_session_plan` for local `designmd.session-plan.v1` Watch Mode planning packets without canonical authority claims
- `designmd_session_variants` for local `designmd.session-variants.v1` proposal lanes without accepted-variant or canonical direction claims
- `designmd_session_handoff` for local `designmd.session-handoff.v1` prompts that bind one proposal lane into agent/operator guidance without canonical authority claims
- `designmd_session_guided_run` for local `designmd.guided-design-run.v1` orchestration packets that prepare plan, memory, variants, handoff, and report-back instructions without executing Pi or claiming canonical authority
- `designmd_session_closeout` for local `designmd.session-closeout.v1` Watch Mode evidence packets without canonical promotion claims
- `designmd_session_promotion_candidate` for local `designmd.promotion-candidate.v1` owner-review packets without promotion, publish, merge, or AK/society mutation claims
- `designmd_readiness`

## Non-goals for the initial package

- No direct save of canonical `DESIGN.md`.
- No provider-backed LLM generation.
- No continuous Penpot webhook/plugin synchronization; the MCP bridge wrapper is limited to one explicit bounded board creation from `designmd.canvas-bridge.v1`, while the MCP export wrapper is limited to read-only SVG export of an existing bridge board.
- No OpenPencil JSX export wrapper until JSX behavior is fixture-verified.
- No claim that `open-pencil`/`openpencil` or `pigmnts` live CLIs exist unless DesignMD readiness reports them.

## Runtime path resolution

The extension resolves the Foundry root in this order:

1. Tool parameter `foundryRoot`.
2. Environment variable `DESIGNMD_FOUNDRY_HOME`.
3. Default local checkout: `~/ai-society/softwareco/owned/designmd-foundry`.

The CLI entrypoint uses `dist/cli.js` when present, otherwise source mode through Node type stripping.

## Safety posture

Tools return command metadata and bounded stdout/stderr. Canonical writes are avoided; generated prompt, token, palette, and snapshot text is returned to the agent/operator for review. Artifact writes require an explicit output path, as with restricted OpenPencil export, Penpot MCP bridge-apply SVG proof output, and read-only Penpot MCP existing-board SVG export. The session plan, variants, handoff, closeout, and promotion-candidate tools can materialize only local Watch Mode artifacts/checks and explicitly do not create or promote AK/society authority. Variant lanes are proposals until accepted through the owning surface, and promotion candidates are owner-review packets only. Penpot MCP inspect and export are read-only. Penpot MCP mutation requires `apply: true` and a human-connected plugin; plan mode is the default. Update selectors such as `updateLatest` and `updateBoardId` may target only existing DesignMD bridge boards, are mutually exclusive, and remain non-mutating unless `apply: true` is set. Bridge plans/results include `designmd.penpot-mcp-transaction.v1` selector, target-resolution, postcondition, and rollback-classification evidence.

## Optional Watch Mode reporting

When `DESIGNMD_SESSION_ENDPOINT` points at a Foundry session API root such as `http://127.0.0.1:8788/api/session`, every tool reports start/pass/fail activity to the current or newly created session. Output-producing tools also attach previewable artifacts when possible.

Reporting must stay optional and fail-open:

- no hidden dependency on a running Foundry server
- no tool failure just because session reporting failed
- no canonical authority claim for session/activity/artifact logs
- optional bearer token via `DESIGNMD_SESSION_TOKEN` or `DESIGNMD_API_TOKEN`

Use `DESIGNMD_SESSION_ID` only when the operator wants to bind reports to an explicit existing session.