WCP AI — Build & Release Guide

The complete guide to building and releasing WCP widgets and agents using AI. Give your AI a single URL and it will walk you through every design decision, write the code, and publish the result — from first question to running Docker container and GitHub Release.

This guide covers the WCP AI skill chain — a family of GitHub repositories, each containing an AI-SKILL.md file. Paste any skill's URL into any AI chat (Claude, GPT-4, Gemini — whatever you use) and the AI is immediately oriented in the WCP ecosystem and ready to guide you through that phase of the build.

The chain has two halves:

• Build chain (wcp-ai-build*) — design and implement your artefact: a containerised widget or a native host agent
• Release chain (wcp-ai-release*) — validate, version, publish to Docker Hub, and create a GitHub Release

Companion resources

• widgetcontextprotocol.com — the full WCP protocol specification
• dev.widgetcontextprotocol.com — the developer guide: widget implementation detail, endpoint reference, theme adoption
• wcpp.widgetcontextprotocol.com — the WCP Portability Protocol: packaging, sharing, and importing widgets

How It Works

The AI skill file pattern

Each repository in the WCP AI family contains an AI-SKILL.md file. This file is the AI's entry point — it tells the AI what the skill does, what questions to ask, what decisions to make, and where to hand off next. You give your AI the raw GitHub URL of the file and the skill is loaded.

No configuration, no installation, no plugins. The pattern works in any AI that can read a URL.

The routing pattern

wcp-ai-build is the entry point for all builds. It orients the AI in the WCP ecosystem, asks what you want to build, and routes to the appropriate specialist skill. Specialist skills own their domain — they don't repeat the routing logic. wcp-ai-release is the entry point for all releases; it establishes the stage and mode, then routes to the widget or agent release skill.

The technology negotiation pattern

Whenever a technology decision is required (language, framework, packaging tool), the AI follows a consistent pattern:

1. Ask if you have a preference. If yes, use it immediately.
2. If no preference: present 3–4 industry-standard options, each with a brief description and a single key trade-off.
3. State the AI default explicitly — the choice the AI will make if you defer. The default is always in active production use at major organisations, well-documented, and conservatively modern.
4. If you say "your choice" or don't respond with a preference, the AI uses the default without further prompting.

The default is not a recommendation — it is a fallback. You can always override it.

Consent at every public push

The release pipeline enforces explicit developer consent before every public push — to Docker Hub, to GitHub Releases, to any public repository. The AI describes exactly what it is about to do and waits for your approval. It closes every session with a written summary of every action taken.

Quick Start

Copy one of these instructions and paste it into any AI chat to begin.

Not sure yet — start here

Read https://github.com/penrithbeacon/wcp-ai-build/blob/main/AI-SKILL.md and help me build a WCP artefact.

The AI will ask what you want to build and route you to the right specialist skill.

Build a widget directly

Read https://github.com/penrithbeacon/wcp-ai-build-widget/blob/main/AI-SKILL.md and help me build a WCP widget.

Build a macOS agent directly

Read https://github.com/penrithbeacon/wcp-ai-build-agent-mac/blob/main/AI-SKILL.md and help me build a WCP agent for macOS.

Release a widget or agent

Read https://github.com/penrithbeacon/wcp-ai-release/blob/main/AI-SKILL.md and release my WCP artefact.

The Skill Chain

The full pipeline from first question to published release:

Build Chain

Release Chain

Building a Widget — Prerequisites

• Docker Desktop — installed and running on your development machine
• Git — for version control; a GitHub account for hosting the repo and publishing releases
• Any AI coding assistant — Claude, GPT-4, Gemini, or any AI that can read a URL and write code
• A free port — each widget runs on its own port; check your existing docker-compose.yml files to confirm the port is unused
• Penrith Beacon Design Studio (optional but recommended) — test your widget in a real WCP host dashboard before releasing

You do not need to know Python, Flask, Docker, or any specific technology before you start. The AI will propose options and proceed with a well-supported default if you prefer to defer the technology decision.

