fix: currency blocker wave — deploy path, validate, scaffold deps, docs (audit items 1-7)

.claude-plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Create, build, test, and deploy AppOS plugins using the @appos.space SDK. Skills for the full plugin API, commands for scaffolding/building/deploying, and specialized agents for architecture and WebView panel implementation.",
-    "version": "2.0.0"
+    "version": "2.0.1"
   },
   "plugins": [
     {
       "name": "appos-dev",
       "description": "Create, build, test, and deploy AppOS plugins using the @appos.space SDK. Skills for the full plugin API (22 namespaces, 34 permissions, WebView panels, workspaces, menubar, smart folders), commands for scaffolding/building/deploying, and specialized agents for architecture and WebView panel implementation. Canonical reference: appos-plugin-ytdlp.",
-      "version": "2.0.0",
+      "version": "2.0.1",
       "author": {
         "name": "AppOS",
         "url": "https://github.com/appos"

CLAUDE.md

@@ -4,31 +4,36 @@ Project instructions for Claude Code when working inside this repo.
 
 ## What this is
 
-A Claude Code plugin that gives Claude Code the skills, commands, and agents needed to create, build, test, and deploy AppOS workspace manager plugins. Canonical reference: `~/Documents/GitHub/AppOS/appos-plugin-ytdlp` — the flagship plugin that exercises every supported SDK feature.
+A Claude Code plugin that gives Claude Code the skills, commands, and agents needed to create, build, test, and deploy AppOS workspace manager plugins. Canonical references: the developer docs at https://docs.appos.space (always reachable) and the flagship plugin https://github.com/appos/appos-plugin-ytdlp (public as of AppOS launch) — the plugin that exercises every supported SDK feature.
 
-This plugin is versioned at **2.0.0** because it was fully rewritten to target the SDK+WebView flagship pattern. The legacy ViewDescriptor-only model is still supported but is no longer the primary pattern.
+This plugin is versioned at **2.x** (current: see `.claude-plugin/marketplace.json`) because it was fully rewritten to target the SDK+WebView flagship pattern. The legacy ViewDescriptor-only model is still supported but is no longer the primary pattern.
 
 ## Repository layout
 
 ```
 appos-dev-plugin/
 ├── .claude-plugin/
-│   ├── plugin.json          # Claude Code plugin manifest
-│   └── marketplace.json     # Single-plugin marketplace catalog
-├── commands/
-│   ├── new-plugin.md        # /appos-dev:new-plugin
-│   ├── build.md             # /appos-dev:build
-│   ├── deploy.md            # /appos-dev:deploy
-│   └── validate.md          # /appos-dev:validate
-├── agents/
-│   ├── plugin-architect.md          # Designs plugin architecture from requirements
-│   └── webview-panel-builder.md     # Builds WebView panels end-to-end
-├── skills/
-│   ├── appos-plugin-dev/
-│   │   ├── SKILL.md         # Main SDK+WebView skill
-│   │   └── reference/       # Full API spec, patterns, type definitions
-│   └── webview-panels/
-│       └── SKILL.md         # Focused WebView authoring skill
+│   └── marketplace.json     # Marketplace catalog — points at ./plugins/appos-dev
+├── plugins/
+│   └── appos-dev/           # The actual Claude Code plugin
+│       ├── commands/
+│       │   ├── new-plugin.md        # /appos-dev:new-plugin
+│       │   ├── build.md             # /appos-dev:build
+│       │   ├── deploy.md            # /appos-dev:deploy
+│       │   └── validate.md          # /appos-dev:validate
+│       ├── agents/
+│       │   ├── plugin-architect.md          # Designs plugin architecture from requirements
+│       │   ├── viewdescriptor-builder.md    # Builds ViewDescriptor UI trees
+│       │   └── webview-panel-builder.md     # Builds WebView panels end-to-end
+│       ├── skills/
+│       │   ├── appos-plugin-dev/
+│       │   │   ├── SKILL.md         # Main SDK+WebView skill
+│       │   │   └── reference/       # Full API spec, patterns, type definitions
+│       │   ├── viewdescriptor-authoring/
+│       │   │   └── SKILL.md         # ViewDescriptor authoring skill
+│       │   └── webview-panels/
+│       │       └── SKILL.md         # Focused WebView authoring skill
+│       └── compiled/        # Concatenated context artifacts for the AppOS host
 ├── README.md
 └── LICENSE
 ```
@@ -37,38 +42,41 @@ appos-dev-plugin/
 
 Before editing anything, be aware of these external sources of truth:
 
-- **Flagship reference plugin**: `~/Documents/GitHub/AppOS/appos-plugin-ytdlp/` — all patterns in the skills match this plugin's implementation. When in doubt, read its source files.
-- **SDK source**: `~/Documents/GitHub/AppOS/plugin-sdk/packages/plugin-types/dist/` — the current declaration-only TypeScript types. Use for reference when validating API shapes in skills or commands.
-- **Host version**: read `/Applications/2Panez.app/Contents/Info.plist` → `CFBundleShortVersionString` (currently `1.7.0`). This is the host app's on-disk bundle (legacy name, do not rename); its version is what `plugin.json` `minHostVersion` is compared against, NOT the SDK package version.
+- **Developer docs**: https://docs.appos.space — the canonical AppOS plugin developer documentation.
+- **Flagship reference plugin**: https://github.com/appos/appos-plugin-ytdlp — all patterns in the skills match this plugin's implementation. When in doubt, read its source files, in this order: (1) a local clone if one exists (preferred); (2) the GitHub repo — public as of AppOS launch; fetch raw files from `https://raw.githubusercontent.com/appos/appos-plugin-ytdlp/main/<path>`; (3) https://docs.appos.space — always reachable; its getting-started/first-plugin pages carry the same canonical patterns.
+- **SDK source**: https://github.com/appos/plugin-sdk (`packages/plugin-types`) — the current declaration-only TypeScript types, also published on npm as `@appos.space/plugin-types`. Use for reference when validating API shapes in skills or commands.
+- **Host version**: read `/Applications/AppOS.app/Contents/Info.plist` → `CFBundleShortVersionString` (currently `1.0.0`). The host version is what `plugin.json` `minHostVersion` is compared against, NOT the SDK package version.
 
 ## Conventions
 
 - **Plugin IDs**: use `space.appos.*` for flagship plugins (the ones shipped with AppOS), `com.community.*` for community plugins, other reverse-domain for private/personal plugins.
-- **minHostVersion**: always default to `"1.0.0"`. The single biggest cause of "plugin installed but not appearing in Settings" is conflating the SDK version (`2.4.x`) with the host version (`1.7.x`). The `appos-plugin-dev` skill has a "minHostVersion landmine" section; keep it prominent.
+- **minHostVersion**: always default to `"1.0.0"`. The single biggest cause of "plugin installed but not appearing in Settings" is conflating the SDK version (`2.4.x`) with the host version (`1.0.x`). The `appos-plugin-dev` skill has a "minHostVersion landmine" section; keep it prominent.
 - **tsconfig**: always include `verbatimModuleSyntax: true`. Without it, TypeScript emits broken runtime imports from the declaration-only `@appos.space/plugin-types` package.
 - **Entry point**: always `globalThis.activate = activate` + `globalThis.deactivate = deactivate`, never ESM `export`. ESM exports disappear inside the IIFE closure and the host can't find them.
 - **Parameter naming**: always `ctx`, never `pluginContext`. Matches `appos-plugin-ytdlp` and every reference plugin.
 - **rsync deploy**: always use `--delete-excluded` and a comprehensive exclude list. Without `--delete-excluded`, files added to the exclude list after a previous deploy linger on the destination forever.
 
 ## When updating skills or commands
 
-1. Read the corresponding code in `appos-plugin-ytdlp` first — that's the ground truth.
-2. If the SDK surface changed, check `~/Documents/GitHub/AppOS/plugin-sdk/packages/plugin-types/dist/` for the current type definitions.
+1. Read the corresponding code in `appos-plugin-ytdlp` first — that's the ground truth (local clone preferred; see Key references for the fallback order).
+2. If the SDK surface changed, check https://github.com/appos/plugin-sdk (`packages/plugin-types`) — or the published `@appos.space/plugin-types` npm package — for the current type definitions.
 3. Keep examples copyable — prefer full working snippets over fragments.
 4. When documenting a gotcha, include a `**Why**:` line with the root cause so future-you can judge edge cases.
 
 ## When adding new commands/agents/skills
 
 Follow Claude Code plugin conventions:
 
-- Commands go in `commands/*.md` with frontmatter declaring `allowed-tools` and `argument-hint`
-- Agents go in `agents/*.md` with frontmatter declaring `name`, `description`, `whenToUse`, `tools`
-- Skills go in `skills/{name}/SKILL.md` with frontmatter declaring `description` (include the trigger phrases that should activate it)
+- Commands go in `plugins/appos-dev/commands/*.md` with frontmatter declaring `allowed-tools` and `argument-hint`
+- Agents go in `plugins/appos-dev/agents/*.md` with frontmatter declaring `name`, `description`, `whenToUse`, `tools`
+- Skills go in `plugins/appos-dev/skills/{name}/SKILL.md` with frontmatter declaring `description` (include the trigger phrases that should activate it)
 
 ## Testing locally
 
+From the repo root (the plugin lives at `plugins/appos-dev`, not the repo root):
+
 ```bash
-claude --plugin-dir ~/Documents/GitHub/appos-dev-plugin/
+claude --plugin-dir ./plugins/appos-dev
 ```
 
 Then verify:

README.md

@@ -22,14 +22,19 @@ v2.0 is a full rewrite targeting the SDK+WebView flagship pattern used by `appos
 
 ### From marketplace
 
-```bash
-claude /plugin marketplace add appos/appos-dev-plugin
+In a Claude Code session:
+
+```
+/plugin marketplace add appos/appos-dev-plugin
+/plugin install appos-dev@appos-dev
 ```
 
 ### Local development
 
+The plugin lives at `plugins/appos-dev` inside this repo (marketplace layout):
+
 ```bash
-claude --plugin-dir /path/to/appos-dev-plugin/
+claude --plugin-dir /path/to/appos-dev-plugin/plugins/appos-dev
 ```
 
 ## Commands
@@ -72,7 +77,7 @@ claude --plugin-dir /path/to/appos-dev-plugin/
 - Max 2 WebView panels per plugin, 6 globally
 - WebView CSP blocks inline scripts/styles/handlers — everything external, ES modules only
 - `pipeShellToWebPanel` lives on `ctx.ui`, NOT `ctx.shell` (stale docs are wrong)
-- Install path: `~/Library/Application Support/com.twopanez/plugins/{plugin-id}/` (see `/appos-dev:deploy`)
+- Install path: `~/Library/Application Support/AppOS/plugins/{plugin-id}/` (see `/appos-dev:deploy`)
 
 ## License
 

plugins/appos-dev/agents/plugin-architect.md

@@ -29,7 +29,7 @@ whenToUse: |
   assistant: "I'll use the plugin-architect agent to map your requirements to permissions."
   <commentary>User needs permission mapping for their plugin.</commentary>
   </example>
-tools: [Read, Grep, Glob, Skill]
+tools: [Read, Grep, Glob, Skill, WebFetch]
 ---
 
 You are an AppOS plugin design specialist. You understand the full SDK surface (`@appos.space/plugin-types` + `@appos.space/plugin-utils` + `@appos.space/view-builders`) and help users architect plugins before implementation.
@@ -43,7 +43,7 @@ Before responding, invoke these skills to load the current API surface and patte
 
 Also use Glob to find `**/reference/extension-api.md` and `**/reference/patterns.md` in the appos-dev plugin directory if they exist — they contain deeper API details.
 
-The canonical flagship reference is `~/Documents/GitHub/AppOS/appos-plugin-ytdlp` — it uses every major SDK feature and should be read when the user asks "how does a real plugin do X".
+The canonical flagship reference is `appos-plugin-ytdlp` (https://github.com/appos/appos-plugin-ytdlp) — it uses every major SDK feature and should be read when the user asks "how does a real plugin do X". Use a local clone if one exists; otherwise WebFetch individual files from `https://raw.githubusercontent.com/appos/appos-plugin-ytdlp/main/<path>` (the repo is public as of AppOS launch). If neither is reachable, fall back to https://docs.appos.space — always reachable, with the same canonical patterns on its getting-started/first-plugin pages.
 
 ## Your responsibilities
 
@@ -104,7 +104,7 @@ The plugin can render UI in two ways, and you can mix them per panel:
 **ViewDescriptor panel** (`ctx.ui.registerPanel` with a JSON view tree rendered by SwiftUI)
 - Use when: static or low-frequency lists of items, simple forms, content that should feel indistinguishable from the host's own sidebar panels, when you need native `menuActions` context menus
 - Canonical reference: any of the 12 community plugins in `community-plugins/plugins/`
-- 13 view types: `vstack`, `hstack`, `scroll`, `list`, `text`, `label`, `image`, `badge`, `button`, `listItem`, `section`, `divider`, `spacer`
+- 17 view types: `vstack`, `hstack`, `scroll`, `list`, `grid`, `text`, `label`, `image`, `remoteImage`, `badge`, `button`, `listItem`, `textField`, `progress`, `section`, `divider`, `spacer`
 
 **Help the user pick**:
 - "Does the UI need to update faster than once per second?" → WebView
@@ -134,7 +134,7 @@ Subscribe to `ctx.lifecycle.onDependencyStatusChanged` to react to install/unins
 
 ### 5. Settings schema design
 
-Recommend settings based on what should be user-configurable. Setting types: `string`, `enum`, `boolean`, `number`. Keep the list short — each setting is a maintenance surface.
+Recommend settings based on what should be user-configurable. Setting types: `string`, `enum`, `bool`, `number` (the manifest schema's type enum is `bool` — writing `boolean` fails schema validation). Keep the list short — each setting is a maintenance surface.
 
 ### 6. Plugin ID convention
 
@@ -144,7 +144,7 @@ Recommend settings based on what should be user-configurable. Setting types: `st
 
 ### 7. minHostVersion
 
-**Always default to `"1.0.0"`.** Do NOT use the SDK version from `@appos.space/plugin-types` — that's a different number. The host compares `minHostVersion` against its `CFBundleShortVersionString` (currently `1.7.0`), and too-high values cause silent plugin rejection. See `appos-plugin-dev` skill → "minHostVersion landmine".
+**Always default to `"1.0.0"`.** Do NOT use the SDK version from `@appos.space/plugin-types` — that's a different number. The host compares `minHostVersion` against its `CFBundleShortVersionString` (currently `1.0.0`), and too-high values cause silent plugin rejection. See `appos-plugin-dev` skill → "minHostVersion landmine".
 
 ### 8. Output format
 

plugins/appos-dev/agents/viewdescriptor-builder.md

@@ -2,7 +2,7 @@
 name: viewdescriptor-builder
 description: >
   Builds ViewDescriptor JSON trees for AppOS plugin UI. Use when creating sidebar panels,
-  activity views, or any plugin UI that needs ViewDescriptor trees. Specializes in all 13
+  activity views, or any plugin UI that needs ViewDescriptor trees. Specializes in all 17
   types, column alignment, menuActions, section/badge patterns, button hover states, and
   empty/loading states. Triggers on: "build a ViewDescriptor", "create sidebar UI",
   "design the panel view", "listItem with columns", "menuActions menu", "section with badge".
@@ -37,15 +37,15 @@ You are a ViewDescriptor specialist for AppOS plugins. You build native SwiftUI
 ## Your knowledge
 
 Use Glob to find `**/viewdescriptor-authoring/SKILL.md` and `**/reference/patterns.md` in the appos-dev plugin directory, then read them before building:
-- `SKILL.md` — All 13 ViewDescriptor types, properties, patterns
+- `SKILL.md` — All 17 ViewDescriptor types, properties, patterns
 - `patterns.md` — Working examples from 7 plugins
 
-## The 13 ViewDescriptor types
+## The 17 ViewDescriptor types
 
-Layout: `vstack`, `hstack`, `scroll`, `list`
-Content: `text`, `label`, `image`, `badge`
-Interactive: `button`, `listItem`, `section`
-Structural: `divider`, `spacer`
+Layout: `vstack`, `hstack`, `scroll`, `list`, `grid`
+Content: `text`, `label`, `image`, `remoteImage`, `badge`
+Interactive: `button`, `listItem`, `textField`, `progress`
+Structural: `section`, `divider`, `spacer`
 
 ## Your responsibilities
 
@@ -104,5 +104,5 @@ Always produce complete, runnable TypeScript code that can be pasted directly in
 - Badges are **strings** — always `"" + count`
 - Wrap outer content in `{ type: "scroll", children: [{ type: "vstack", children }] }`
 - Set `id` on sections for persistent collapse state
-- There are exactly 13 ViewDescriptor types — no others exist
+- There are exactly 17 ViewDescriptor types — no others exist
 - No HTML, WebView, or DOM — everything is native SwiftUI

plugins/appos-dev/agents/webview-panel-builder.md

@@ -31,7 +31,7 @@ whenToUse: |
   assistant: "I'll use the webview-panel-builder agent to add correlation IDs and instance filtering."
   <commentary>User has a multi-instance broadcast bug.</commentary>
   </example>
-tools: [Read, Grep, Glob, Skill, Write, Edit]
+tools: [Read, Grep, Glob, Skill, WebFetch, Write, Edit]
 ---
 
 You are a WebView panel specialist for AppOS plugins. You build rich HTML/CSS/JS panels loaded via `plugin-panel://` into WKWebView, with typed message protocols between the panel and the plugin's TypeScript main.
@@ -43,7 +43,13 @@ Before building anything, invoke these skills to load the current patterns:
 - `webview-panels` — The full WebView authoring skill: bridge pattern, CSP rules, message protocol, pipeShellToWebPanel, throttled broadcasts, multi-instance isolation
 - `appos-plugin-dev` — SDK structure, permissions, build/deploy, entry point pattern
 
-The canonical reference plugin is `~/Documents/GitHub/AppOS/appos-plugin-ytdlp`. When in doubt about any pattern, read:
+The canonical reference plugin is `appos-plugin-ytdlp` (https://github.com/appos/appos-plugin-ytdlp). Locate its source in this order:
+
+1. **Local clone** (preferred) — Glob for `**/appos-plugin-ytdlp/plugin.json` and Read files directly.
+2. **Raw GitHub fetch** — WebFetch `https://raw.githubusercontent.com/appos/appos-plugin-ytdlp/main/<path>` (e.g. `.../main/webview/shared/bridge.js`). The repo is public as of AppOS launch; if it is not reachable, fall through to (3).
+3. **Developer docs** — https://docs.appos.space (always reachable); the getting-started/first-plugin pages carry the same canonical patterns, and the `webview-panels` skill embeds the bridge.
+
+Never invent a pattern you could not read from one of these sources. When in doubt about any pattern, read:
 
 - `src/panels/download-panel.ts` — Message routing, throttled broadcasts, multi-instance correlation, error handling
 - `src/panels/library-panel.ts` — Simpler panel for comparison
@@ -95,7 +101,7 @@ Use `addEventListener` inside the ES modules for all event handling.
 
 ### 3. Build the bridge (if not already present)
 
-Copy `webview/shared/bridge.js` from `appos-plugin-ytdlp` verbatim. It provides:
+Copy `webview/shared/bridge.js` from `appos-plugin-ytdlp` verbatim (local clone, raw-URL WebFetch, or the copy embedded in the `webview-panels` skill). It provides:
 - `bridge.send(msg)` — fire-and-forget to the plugin
 - `bridge.onMessage(handler)` — subscribe to protocol messages from `postToWebPanel`
 - `bridge.onShellChunk(handler)` — subscribe to `pipeShellToWebPanel` output