SoulShare — Widget Marketplace Spec

Context

The wise-songs-media widget is the first candidate for sharing/selling through a marketplace. The soul widget system already has the right primitives (versioning, registry, preview metadata) but is missing the publication, discovery, licensing, and monetisation layers.

This spec defines what needs to be added to SoulShare to support a widget marketplace, using the media pipeline widget as the concrete design target.

Current state (from code review):

• ss widget install local:<path> works
• registry.json tracks installed widgets with manifest + sha256 + heartbeat
• soul-widget.yaml has version, preview.tags, preview.features, preview.screenshot
• No publish command, no remote install, no pricing fields, no upgrade path
• Roadmap explicitly de-prioritises marketplace through Q2 2026 — this spec is forward design, not an immediate build request

---

What "Marketplace" Means Here

Three distinct use cases, in order of priority:

1. Share within a team / family (near-term, low lift) A team member installs the same widget another team member built. ss widget install github:supernal-family/wise-songs-media

2. Share publicly / give away (medium-term) A widget published to ClaWHub (Supernal's registry) that anyone can install free. ss widget install clawhub:wise-songs-media

3. Sell (longer-term) A widget with a license key or subscription check. The installer pays, gets a token, the widget checks the token at install time or at runtime. ss widget install clawhub:wise-songs-media --tier pro

---

Changes Needed in soul-widget.yaml

Add a marketplace block. All fields optional — a widget without it is private/local only.

id: wise-songs-media
version: 1.2.0
name: "Wise Songs Media Pipeline"
description: >
  Full video production pipeline for educational music channels.
  Generates scene-coherent videos with sequential img2img, karaoke
  word highlighting, and automated Revid integration.

equipment: content-tracker
board: ./board.yaml

# ── Existing preview block (already exists) ──────────────────
preview:
  tags: [media, video, youtube, educational, music, content-pipeline]
  features:
    - Sequential img2img scene generation (visual continuity)
    - Whisper karaoke word highlighting
    - Revid automation via Playwright
    - Channel management with cost guardrails
    - Review-before-publish workflow
  screenshot: ./preview/board-screenshot.png

# ── New marketplace block ─────────────────────────────────────
marketplace:
  visibility: public          # private | team | public
  source: github              # github | clawhub | npm

  # Value metrics — shown to potential buyers
  value:
    replaces:
      - "Revid manual upload workflow (~2 hrs/video)"
      - "Spreadsheet pipeline tracking"
      - "Manual YouTube metadata entry"
    saves_per_video:
      human_hours: 2.5
      manual_steps: 14
    compute_per_video:
      llm_tokens: 1200          # GPT-4o scene planning
      image_calls: 6            # FLUX img2img
      whisper_minutes: 2.5
      estimated_cost_usd: 0.15  # our API costs, not their time

  # Licensing
  license:
    model: subscription         # free | one_time | subscription
    price_usd: 0                # 0 = free tier
    tiers:
      - id: free
        price_usd: 0
        limits:
          videos_per_month: 10
          channels: 2
          backends: [ken_burns]
      - id: pro
        price_usd: 19           # /month
        limits:
          videos_per_month: 100
          channels: unlimited
          backends: [ken_burns, ltx_video, revid]
      - id: studio
        price_usd: 49           # /month
        limits:
          videos_per_month: unlimited
          channels: unlimited
          backends: all
          priority_queue: true

  # Payment integration (LemonSqueezy)
  payment:
    provider: lemonsqueezy
    product_id: ""              # filled at publish time
    webhook_secret: ""          # filled at publish time

  # Publisher info
  publisher:
    name: "Supernal Family"
    url: "https://supernal.family"
    verified: false             # set by ClaWHub on verification

---

Changes Needed in SoulShare CLI

New commands

# Publish a widget to a remote source
ss widget publish [--remote clawhub|github] [--version 1.2.0]
  → validates soul-widget.yaml
  → bundles board.js, manifest, assets
  → pushes to registry with version tag
  → returns: published URL, install command

# Install from remote
ss widget install clawhub:wise-songs-media[@1.2.0] [--tier pro]
  → fetches manifest from registry
  → checks license (if paid, prompts for key or OAuth)
  → runs existing apply flow
  → pins version in local registry.json

# Check for updates
ss widget check-updates
  → for each installed widget, queries remote for latest version
  → reports: "wise-songs-media 1.0.0 → 1.2.0 available"

# Upgrade
ss widget upgrade wise-songs-media [@1.2.0]
  → backs up current install
  → runs install of new version
  → on failure: rollback to backup

# List available (discovery)
ss widget search [query] [--tag media] [--free]
  → queries ClaWHub API
  → returns: id, name, description, installs, price, tags

Changes to registry.json entry

interface RegistryEntry extends WidgetManifest {
  // existing
  owner: string | null;
  lastHeartbeat: string | null;
  companies?: string[];
  sha256: string;
  installedAt: ISO8601;

  // new
  source: "local" | "github" | "clawhub" | "npm";
  sourceRef: string;            // e.g. "clawhub:wise-songs-media@1.2.0"
  licenseKey?: string;          // for paid widgets
  tier?: string;                // "free" | "pro" | "studio"
  pinnedVersion?: string;       // if user pinned, don't auto-upgrade
  lastCheckedUpdate?: ISO8601;
  availableVersion?: string;    // populated by check-updates
}

---

ClaWHub Registry API (new service)

Minimal API needed to support the marketplace:

GET  /api/v1/widgets                       search/list
GET  /api/v1/widgets/:id                   manifest + metadata
GET  /api/v1/widgets/:id/versions          version history
POST /api/v1/widgets                       publish (auth required)
POST /api/v1/widgets/:id/versions          publish new version
GET  /api/v1/widgets/:id/install/:version  download bundle
POST /api/v1/licenses/validate             check license key
POST /api/v1/licenses/activate             activate on device

This is a new service. Does not need to exist before internal sharing works (GitHub source install is enough for team sharing without ClaWHub).

---

Rollout Order

Step 1 — Internal sharing (near-term, low lift)
  [ ] ss widget install github:<owner>/<repo>[@tag]
  [ ] Basic bundle format (zip: soul-widget.yaml + board.js + assets)
  [ ] Version pinning in registry.json
  The wise-songs-media widget can be shared between team members via GitHub.

Step 2 — Value metadata in manifest (near-term, no infra needed)
  [ ] Add marketplace.value block to soul-widget.yaml spec
  [ ] ss widget info — shows value metrics for any installed widget
  [ ] Establish the value measurement convention before monetisation

Step 3 — Upgrade lifecycle (medium-term)
  [ ] ss widget check-updates
  [ ] ss widget upgrade with rollback
  [ ] source + pinnedVersion fields in registry.json

Step 4 — ClaWHub registry + public sharing (longer-term)
  [ ] ss widget publish → ClaWHub
  [ ] ss widget search / install clawhub:*
  [ ] Publisher verification

Step 5 — Monetisation (after ClaWHub exists)
  [ ] License tiers in soul-widget.yaml
  [ ] LemonSqueezy integration for payment
  [ ] License key validation at install + runtime
  [ ] ss widget upgrade respects tier limits

---

The Dogfooding Loop

Supernal Family is the first customer of this marketplace — specifically as a "media creator" profile. The design choices made in the wise-songs-media widget should reflect what a non-technical media creator needs, not what a developer needs.

Every rough edge we hit (channel creation UX, cost visibility, review workflow) is a rough edge a paying customer would hit. Fixing it here fixes it for the product.

The value metrics in marketplace.value are also the sales copy:

• "Saves 2.5 hours per video"
• "Replaces $39/mo Revid manual workflow"
• "Estimated API cost: $0.15/video"

These are real numbers derived from building it ourselves. That's the dogfooding advantage.

---

What This Doesn't Change

• The soul-widget architecture doc remains the source of truth for widget internals
• The media-pipeline widget implementation is unaffected — marketplace is a publication layer
• SoulShare's current Phase 3–7 roadmap is unchanged — this spec is additive design
• No build work starts on ClaWHub until Step 1 (GitHub install) is working and validated