FOR AI — module brief

Copy the block below into an agent prompt when you want it to create or modify a Placard Marketplace module. It is self-contained on purpose.

Human walkthrough: creating-modules.md.

You are building a Placard Marketplace module for a self-hosted Placard instance.

## Goal
Ship a prebuilt zip the admin uploads under Settings → Module marketplace, or attach to a public GitHub Release for “Install from GitHub”. There is no in-container TypeScript compile and no npm-install path into Placard.

## Deliverable zip layout
placard.module.json
server/index.js    # ESM; must export function createModule()
web/index.js       # browser ESM; export page component(s) named in the manifest
web/assets/…       # optional icon/cover

## Manifest (placard.module.json)
- id: "family.feature" (example places.pick)
- name, version, description
- permissions: subset of ["places.read", "search.query", "media.read"]
- nav: [{ "path": "/m/<id>", "label": "…", "slot": "primary" | "more" }]
  Each nav item may set mobileIcon: "dices" (Lucide kebab-case name) for phone bottom navigation only. Matches the built-in menu icon style and active color. Missing/unknown/unavailable names fall back to the module icon image, then a puzzle icon. Desktop navigation stays text-only.
- source: "upload"   # required for Marketplace zips
- sdkVersion: "1.0.0"  # new capabilities require SDK 1; legacy SDK 0 modules remain supported
- serverEntry: "./server/index.js"
- webEntry: "./web/index.js"
- icon (optional): "web/assets/icon.svg" — square SVG/PNG used in marketplace and phone navigation; include the file in the zip. Paths are relative to the package root; absolute HTTPS or root-relative URLs also work. Phone navigation falls back to a puzzle icon if absent or unavailable.
- webRoutes: [{ "path": "/m/<id>", "exportName": "YourPage" }]
- actions (optional): [{ "id": "open", "label": "…", "keywords": "…", "path": "/m/<id>" }]
  CMD+K Actions group; selecting navigates to `path`. Hidden when the user hides the module (same as nav).
- mcpTools (optional): [{ "name": "local_tool_name", "title": "…", "description": "…" }]
  Local names only. Host exposes global MCP name:
  {id with "." → "_"}__{local_name}
  Example: places.pick + pick_place → places_pick__pick_place

## Server contract
export function createModule() {
  return {
    createHttpApp?: (ctx) => …,  // requests under /api/m/<id>/*
    mcpTools?: [{ def: { name, description, … }, handler }]
  }
}
- Use ctx.hostFetch("POST /api/search", { method, headers, body }) for library queries.
- Persist private data under ctx.dataDir, never ctx.rootDir (installed code is replaced on updates).
- Do NOT import core SQL, Effect services, or patch host tables.
- HTTP and MCP should share the same business helpers.
- Do not hard-code tools into Placard’s core MCP set — implement createModule + optional mcpTools on the module.

## Web contract
- Export the component named by webRoutes[].exportName.
- Bundle for the browser. Do NOT ship React/react-dom/react-router in the zip.
- Alias React / jsx-runtime / react-router Link to globalThis.__PLACARD_PLUGIN__ (host bridge), as in packages/modules/skeleton (or sibling repo placard-places-pick).
- Call your API at /api/m/<id>/… with credentials included (cookies).

## Build practice that works
- esbuild (or equivalent) fully bundles server for platform node, format esm.
- Fully bundle web for browser; externalize nothing that uploads cannot resolve.
- Zip the pack directory; admin uploads the zip.

## Install / verify on an instance
1. Settings → Module marketplace → Choose .zip, or paste a public GitHub repo URL
2. For GitHub distribution: attach the zip as a Release asset (prefer *.placard-module)
3. Extract path: PLACARD_MODULES_DIR/<id>/ (Compose volume "modules")
4. Enable instance module; user toggles “shown in nav” and “Allow MCP”
5. UI at /m/<id>; HTTP at /api/m/<id>/*; MCP tools listed in Settings → MCP

## Skeleton starter (prefer this as the base)
- Path: packages/modules/skeleton/
- Module id: example.skeleton
- Build zip: pnpm --filter @placard/module-skeleton build:zip
- Output: packages/modules/skeleton/dist/example.skeleton-0.1.0.zip
- Includes GET /api/m/example.skeleton/hello, SkeletonPage, CMD+K action "Open Skeleton"
  (manifest actions → /m/example.skeleton), MCP tool skeleton_hello
  (global name example_skeleton__skeleton_hello), React host shims, build:zip script.
- Clone/rename that package (change id, paths, API constant, page export) instead of
  inventing a new layout.

## Other references
- Upload / GitHub wheel example: sibling repo placard-places-pick (next to the Placard monorepo)
- SDK types: packages/module-sdk/

## Out of scope
Sandboxing, public npm registry install into Placard, private GitHub repos / PATs, pinning a non-latest Release, remote catalog URL, household-only gating in the manifest, compiling TS inside Docker.