Step 1 — Orient

Read https://github.com/penrithbeacon/wcp-ai-build/blob/main/AI-SKILL.md and help me build a WCP widget.

The wcp-ai-build skill orients your AI in the WCP ecosystem. At this step, the AI:

• Reads the WCP protocol overview — what a widget is, what a host is, how they communicate
• Asks what you want to build (widget, agent, or something else)
• Confirms it is a widget and provides the URL for wcp-ai-build-widget
• Hands off — you don't need to paste the new URL yourself, the AI gives it to you

If you already know you're building a widget, you can skip directly to Step 2 and paste the wcp-ai-build-widget URL directly.

Step 2 — Design

The wcp-ai-build-widget skill walks through a structured conversation before writing a line of code. The phases:

Phase A — Intent

What does this widget do? Who is the user? What problem does it solve? The AI uses your answers to shape everything that follows.

Phase B — Components

How many visual components? For each component: what does it display, what WCP role does it serve (widget, ancillary, banner, coda), and what default card size does it need?

Phase C — Data & Behaviour

Does the widget need external data (API calls, local files, system data)? Does it need user configuration (POST /widget/configure)? Does it need persistent storage across sessions? Can it run as multiple independent instances?

Phase D — Advanced Features

Does the widget need Publish to Web (POST /widget/publish — serve a standalone SPA)? WCP export (GET /widget/export.wcp)?

Phase E — Infrastructure

Technology choice (applying the negotiation pattern) and port assignment. For the technology decision, the standard options are:

Step 3 — Build & Test

Once design decisions are complete, the AI generates the complete file set and builds the container:

1. Reads the widget build specification from wcp-ai-automation — all mandatory endpoint requirements, naming conventions, and compliance rules
2. Generates: Dockerfile, docker-compose.yml, entry point (e.g. app.py), and all templates
3. Implements all mandatory WCP endpoints: GET /wcp, GET /widget/wcp, GET /widget/health, GET /widget/theme, component views
4. Implements optional endpoints selected in Phase D
5. Builds the Docker image and runs the container locally
6. Verifies each WCP endpoint with curl — the AI checks that every response matches the protocol spec

Step 4 — Release

Read https://github.com/penrithbeacon/wcp-ai-release/blob/main/AI-SKILL.md and release my WCP widget.

The wcp-ai-release skill:

1. Establishes release stage: beta (pre-production, -beta suffix) or production
2. Establishes release mode: dry-run (validate everything, push nothing) or live
3. Routes to wcp-ai-release-widget

The wcp-ai-release-widget skill then:

1. Runs the audit checklist against your widget source
2. Bumps the version in docker-compose.yml, specification.md, and any other version-bearing files
3. Commits and pushes to your private repo (HarrisonOfTheNorth) and then to your public repo (penrithbeacon)
4. Builds a multi-platform Docker image: linux/amd64 + linux/arm64
5. Pushes to Docker Hub with version tag and floating tags (beta or latest)
6. Creates a GitHub Release on the public repo
7. Provides a written summary of every action taken — you sign it off

What Is an Agent?

An agent is a native process that runs on the host machine — not inside Docker. Agents extend widget capabilities by providing access to host resources that Docker containers cannot reach directly: the local file system, running processes, OS APIs, credentials stored in the system keychain.

An agent exposes a small HTTP API on 127.0.0.1 only (loopback). WCP widgets running in Docker containers reach it via host.docker.internal — the Docker bridge hostname that resolves to the host machine's IP.

The Markdown Editor Agent — a concrete example

The Markdown Editor widget (wcp-widget-markdown-editor) needs to read and write files on the user's Mac. Docker containers have an isolated filesystem — they cannot browse ~/Documents directly. The Markdown Editor Agent (wcp-agent-markdown-editor) runs natively on macOS, exposes endpoints for /ls, /read, /write, and /mkdir, and the widget calls those endpoints via host.docker.internal:7891.

When do you need an agent?

