@web42/cli 0.1.6 → 0.1.8

package/skills/web42-publish-prep/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: web42-publish-prep
-description: "This skill should be used when the user asks to 'prepare my agent for Web42', 'publish to Web42', 'set up web42 CLI', 'create a manifest', 'write an agent README', 'clean up files before pushing', 'init web42', or needs help packaging an agent project for the Web42 marketplace. Guides the full lifecycle from init through push-ready state."
+description: "This skill should be used when the user asks to 'prepare my agent for Web42', 'publish to Web42', 'set up web42 CLI', 'create a manifest', 'write an agent README', 'set up marketplace pricing', 'add screenshots', 'clean up files before pushing', 'init web42', or needs help packaging an agent project for the Web42 marketplace. Guides the full lifecycle from init through push-ready state, including marketplace configuration, visual assets, and sync."
 internal: true
 metadata:
   clawdbot:
@@ -12,7 +12,7 @@ metadata:
 
 # Web42 Publish Prep
 
-Prepare an agent project for publishing to the Web42 marketplace. This skill covers the full lifecycle: initializing the project, populating the manifest, writing a compelling README, and auditing workspace files so only the right content ships to users.
+Prepare an agent project for publishing to the Web42 marketplace. This skill covers the full lifecycle: initializing the project, populating the manifest, configuring marketplace settings (pricing, license, tags), preparing visual assets (avatar, screenshots, demo media), writing a compelling README, auditing workspace files, and validating everything before push.
 
 ## When to Activate
 
@@ -20,7 +20,7 @@ Activate when the user wants to get their agent ready for the Web42 marketplace
 
 ## Prerequisites
 
-- The Web42 CLI must be installed (`npx web42-cli` or globally via `npm i -g web42-cli`).
+- The Web42 CLI must be installed (`brew install web42` or via the install script).
 - The user must be authenticated (`web42 auth login`). Verify with `web42 auth whoami`.
 - The workspace must contain a supported platform config (currently OpenClaw — `openclaw.json`).
 
@@ -32,10 +32,13 @@ If any prerequisite is missing, guide the user through resolving it before proce
 
 Check whether `manifest.json` already exists in the workspace root.
 
-- **If missing:** Run `web42 init` interactively. The CLI prompts for platform, description, version, and detects skills from `skills/*/SKILL.md`.
+- **If missing:** Run `web42 init` interactively. The CLI prompts for platform, description, version, and detects skills from `skills/*/SKILL.md`. It also scaffolds the `.web42/` metadata folder with `marketplace.json` and `resources.json`.
 - **If present:** Read and validate the existing manifest against the field reference in `references/manifest-fields.md`. Report any missing or invalid fields.
 
