Workbench + export pipeline

When to use

• Building or refactoring Workbench UI panels, onboarding, or actions.
• Updating Workbench state (UAM v1, scopes, blocks, targets) or scan handoff.
• Changing compile/export behavior, adapters, or target options.

Quick map

• Workbench UI + state:

  src/components/workbench/*

  +

  src/hooks/useWorkbenchStore.ts

• Compile endpoint:

  src/app/api/compile/route.ts

• Compile + adapters:

  src/lib/compile/compile.ts

  ,

  src/lib/adapters/*

  ,

  src/lib/uam/compile/*

• Export UX:

  src/components/workbench/ExportPanel.tsx

Workflow

1. Confirm entry point

   • Identify whether the change is UI-only, state-only, or export pipeline.
   • Workbench state lives in

     useWorkbenchStore

     ; it normalizes UAM v1 and syncs legacy fields.

2. State + targets

   • Targets are stored on the UAM v1 definition; changes should flow through

     setUam

     + target helpers.
   • When adjusting scan → Workbench handoff, review

     applyScanContext

     and

     SCAN_TOOL_TARGET_MAP

     .

3. Export/compile behavior

   • Export panel calls

     /api/compile

     (debounced) and displays the compilation result.
   • Update compile or adapter logic in

     src/lib/compile/compile.ts

     and

     src/lib/adapters/*

     .
   • Keep file path collisions and warnings surfaced (compile result is shown in Workbench).

4. Adapters

   • Adapters define target-specific output; register new adapters in the registry.
   • If adapter output or options change, update

     docs/architecture/skills-export-matrix.md

     .

5. Tests + checks

   • Run

     npm run compile

     ,

     npm run lint

     ,

     npm run test:unit

     .
   • If you change export behavior, check any Workbench/E2E references and update tests as needed.

References

• codex/skills/markdowntown-workbench/references/workbench-ui.md
• codex/skills/markdowntown-workbench/references/compile-adapters.md

Guardrails

• Prefer UAM v1 helpers (

  createUamTargetV1

  ,

  normalizeUamTargetsV1

  ) to avoid drift.
• Keep Workbench strings aligned with

  docs/ux/microcopy-guidelines.md

  .