• Your widget needs to read or write files on the user's machine
• Your widget needs to call a process or tool installed on the host (e.g. git, ffmpeg)
• Your widget needs access to OS APIs that Docker cannot reach (keychain, Bluetooth, local network discovery)
• You want to avoid embedding host credentials inside a Docker container

Step 1 — Design (Platform-Agnostic)

Read https://github.com/penrithbeacon/wcp-ai-build-agent/blob/main/AI-SKILL.md and help me build a WCP agent.

The wcp-ai-build-agent skill establishes the agent design before touching any platform-specific detail:

• Purpose — what host data or capabilities does this agent provide? Which widgets will consume it?
• Communication — port number, loopback-only binding, health endpoint
• Endpoints — what does the API look like? (health, data, control)
• Persistent state — config file, local database?
• Auto-start — agents intended for production use must auto-start at login

Once the design is clear, the AI asks which platform(s) you are targeting and provides the platform-specific skill URL.

Step 2 — Build (macOS)

Read https://github.com/penrithbeacon/wcp-ai-build-agent-mac/blob/main/AI-SKILL.md and help me build a WCP agent for macOS.

The wcp-ai-build-agent-mac skill builds a native macOS agent. Technology options:

The AI also asks about architecture: Apple Silicon only (ARM64), Intel only (x86_64), or a universal binary (both). Apple Silicon is the default for developer tools targeting modern Macs.

What the AI builds

1. The agent HTTP server — Python file listening on 127.0.0.1:<port>
2. A launchd plist — ~/Library/LaunchAgents/com.<org>.<agent>.plist — so the agent auto-starts at login
3. An install script and an uninstall script
4. A build-pkg.sh script: packages the agent as a .app bundle via py2app, then wraps it in a .pkg installer via pkgbuild

Step 3 — Release

Read https://github.com/penrithbeacon/wcp-ai-release/blob/main/AI-SKILL.md and release my WCP agent.

The release pipeline for agents is simpler than for widgets — there is no Docker image to build. The wcp-ai-release-agent skill:

1. Runs the audit checklist
2. Bumps the version and commits
3. Runs build-pkg.sh to produce the final .pkg installer
4. Pushes to private repo (HarrisonOfTheNorth) then public repo (penrithbeacon)
5. Creates a GitHub Release on the public repo with the .pkg attached as a release asset

Worked Example: Markdown Editor

A complete end-to-end walkthrough — from first design question to published beta release — using the Markdown Editor widget and agent as the reference implementation.

The Markdown Editor is a WYSIWYG markdown editor with an integrated folder browser. It consists of two artefacts built as a pair:

The widget was built first, then the agent, then both were released together. The sections that follow document the design decisions, implementation patterns, and release steps — the kind of detail that is useful whether you are studying this as a tutorial or picking up a specific technique.

Widget Design Decisions

Phase A — Intent

A WYSIWYG markdown editor embedded in the Penrith Beacon dashboard. The user can browse their local filesystem (via the agent), open .md files, edit them with live preview, and save. A secondary goal: the editor should be publishable as a standalone SPA for sharing.

Phase B — Components

Single WCP component — a full-page widget. The file browser is an overlay panel within the widget page rather than a separate WCP component. This keeps the manifest simple and avoids the complexity of cross-component state synchronisation.

• Role: widget (full-page)
• Default card size: 6×4 (wide, tall)

Phase C — Data & Behaviour

• External data: none directly — all file I/O goes through the agent API
• Configuration: POST /widget/configure — root folder path, agent URL, initial theme
• Persistent storage: named Docker volume for the widget's config JSON
• Multi-instance: yes — multiple editor instances can run at different ports, each with its own root folder

Phase D — Advanced Features

• Publish to Web: yes — POST /widget/publish generates a standalone SPA and pushes it to the widget container's web root. Allows sharing a document as a rendered markdown page.
• WCP export: not included in v1.1.0-beta

Phase E — Infrastructure