-After init, verify that the scaffolded platform files exist (`AGENTS.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `USER.md`). If the user already customized these, do not overwrite — just confirm they are present.
+After init, verify that these exist:
+
+1. **Platform files:** `AGENTS.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `USER.md` — if the user already customized these, do not overwrite.
+2. **`.web42/` folder:** `marketplace.json`, `resources.json`, `resources/` directory. See `references/web42-folder.md` for the complete structure.
 
 ### Phase 2 — Enrich the Manifest
 
@@ -46,16 +49,55 @@ Key actions:
 1. **`name`** — Confirm it is lowercase-hyphenated and reflects the agent's purpose. Suggest alternatives if generic.
 2. **`description`** — Must be 1–500 characters. Draft a concise, benefit-oriented description that tells a potential buyer what the agent *does for them*.
 3. **`version`** — Ensure semver format (`MAJOR.MINOR.PATCH`).
-4. **`tags`** — Suggest 3–6 relevant tags for discoverability.
-5. **`skills`** — Auto-detected from `skills/*/SKILL.md`. If none found, ask if skills should be documented.
-6. **`configVariables`** — For each detected secret/config, ensure `label` and `description` are clear enough for a buyer.
-7. **`modelPreferences`** — Set `primary` to the intended model. Optionally set a `fallback`.
-8. **`coverImage`** — Ask if the user has a cover image (path relative to workspace).
-9. **`demoVideoUrl`** — Ask if there is a demo video URL to include.
+4. **`skills`** — Auto-detected from `skills/*/SKILL.md`. If none found, ask if skills should be documented.
+5. **`configVariables`** — For each detected secret/config, ensure `label` and `description` are clear enough for a buyer.
+6. **`modelPreferences`** — Set `primary` to the intended model. Optionally set a `fallback`.
 
 Write the updated `manifest.json` only after user confirmation.
 
-### Phase 3 — Write the README
+### Phase 3 — Configure Marketplace Settings
+
+Read `.web42/marketplace.json` and walk through each field. Consult `references/marketplace-config.md` for the full reference.
+
+Key actions:
+
+1. **`price_cents`** — Ask the user about their pricing strategy. Free (`0`) or paid? For paid agents, suggest a price based on the agent's capabilities and target audience. Explain that pricing can be changed later.
+2. **`currency`** — Currently only `"usd"`. Confirm and leave as default.
+3. **`license`** — Help choose. For free agents: suggest `"MIT"` or `"Apache-2.0"`. For paid agents: suggest `"Proprietary"`. Explain the implications briefly.
+4. **`tags`** — Suggest 3–6 searchable tags. Mix category terms ("finance", "devops") with capability terms ("slack-integration", "pdf-generation"). Think about what a buyer would search for.
+
+Write `.web42/marketplace.json` only after user confirmation.
+
+**Important:** Visibility (`public`/`private`/`unlisted`) is managed exclusively through the Web42 dashboard, not through local files. Remind the user that the agent starts private and they should toggle visibility on the dashboard when ready to launch.
+
+### Phase 4 — Prepare Visual Assets
+
+Visual assets are what make a marketplace listing stand out. Walk through each:
+
+#### Avatar
+
+Check if `.web42/avatar.{png,jpg,webp,svg}` exists.
+
+- If missing, ask the user if they want to provide or generate one.
+- **Recommended:** 400x400 or larger, square, PNG or WebP.
+- The avatar appears on the marketplace listing, search results, and the agent's profile.
+- If the user wants to generate one, help create a prompt that captures the agent's personality and purpose.
+
+#### Resources (Screenshots, Videos, Documents)
+
+Check `.web42/resources.json` and `.web42/resources/`. Consult `references/resources-guide.md`.
+
+- **Screenshots** — The single most impactful asset. Ask the user to capture 2–4 screenshots showing the agent in action. Recommend 1200x800 or 1600x900 (landscape).
+- **Demo video** — A 1–3 minute recording showing the agent's core workflow. Dramatically improves conversion. Can be a screen recording with voiceover.
+- **Documents** — Optional setup guides or architecture overviews as PDF.
+
+For each resource:
+
+1. Help the user save files to `.web42/resources/`.
+2. Create or update `.web42/resources.json` with metadata (`file`, `title`, `description`, `type`, `sort_order`).
+3. Put the strongest visual first (`sort_order: 0`).
+
+### Phase 5 — Write the README
 
 The README is the storefront — the agent's pitch deck. Read `assets/readme-template.md` for inspiration, then write a README that lets the agent's personality shine.
 
@@ -63,14 +105,14 @@ Principles:
 
 - **Lead with outcomes, not internals.** Paint the picture of life *with* this agent.
 - **Show personality.** Write in the agent's own voice — confident, creative, even playful.
-- **Use rich media.** GIFs, demo videos, screenshots, embedded links. The marketplace renders full Markdown.
+- **Use rich media.** Reference screenshots from `.web42/resources/`, embed demo videos, include links. The marketplace renders full Markdown.
 - **Give concrete scenarios.** "Ask me to..." or "Imagine you need to..." — make it visceral.
 - **Include practical info** (install command, required config) but don't let it dominate.
 - **Don't reveal the recipe.** Focus on outcomes, not system prompts or internal file structures.
 
 Write to `README.md` at workspace root. If one already exists, show a diff and ask before overwriting.
 
-### Phase 4 — Audit Workspace Files
+### Phase 6 — Audit Workspace Files
 
 Before packing, scan the workspace for files that should not ship to buyers. Consult `references/file-hygiene.md` for the full checklist.
 
@@ -88,15 +130,28 @@ For each flagged item:
 2. Ask the user whether to remove, reset to scaffold default, or keep it.
 3. If unsure, recommend `web42 pack --dry-run` to preview the bundle.
 
-### Phase 5 — Validate and Preview
+### Phase 7 — Validate, Pack, and Sync
 
-Run `web42 pack --dry-run` to show exactly what files will be included. Review together:
+Run `web42 pack --dry-run` to show exactly what files will be included in `.web42/dist/`. Review together:
 
 - Confirm file count and total size are reasonable.
 - Verify no secrets leaked (the CLI strips known patterns, but manual review catches edge cases).
-- Ensure `README.md` is present (push reads it from workspace root).
+- Ensure `README.md` is present.
+- Ensure `.web42/marketplace.json` has pricing, license, and tags set.
+- Ensure at least one screenshot or resource exists in `.web42/resources/`.
+
+When clean, the user can publish:
+
+1. **`web42 push`** — Packs (if needed), pushes the full snapshot (manifest, README, marketplace config, files, avatar, resources) to the remote.
+2. **`web42 sync`** — Check sync status at any time to see if local and remote are aligned.
+3. **Dashboard** — Remind the user to visit `web42.ai` to set visibility to `public` or `unlisted` when ready.
+
+After the first push, subsequent changes follow the sync workflow:
 
-When clean, inform the user they can publish with `web42 push`. The agent is created **private** by default — remind them to toggle visibility on the marketplace when ready.
+- Edit locally → `web42 push` to sync up
+- Edit on dashboard → `web42 pull` to sync down
+- `web42 sync` to check status without changing anything
+- `--force` flag on push/pull to override when both sides have changed
 
 ## CLI Quick Reference
 
@@ -104,16 +159,22 @@ When clean, inform the user they can publish with `web42 push`. The agent is cre
 |---------|---------|
 | `web42 auth login` | Authenticate via GitHub OAuth |
 | `web42 auth whoami` | Check current auth status |
-| `web42 init` | Scaffold `manifest.json` + platform files |
+| `web42 init` | Scaffold `manifest.json` + `.web42/` metadata folder |
 | `web42 pack --dry-run` | Preview packaged files without writing |
-| `web42 pack` | Bundle into `.web42/` directory |
-| `web42 push` | Pack (if needed) and upload to marketplace |
-| `web42 pull` | Fetch latest published files back locally |
+| `web42 pack` | Bundle workspace into `.web42/dist/` |
+| `web42 push` | Pack (if needed) and sync everything to the marketplace |
+| `web42 push --force` | Push even if no local changes detected |
+| `web42 pull` | Fetch latest state from the marketplace to local files |
+| `web42 pull --force` | Pull even if no remote changes detected |
+| `web42 sync` | Show sync status (local vs remote hash comparison) |
 
 ## Resources
 
 ### References
-- **`references/manifest-fields.md`** — Complete manifest.json field reference with types, constraints, and guidance.
+- **`references/web42-folder.md`** — Complete `.web42/` folder structure reference.
+- **`references/manifest-fields.md`** — `manifest.json` field reference with types, constraints, and guidance.
+- **`references/marketplace-config.md`** — `.web42/marketplace.json` field reference with pricing and license guidance.
+- **`references/resources-guide.md`** — Resource types, schema, dimensions, and best practices for screenshots/videos/docs.
 - **`references/file-hygiene.md`** — Checklist of files and patterns to audit before packing.
 
 ### Assets

package/skills/web42-publish-prep/_meta.json

@@ -1,10 +1,10 @@
 {
   "name": "web42-publish-prep",
   "tagline": "Prepare your agent for the Web42 marketplace",
-  "description": "Guides agents through the full publish lifecycle: init, manifest enrichment, README writing, file auditing, and validation before pushing to the Web42 marketplace.",
+  "description": "Guides agents through the full publish lifecycle: init, manifest enrichment, marketplace configuration (pricing, license, tags), visual assets (avatar, screenshots, demo media), README writing, file auditing, and two-way sync with the Web42 marketplace.",
   "category": "development",
-  "tags": ["web42", "marketplace", "publishing", "cli", "agent-packaging"],
-  "version": "1.0.0",
+  "tags": ["web42", "marketplace", "publishing", "cli", "agent-packaging", "sync"],
+  "version": "2.0.0",
   "license": "MIT",
   "pricing": "free",
   "support_url": "https://github.com/web42-ai/web42-marketplace/issues",

package/skills/web42-publish-prep/assets/readme-template.md

@@ -3,13 +3,13 @@
 <!-- 
   This is a starting point, not a form. Rewrite it, restructure it, make it yours.
   The marketplace renders full Markdown — use it. GIFs, videos, screenshots, emoji, whatever tells your story.
+  
+  Screenshots and demo media are managed in .web42/resources/ and appear automatically on the listing.
+  The README is for the narrative — let the resources handle the visuals.
 -->
 
 {A bold opening line. What changes for the user when they have you? Don't describe yourself — describe the outcome.}
 
-<!-- Optional: embed a GIF or demo video here -->
-<!-- ![Demo](https://your-demo-url.gif) -->
-
 ---
 
 ## What I Do
@@ -26,7 +26,7 @@
 
 <!-- Replace these with real scenarios that match what you actually do. -->
 
-## Quickstart
+## Install
 
 ```bash
 web42 openclaw install @{author}/{name}
@@ -40,7 +40,7 @@ web42 openclaw install @{author}/{name}
 
 | Variable | What It Is | Where to Get It |
 |----------|-----------|-----------------|
-| `EXAMPLE_API_KEY` | Access token for Example API | [Example Dashboard → Settings → API](https://example.com/settings) |
+| `EXAMPLE_API_KEY` | Access token for Example API | [Example Dashboard > Settings > API](https://example.com/settings) |
 
 <!-- Remove this section entirely if the agent needs no configuration. -->
 
@@ -54,4 +54,8 @@ web42 openclaw install @{author}/{name}
   - "Credits" (shoutouts, inspirations)
   
   Or make up your own sections. There are no rules here.
+  
+  Tip: Your screenshots and demo video in .web42/resources/ will appear 
+  on the marketplace listing alongside this README. Focus the README on 
+  the story and let the media speak for the visual side.
 -->

package/skills/web42-publish-prep/references/file-hygiene.md

@@ -4,7 +4,7 @@ Before packing, audit the workspace for files that should not ship to buyers. Th
 
 ## Automatically Excluded by the CLI
 
-These patterns are hardcoded in the pack command and will never appear in the `.web42/` artifact:
+These patterns are hardcoded in the pack command and will never appear in the `.web42/dist/` artifact:
 
 | Pattern | Reason |
 |---------|--------|
@@ -18,11 +18,26 @@ These patterns are hardcoded in the pack command and will never appear in the `.
 | `*.log` | Log files |
 | `openclaw.json` | Platform config (contains agent bindings, channel secrets) |
 | `.openclaw/credentials/**` | Platform credentials |
-| `.web42/**` | Previous pack artifacts |
+| `.web42/**` | Metadata folder (marketplace config, sync state, pack output) |
 | `.web42ignore` | Pack ignore config (meta, not content) |
 | `manifest.json` | Shipped separately as structured data |
 | `USER.md` | Always rewritten with a blank template on install |
 
+## `.web42/` Metadata Files (Not Packed)
+
+The `.web42/` folder contains metadata and assets that are synced separately — they are NOT included in the packed agent files:
+
+| File | Purpose | Editable? |
+|------|---------|-----------|
+| `marketplace.json` | Pricing, license, tags | Yes |
+| `resources.json` | Resource file metadata | Yes |
+| `avatar.*` | Agent profile image | Yes |
+| `resources/` | Screenshots, videos, documents | Yes |
+| `sync.json` | Sync state tracking | No — auto-managed |
+| `dist/` | Pack output | No — auto-generated |
+
+**`sync.json`** should never be edited manually. Doing so will break change detection between local and remote. It is safe to delete if you want to force a full re-sync.
+
 ## Files to Flag for Manual Review
 
 These are NOT auto-excluded but often contain content that should not ship:
@@ -53,11 +68,11 @@ These are NOT auto-excluded but often contain content that should not ship:
 
 - The pack command skips files larger than 1 MB.
 - Binary files (images, compiled executables) are skipped automatically (UTF-8 decode failure).
-- If the agent needs images (e.g., for the README cover), use `coverImage` in the manifest or host them externally.
+- If the agent needs images (e.g., for the README cover), host them externally or manage them as resources in `.web42/resources/`.
 
 ## Using `.web42ignore`
 
-Create a `.web42ignore` file in the workspace root to exclude additional patterns. Syntax follows `.gitignore`:
+`web42 init` scaffolds a default `.web42ignore` with sensible patterns (IDE folders, env files, test dirs, drafts). Edit it to match your workspace. Syntax: glob patterns, one per line — lines starting with `#` are comments.
 
 ```
 # Exclude test fixtures
@@ -71,7 +86,7 @@ drafts/**
 scripts/local-*.sh
 ```
 
-The `.web42ignore` file itself is automatically excluded from the artifact.
+The `.web42ignore` file itself is automatically excluded from the packed artifact.
 
 ## Verification
 
@@ -81,8 +96,14 @@ After auditing, always run:
 web42 pack --dry-run
 ```
 
-This prints every file that would be included. Review the list for:
+This prints:
+
+1. **User ignore patterns** loaded from `.web42ignore` (shown with ✕ prefix)
+2. **Every file** that would be included, with sizes
+3. **File and config variable counts**
+
+Review the output for:
 
-1. **Unexpected files** — anything you don't recognize or didn't intend to ship
-2. **File count** — a typical agent has 5–30 files. Hundreds of files suggests something is wrong.
-3. **Sensitive content** — spot-check a few files for leaked secrets or personal data
+- **Unexpected files** — anything you don't recognize or didn't intend to ship
+- **File count** — a typical agent has 5–30 files. Hundreds of files suggests missing ignore patterns.
+- **Sensitive content** — spot-check a few files for leaked secrets or personal data

package/skills/web42-publish-prep/references/manifest-fields.md

@@ -75,12 +75,14 @@ Searchable labels for marketplace discoverability.
 - **Good:** `["support", "crm", "slack", "weekly-reports"]`
 - **Bad:** `["ai", "agent", "good"]` (too generic)
 - **Guidance:** 3–6 tags. Think about what a buyer would search for. Mix category terms ("support", "finance") with capability terms ("slack-integration", "pdf-generation").
+- **Note:** Tags are also specified in `.web42/marketplace.json`. The marketplace.json tags are the canonical source that gets synced to the remote. If tags exist in both files, the marketplace.json values take precedence during sync. See `references/marketplace-config.md`.
 
 ### `coverImage` (string)
 
 Path to a cover image file, relative to workspace root.
 
-- **Guidance:** Optional but recommended. A good cover image dramatically improves click-through on the marketplace. Use a 1200x630 or 1200x1200 image.
+- **Guidance:** Optional. A good cover image dramatically improves click-through on the marketplace. Use a 1200x630 or 1200x1200 image.
+- **Note:** For the marketplace listing, the primary visual asset is now the agent avatar at `.web42/avatar.*` and resources in `.web42/resources/`. The `coverImage` manifest field is still supported for backward compatibility but resources are the preferred approach. See `references/resources-guide.md`.
 
 ### `demoVideoUrl` (string)
 
@@ -88,6 +90,7 @@ URL to a demo video.
 
 - **Constraints:** Must be a valid URL.
 - **Guidance:** A 1–3 minute video showing the agent in action converts far better than text alone. Host on YouTube, Loom, or similar.
+- **Note:** Demo videos can also be managed as resources in `.web42/resources/` with type `"video"`. Resources are uploaded directly to the marketplace. Use `demoVideoUrl` for externally hosted videos (YouTube, Loom) or `.web42/resources/` for self-hosted files. See `references/resources-guide.md`.
 
 ### `configVariables` (array)
 

package/skills/web42-publish-prep/references/marketplace-config.md

@@ -0,0 +1,99 @@
+# Marketplace Configuration Reference
+
+The file `.web42/marketplace.json` controls how your agent appears and is sold on the Web42 marketplace. It is created automatically by `web42 init` with sensible defaults.
+
+## File Location
+
+```
+.web42/marketplace.json
+```
+
+## Fields
+
+### `price_cents` (number)
+
+The price in cents. `0` means free.
+
+- **Default:** `0`
+- **Examples:** `0` (free), `500` ($5.00), `2999` ($29.99), `10000` ($100.00)
+- **Guidance:**
+  - Free agents get more installs but less revenue. Consider free for simple utilities, paid for specialized workflows.
+  - Look at comparable agents on the marketplace for pricing cues.
+  - $5–$15 is a sweet spot for productivity agents. $20–$50 for specialized professional tools.
+  - You can always start free and add pricing later.
+
+### `currency` (string)
+
+ISO 4217 currency code.
+
+- **Default:** `"usd"`
+- **Values:** Currently only `"usd"` is supported.
+
+### `license` (string | null)
+
+The license under which the agent is distributed. `null` means no license specified.
+
+- **Default:** `null`
+- **Supported values:**
+
+| License | Summary | Best For |
+|---------|---------|----------|
+| `"MIT"` | Permissive. Buyers can do almost anything. | Open tools, community agents |
+| `"Apache-2.0"` | Permissive + patent grant. | Enterprise-friendly tools |
+| `"GPL-3.0"` | Copyleft. Derivatives must also be GPL. | Agents you want to stay open |
+| `"BSD-3-Clause"` | Permissive, similar to MIT. | Academic or research agents |
+| `"Proprietary"` | All rights reserved. No redistribution. | Commercial/paid agents |
+| `"Custom"` | Custom terms defined elsewhere. | Unique licensing needs |
+
+- **Guidance:**
+  - For **free agents** intended as community contributions: `MIT` or `Apache-2.0`.
+  - For **paid agents**: `Proprietary` is the standard choice — buyers get usage rights but cannot redistribute.
+  - If unsure, `MIT` for free and `Proprietary` for paid is a safe default.
+
+### `tags` (string array)
+
+Searchable labels for marketplace discoverability. These are the canonical tags shown on the marketplace listing.
+
+- **Default:** `[]`
+- **Constraints:** Each tag should be lowercase, hyphenated for multi-word.
+- **Good:** `["crm", "slack-integration", "weekly-reports", "productivity"]`
+- **Bad:** `["ai", "agent", "good", "cool"]` (too generic)
+- **Guidance:**
+  - Use 3–6 tags.
+  - Mix **category terms** ("finance", "devops", "support") with **capability terms** ("pdf-generation", "slack-integration", "email-monitoring").
+  - Think about what a buyer would search for to find your agent.
+  - Tags also appear in the manifest — the marketplace.json tags are the canonical source that gets synced to the remote.
+
+## Visibility (Dashboard Only)
+
+Agent visibility is **not** controlled through local files. It is managed exclusively through the Web42 dashboard at `web42.ai`.
+
+The visibility lifecycle:
+
+1. **`private`** (default) — Only you can see it. Use this while developing and preparing.
+2. **`unlisted`** — Accessible via direct link but not in search/browse. Good for beta testers or early feedback.
+3. **`public`** — Visible to everyone on the marketplace. Set this when you're ready to launch.
+
+Remind the user to visit the dashboard to toggle visibility when the agent is ready.
+
+## Example File
+
+```json
+{
+  "price_cents": 999,
+  "currency": "usd",
+  "license": "Proprietary",
+  "tags": [
+    "crm",
+    "slack-integration",
+    "weekly-reports",
+    "productivity"
+  ]
+}
+```
+
+## Sync Behavior
+
+When you run `web42 push`, the contents of `.web42/marketplace.json` are included in the sync snapshot and written to the remote database. When you run `web42 pull`, remote marketplace settings (except visibility) are written back to this file.
+
+Changes made on the dashboard (e.g., editing tags or price via the web UI) will be reflected locally on the next `web42 pull`.

package/skills/web42-publish-prep/references/resources-guide.md

@@ -0,0 +1,136 @@
+# Resources Guide
+
+Resources are the visual media and documents that accompany your agent's marketplace listing: screenshots, demo videos, architecture diagrams, PDF guides, etc. They make listings dramatically more compelling.
+
+## File Locations
+
+```
+.web42/resources.json        # Metadata describing each resource
+.web42/resources/             # The actual resource files
+  screenshot-dashboard.png
+  demo-recording.mp4
+  setup-guide.pdf
+```
+
+## `resources.json` Schema
+
+The file is a JSON array of `ResourceMeta` objects:
+
+```json
+[
+  {
+    "file": "screenshot-dashboard.png",
+    "title": "Dashboard Overview",
+    "description": "The main dashboard showing weekly report generation",
+    "type": "image",
+    "sort_order": 0
+  },
+  {
+    "file": "demo-recording.mp4",
+    "title": "3-Minute Demo",
+    "description": "Watch the agent draft a report from CRM data in real time",
+    "type": "video",
+    "sort_order": 1
+  }
+]
+```
+
+### Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `file` | string | Yes | Filename in `.web42/resources/` |
+| `title` | string | Yes | Display title on the marketplace listing |
+| `description` | string | No | Optional caption or context |
+| `type` | `"image"` \| `"video"` \| `"document"` | Yes | Determines how the marketplace renders it |
+| `sort_order` | number | Yes | Display order (0 = first) |
+
+## Resource Types
+
+### Images
+
+Screenshots, diagrams, architecture overviews, result samples.
+
+- **Recommended:** 1200x800 or 1600x900 (16:9 landscape)
+- **Formats:** PNG, JPEG, WebP
+- **Max size:** 5 MB per file
+- **Tips:**
+  - Lead with your best screenshot — it appears first in the gallery.
+  - Show the agent *in action*, not just a static interface.
+  - Annotate screenshots with callouts if key features are not obvious.
+  - Dark-mode and light-mode variants both work well.
+
+### Videos
+
+Demo recordings, walkthroughs, setup tutorials.
+
+- **Recommended:** 1–3 minutes for demos, under 60 seconds for teasers
+- **Formats:** MP4, WebM
+- **Max size:** 50 MB per file (for local storage; consider hosting large videos externally)
+- **Tips:**
+  - Start with the outcome, not the setup. Show the result in the first 10 seconds.
+  - Screen recordings with voiceover convert better than silent ones.
+  - For large video files, consider hosting on YouTube/Loom and linking via `demoVideoUrl` in the manifest instead.
+
+### Documents
+
+PDF guides, setup instructions, architecture docs.
+
+- **Formats:** PDF
+- **Max size:** 10 MB per file
+- **Tips:**
+  - Use for detailed setup guides that are too long for the README.
+  - A 1-page "quick start" PDF is a nice touch for complex agents.
+
+## How Resources Appear on the Marketplace
+
+Resources are displayed on the agent's detail page:
+
+- **Images** show as a scrollable gallery below the agent header.
+- **Videos** embed with a play button.
+- **Documents** appear as downloadable links.
+
+The `sort_order` controls the display sequence across all types.
+
+## Sync Behavior
+
+When you run `web42 push`, the CLI:
+
+1. Reads `.web42/resources.json` for metadata.
+2. Uploads each file from `.web42/resources/` to the server.
+3. Creates the corresponding `agent_resources` rows in the database.
+
+When you run `web42 pull`, the CLI writes `.web42/resources.json` with metadata from the remote. Resource files themselves are not downloaded back (they are referenced by URL in the snapshot).
+
+## Example Workflow
+
+1. Take screenshots of your agent in action.
+2. Save them to `.web42/resources/`.
+3. Create or update `.web42/resources.json` with metadata for each file.
+4. Run `web42 push` — the resources upload alongside everything else.
+
+```json
+[
+  {
+    "file": "slack-report.png",
+    "title": "Weekly Report in Slack",
+    "description": "Automated report posted to #team-updates every Monday",
+    "type": "image",
+    "sort_order": 0
+  },
+  {
+    "file": "crm-dashboard.png",
+    "title": "CRM Data View",
+    "description": "The agent reads from your CRM and extracts key metrics",
+    "type": "image",
+    "sort_order": 1
+  },
+  {
+    "file": "setup-guide.pdf",
+    "title": "Setup Guide",
+    "description": "Step-by-step guide for connecting your CRM and Slack",
+    "type": "document",
+    "sort_order": 2
+  }
+]
+```