• Technology: Python + Flask (AI default — consistent with all 9 existing WCP reference widgets)
• Port: 3746 (confirmed unused by checking existing docker-compose.yml files across the widget ecosystem)

Full theme system

The Markdown Editor implements the complete WCP theme adoption protocol: it accepts postMessage theme updates from the host, applies all CSS variables, and additionally supports a custom theme creator — users can create, name, import (.wcpt files), and delete custom themes. The active theme persists in the widget's config volume.

Implementation Highlights

Six patterns from the Markdown Editor implementation that apply broadly to any WCP widget:

1. Folder picker with history stack

The folder browser uses an overlay panel with a _pickerHistory array to track navigation. The ↑ Up button pops the last path from the stack rather than splitting the path string — this correctly handles paths with unusual characters and avoids off-by-one errors at the filesystem root.

let _pickerHistory = [];

async function pickerBrowse(path, pushCurrent = true) {
  if (pushCurrent && pickerCurrentPath) _pickerHistory.push(pickerCurrentPath);
  pickerCurrentPath = path;
  // ... render directory listing ...
}

function pickerUp() {
  if (!_pickerHistory.length) return;
  const prev = _pickerHistory.pop();
  pickerBrowse(prev, false);  // false: don't push current when going up
}

2. Toolbar path display

The main widget toolbar shows the absolute path of the currently open folder. This is updated in loadDir() every time the directory changes — simple but crucial for a file browser embedded in a fullscreen widget where there is no OS title bar:

const absPath = rel ? rootPath + '/' + rel : rootPath;
document.getElementById('toolbar-path').textContent = absPath;
document.getElementById('btn-up').disabled = !rel;

3. Agent health badge

The widget polls /agent/status on boot and on every file operation. The badge in the toolbar shows agent: connected (green) or agent: offline (red). This gives the user immediate feedback when the agent is not running — with a clear "install the agent" prompt rather than a cryptic network error.

4. macOS .app bundle exclusion

macOS application bundles (.app, .framework, .bundle, .plugin) are directories on disk. Without explicit exclusion, they appear as navigable folders in the file browser. The fix is a single filter in the directory listing:

.filter(e => e.type === 'dir'
  && !e.name.startsWith('.')
  && !e.name.endsWith('.app')
  && !e.name.endsWith('.framework')
  && !e.name.endsWith('.bundle')
  && !e.name.endsWith('.plugin'))

5. visibilitychange listener

When a user switches tabs in the Penrith Beacon dashboard and then returns, the widget may be stale — a theme might have been deleted in the settings tab, or the agent might have been reinstalled. Adding a visibilitychange listener ensures the widget re-syncs on every tab return:

document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'visible') validateState();
});
validateState(); // also run on boot

6. uuid/id key consistency

Custom themes in the Markdown Editor can be stored with either a uuid or id field depending on how they were created. The deletion endpoint must check both — if either field matches, the theme is removed. Checking only one field silently no-ops for themes stored under the other key, and the user sees the theme persist after clicking Delete.

# Python (Flask) — check both keys
cfg['custom_themes'] = [
    t for t in cfg.get('custom_themes', [])
    if t.get('uuid') != theme_id and t.get('id') != theme_id
]

Agent Design & Packaging

Purpose and API

The Markdown Editor Agent provides filesystem access to the Markdown Editor widget. It runs on 127.0.0.1:7891, loopback-only. Five endpoints:

Language and packaging

• Language: Python (AI default for macOS agents)
• Packaging: py2app → .app bundle → pkgbuild → .pkg installer
• Architecture: Apple Silicon (ARM64) — targets the developer's own machine; no Rosetta required

Auto-start via launchd

The agent installs a launchd plist to ~/Library/LaunchAgents/ so it starts automatically at login:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.penrithbeacon.markdown-editor-agent</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Applications/Markdown Editor Agent.app/Contents/MacOS/agent</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key>
  <string>~/Library/Logs/markdown-editor-agent.log</string>
  <key>StandardErrorPath</key>
  <string>~/Library/Logs/markdown-editor-agent-error.log</string>
</dict>
</plist>

Installer flow

The build-pkg.sh script handles the full packaging pipeline:

1. python3 setup.py py2app — creates the .app bundle in dist/
2. Copies the launchd plist into the package scripts directory
3. pkgbuild --root dist/ --scripts scripts/ --identifier com.penrithbeacon.markdown-editor-agent wcp-agent-markdown-editor.pkg

The resulting .pkg installs the .app to /Applications/ and loads the launchd agent in a postinstall script. The agent starts immediately — no reboot required.

Beta Release Walkthrough

The actual release sequence for the Markdown Editor v1.1.0-beta, using the wcp-ai-release pipeline:

1. Establish release context. Instruction given to AI:

   Read https://github.com/penrithbeacon/wcp-ai-release/blob/main/AI-SKILL.md and release my WCP widget.

   The AI asked: beta or production? dry-run or live? Answers: beta, live.
2. Route to wcp-ai-release-widget. The AI loaded the widget release skill automatically.
3. Audit checklist. The AI verified every item in the wcp-ai-automation audit checklist: mandatory endpoints present, manifest schema valid, theme adoption implemented, CORS headers correct, specification.md complete, DOCKER.md present.
4. Version bump. docker-compose.yml, specification.md, and about.html updated from 1.0.0 to 1.1.0-beta.
5. Commit and push. 8 changed files committed. Pushed to HarrisonOfTheNorth/wcp-widget-markdown-editor (private) first, then to penrithbeacon/wcp-widget-markdown-editor (public) via GIT_ASKPASS pattern.
6. Docker multi-platform build and push.

   docker buildx build \
     --platform linux/amd64,linux/arm64 \
     --tag penrithbeacon/wcp-widget-markdown-editor:1.1.0-beta \
     --tag penrithbeacon/wcp-widget-markdown-editor:beta \
     --push .

7. GitHub Release. Created on the public penrithbeacon repo: tag v1.1.0-beta, release title "v1.1.0-beta", body summarising changes. The agent .pkg (released separately via wcp-ai-release-agent as v1.0.2) was noted in the release notes.
8. Written summary. The AI produced a full summary of every action taken — files changed, tags pushed, release URL. Signed off by the developer before the session closed.

Key Lessons

Distilled from the Markdown Editor build — applicable to any WCP widget + agent pair:

• Design the agent API before building the widget. The widget depends on the agent, not the other way around. If you build the widget first, you will discover the agent API shape only when you wire up the first real call — and you will likely have to refactor. Design the endpoint list up front and mock it with a stub server while building the widget.
• The visibilitychange listener is non-negotiable for stateful widgets. Any widget that caches state (theme list, file path, agent status) will go stale when the user switches tabs and returns. Adding a visibilitychange listener to re-sync on visibility restored costs one minute to implement and prevents a whole class of bug reports.
• Exclude macOS .app bundles from file browser filters. They are directories on disk. Users who try to navigate into /Applications/SomeApp.app will get a confusing listing of Contents/, MacOS/, and Resources/. Always filter them out.
• Test the full WCP endpoint suite with curl before releasing. The release pipeline will run the audit checklist, but it is cheaper to fix a missing endpoint before you get there. A two-minute manual curl pass against /wcp, /widget/wcp, /widget/health, and /widget/theme catches most issues.
• Use the beta floating tag on Docker Hub for pre-production releases. Users who docker pull penrithbeacon/wcp-widget-markdown-editor:beta always get the latest beta. The versioned tag (1.1.0-beta) is pinned for reproducibility. Both are pushed in the same build.
• Agree on uuid/id key naming before writing the first line of config code. The Markdown Editor had a silent delete bug because the JS sent t.id but the server expected t.uuid. Themes appeared to delete (the server returned 200) but persisted on disk. The fix was a two-line patch, but the root cause was avoidable: pick one key name and use it everywhere from the start.

All Skills — Quick Reference

Pre-Build Checklist

Run through this before starting a build to avoid the most common setup issues.