v3 knowledge refresh: teach the published SDK 3.0.0 surface + three drift gates (fn-165)

.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.1"
+    "version": "3.0.0"
   },
   "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.1",
+      "description": "Create, build, test, and deploy AppOS plugins using the @appos.space SDK 3.0.0. Skills for the full plugin API (the complete PluginContext surface — WebView panels, actions, notifications, scheduler, workspaces, menubar, smart folders, and the core-plugin namespaces — plus the canonical permission-scope model and extensions[] manifests), commands for scaffolding/building/deploying, and specialized agents for architecture, ViewDescriptor, and WebView panel implementation. Canonical reference: appos-plugin-ytdlp.",
+      "version": "3.0.0",
       "author": {
         "name": "AppOS",
         "url": "https://github.com/appos"

.github/workflows/verify.yml

@@ -0,0 +1,44 @@
+# verify.yml — fn-165.1 (R2): knowledge-drift gate.
+#
+# This repo had zero CI before fn-165 — a gate nobody runs is not a gate.
+# Runs on every PR + push to main:
+#   1. check-sdk-freshness.sh  — bundled d.ts mirror is byte-equal to the
+#      PUBLISHED @appos.space/plugin-types tarball pinned in .sdk-integrity
+#   2. verify-knowledge.mjs    — teaching surfaces type-check against the
+#      pinned SDK (fence compile + exported-name-set diff + stale-identifier
+#      denylist + count-string consistency)
+#   3. check-compiled-freshness.sh (fn-165.4) — compiled/ artifacts match
+#      their manifest in BOTH directions (source changed without regen /
+#      compiled artifact edited directly)
+#
+# Deterministic diagnostics: `npm ci` against the committed package-lock.json
+# (typescript + @appos.space/* pinned EXACTLY in devDependencies).
+name: verify
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install pinned toolchain (npm ci)
+        run: npm ci
+
+      - name: SDK mirror freshness (integrity pin + byte-equality vs npm tarball)
+        run: scripts/check-sdk-freshness.sh
+
+      - name: Knowledge verification (fence type-check + denylist + counts)
+        run: node scripts/verify-knowledge.mjs
+
+      - name: Compiled-artifact freshness (sources vs compiled/ manifest, both directions)
+        run: scripts/check-compiled-freshness.sh

.sdk-integrity

@@ -0,0 +1,3 @@
+package=@appos.space/plugin-types
+version=3.0.0
+integrity=sha512-Sw6Ro/MNq07cn/idU1d+ccyjjf0vAYrr09Mh/O3vnHXqrgjpg1l5YO7lpCMHqLoxJAxw3pRXD1pcLDJ1GMhT7g==

CLAUDE.md

@@ -2,18 +2,20 @@
 
 Project instructions for Claude Code when working inside this repo.
 
+> Note: per the Claude Code plugin docs, this root `CLAUDE.md` is NOT loaded as plugin context when the `appos-dev` plugin is installed — it exists for contributors editing THIS repo. Knowledge meant for plugin consumers belongs in the skills/agents/commands under `plugins/appos-dev/`.
+
 ## 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 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.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.
+This plugin is versioned at **3.x** (current: see `.claude-plugin/marketplace.json`, the repo's ONLY manifest — both `metadata.version` and `plugins[0].version`), deliberately aligned with the `@appos.space` SDK major it teaches. That alignment is versioning convenience, NOT a `minHostVersion` — the host version stays `1.0.0` (see Conventions). The v2.x line was the SDK+WebView rewrite; the legacy ViewDescriptor-only model is still supported but is no longer the primary pattern.
 
 ## Repository layout
 
 ```
 appos-dev-plugin/
 ├── .claude-plugin/
-│   └── marketplace.json     # Marketplace catalog — points at ./plugins/appos-dev
+│   └── marketplace.json     # Marketplace catalog (the ONLY manifest — no plugin.json exists) — points at ./plugins/appos-dev
 ├── plugins/
 │   └── appos-dev/           # The actual Claude Code plugin
 │       ├── commands/
@@ -28,16 +30,24 @@ appos-dev-plugin/
 │       ├── skills/
 │       │   ├── appos-plugin-dev/
 │       │   │   ├── SKILL.md         # Main SDK+WebView skill
-│       │   │   └── reference/       # Full API spec, patterns, type definitions
+│       │   │   └── reference/       # API reference, patterns, plugin-api/ d.ts mirror (generated)
 │       │   ├── viewdescriptor-authoring/
 │       │   │   └── SKILL.md         # ViewDescriptor authoring skill
 │       │   └── webview-panels/
 │       │       └── SKILL.md         # Focused WebView authoring skill
-│       └── compiled/        # Concatenated context artifacts for the AppOS host
+│       └── compiled/        # GENERATED context artifacts for the AppOS host — do not hand-edit
+├── scripts/                 # verify-knowledge.mjs + check-sdk-freshness.sh + check-compiled-freshness.sh (CI gates)
+├── package.json             # exact-pinned toolchain for the gates (npm ci)
+├── package-lock.json
 ├── README.md
 └── LICENSE
 ```
 
+### Generated content — provenance
+
+- `plugins/appos-dev/skills/appos-plugin-dev/reference/plugin-api/` is a byte-verbatim mirror of the published `@appos.space/plugin-types` tarball's `dist/*.d.ts`, regenerated with `scripts/check-sdk-freshness.sh --update` and verified against the npm registry on CI. Never edit by hand.
+- `plugins/appos-dev/compiled/` is generated by the **AppOS-Desktop** repo's `scripts/compile-factory-context.sh`, which concatenates this repo's skill sources into the context artifacts the host bundles for its in-app AI features. Regenerate via that script (it writes both the Desktop-side copy and this repo's copy); the artifacts are validated by freshness manifests, not by `verify-knowledge.mjs`.
+
 ## Key references
 
 Before editing anything, be aware of these external sources of truth:
@@ -50,7 +60,7 @@ Before editing anything, be aware of these external sources of truth:
 ## 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.0.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 (`3.0.x` — or the older `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.
@@ -62,6 +72,7 @@ Before editing anything, be aware of these external sources of truth:
 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.
+5. Run the CI gates before committing: `npm ci` once, then `npm run check` — the same sequence CI runs: `scripts/check-sdk-freshness.sh` (mirror byte-equality), `node scripts/verify-knowledge.mjs` (type-checks every `ts` fence against the pinned SDK, plus a stale-identifier denylist and count-string consistency; opt-out convention documented in the script header), and `scripts/check-compiled-freshness.sh` (compiled/ artifacts match their manifest, both directions).
 
 ## When adding new commands/agents/skills
 

README.md

@@ -2,14 +2,22 @@
 
 A Claude Code plugin for creating, building, testing, and deploying [AppOS](https://appos.space) workspace manager plugins using the `@appos.space` SDK.
 
-## What's new in v2.0
+## What's new in v3.0
 
-v2.0 is a full rewrite targeting the SDK+WebView flagship pattern used by `appos-plugin-ytdlp`. The legacy ViewDescriptor-only model is still supported but is no longer the primary pattern. Key changes:
+v3.0 re-anchors every teaching surface on the published SDK 3.0.0 (`@appos.space/plugin-types@3.0.0`), the surface the shipped AppOS 1.0.0 host actually exposes. The plugin's own version is deliberately aligned with the SDK major it teaches (it is NOT a `minHostVersion` — that stays `"1.0.0"`). Key changes:
 
-- **SDK-based scaffolding** — `new-plugin` now writes `package.json` with `@appos.space/plugin-types` (declaration-only types), `@appos.space/plugin-utils` (runtime helpers), and `@appos.space/view-builders` (typed view builders), plus a `tsconfig.json` with `verbatimModuleSyntax: true` and a `build.mjs` esbuild-API build script.
-- **WebView panels are first-class** — new `webview-panels` skill covers `registerWebPanel`, the host-injected webview bridge, CSP constraints, typed message protocols, throttled broadcasts, and `pipeShellToWebPanel` for streaming CLI output directly to the UI.
-- **22 namespaces, 34 permissions** — updated to match the current `@appos.space/plugin-types` surface. Adds `menubar`, `workspaces`, `smartFolders`, `cache`, `feedback`, `webview`, and more.
-- **minHostVersion landmine documented** — the single most common "plugin won't appear in Settings" bug now has a prominent warning everywhere it matters.
+- **Full 3.0.0 API surface** — 43 namespaces on `PluginContext` (of which 21 core-plugin namespaces: actions, palette, scheduler, vault, store, resources, tokens, bundles, entities, fields, ledger, views, surfaces, protocols, notifications, input, webhook, llm, recipes, sequences, fileSystem) and the 135-scope canonical permission model with 5 legacy aliases (deprecated).
+- **`extensions[]` manifests** — manifest-declarative contributions to core-plugin extension points, including the required `actions.definition` dual-registration pattern: today the manifest entry is catalog/manifest metadata only (host bug fn-163), and the runtime `ctx.actions.register()` call is what provides discovery and execution — see `plugins/appos-dev/skills/appos-plugin-dev/reference/extension-api.md`. <!-- remove when fn-163 lands -->
+- **Scaffold pins `^3.0.0`** — `new-plugin` scaffolds depend on the 3.x SDK line; 3.0.0 ships no ambient globals, so all types are imported from the packages.
+- **Byte-verbatim type mirror + drift gate** — the bundled d.ts reference is a generated mirror of the published npm tarball, and CI type-checks every fenced code example against it (see "Knowledge verification" below).
+
+## What was new in v2.0
+
+v2.0 was a full rewrite targeting the SDK+WebView flagship pattern used by `appos-plugin-ytdlp`. The legacy ViewDescriptor-only model is still supported but is no longer the primary pattern. Key changes:
+
+- **SDK-based scaffolding** — `new-plugin` writes `package.json` with `@appos.space/plugin-types` (declaration-only types), `@appos.space/plugin-utils` (runtime helpers), and `@appos.space/view-builders` (typed view builders), plus a `tsconfig.json` with `verbatimModuleSyntax: true` and a `build.mjs` esbuild-API build script.
+- **WebView panels are first-class** — the `webview-panels` skill covers `registerWebPanel`, the host-injected webview bridge, CSP constraints, typed message protocols, throttled broadcasts, and `pipeShellToWebPanel` for streaming CLI output directly to the UI.
+- **minHostVersion landmine documented** — the single most common "plugin won't appear in Settings" bug has a prominent warning everywhere it matters.
 - **Canonical reference** — `appos-plugin-ytdlp` is the flagship plugin that exercises every supported SDK feature. Skills and agents point at it for ground truth.
 
 ## Features
@@ -37,6 +45,30 @@ The plugin lives at `plugins/appos-dev` inside this repo (marketplace layout):
 claude --plugin-dir /path/to/appos-dev-plugin/plugins/appos-dev
 ```
 
+## Repository layout
+
+```
+appos-dev-plugin/
+├── .claude-plugin/
+│   └── marketplace.json     # Marketplace catalog (the repo's ONLY manifest) — points at ./plugins/appos-dev
+├── plugins/
+│   └── appos-dev/           # The actual Claude Code plugin
+│       ├── commands/        # new-plugin, build, deploy, validate
+│       ├── agents/          # plugin-architect, viewdescriptor-builder, webview-panel-builder
+│       ├── skills/
+│       │   ├── appos-plugin-dev/        # Main SDK skill + reference/ (incl. plugin-api/ d.ts mirror)
+│       │   ├── viewdescriptor-authoring/
+│       │   └── webview-panels/
+│       └── compiled/        # GENERATED context artifacts consumed by the AppOS host (do not hand-edit)
+├── scripts/                 # verify-knowledge.mjs, check-sdk-freshness.sh, check-compiled-freshness.sh
+├── package.json             # exact-pinned toolchain for the verification gate
+├── README.md
+├── CLAUDE.md                # contributor instructions for THIS repo (not shipped as plugin context)
+└── LICENSE
+```
+
+The `compiled/` artifacts are generated by the AppOS-Desktop repo's `scripts/compile-factory-context.sh` (which concatenates the skill sources for the host's in-app AI features) — regenerate them from that script rather than editing them; they are validated by freshness manifests, not by the knowledge gate.
+
 ## Commands
 
 | Command | Description |
@@ -51,13 +83,15 @@ claude --plugin-dir /path/to/appos-dev-plugin/plugins/appos-dev
 | Skill | Triggers on |
 |-------|-------------|
 | appos-plugin-dev | "AppOS plugin", "workspace manager plugin", PluginContext, SDK packages, workspaces, menubar |
+| viewdescriptor-authoring | "ViewDescriptor", "sidebar panel UI", "listItem", "menuActions", "section with badge", column alignment |
 | webview-panels | "registerWebPanel", "postToWebPanel", "pipeShellToWebPanel", "bridge.js", "shell chunks", CSP, webview |
 
 ## Agents
 
 | Agent | Purpose |
 |-------|---------|
 | plugin-architect | Designs plugin structure from requirements — maps APIs, permissions, rendering mode, settings |
+| viewdescriptor-builder | Builds ViewDescriptor JSON trees — all 17 view types, columns, menuActions, empty/loading states |
 | webview-panel-builder | Builds WebView panels end-to-end — registration, HTML bundle, typed message protocol, pipeShellToWebPanel wiring |
 
 ## Prerequisites
@@ -79,6 +113,27 @@ claude --plugin-dir /path/to/appos-dev-plugin/plugins/appos-dev
 - `pipeShellToWebPanel` lives on `ctx.ui`, NOT `ctx.shell` (stale docs are wrong)
 - Install path: `~/Library/Application Support/AppOS/plugins/{plugin-id}/` (see `/appos-dev:deploy`)
 
+## Knowledge verification (CI)
+
+Every teaching surface in this repo is gated against the PUBLISHED `@appos.space/plugin-types` package (`.github/workflows/verify.yml` runs all three checks on PR via `npm ci`). Reproduce CI locally with:
+
+```bash
+npm ci          # install the exact-pinned toolchain
+npm run check   # the full CI sequence — the three gates below, in order
+```
+
+`npm run check` expands to:
+
+```bash
+scripts/check-sdk-freshness.sh        # bundled d.ts mirror byte-equal to the npm tarball
+node scripts/verify-knowledge.mjs     # fence type-check + stale-identifier denylist + count consistency
+scripts/check-compiled-freshness.sh   # compiled/ artifacts match their manifest, both directions
+```
+
+The bundled type reference is `plugins/appos-dev/skills/appos-plugin-dev/reference/plugin-api/` — a byte-verbatim mirror of the published tarball's `dist/*.d.ts` files. Its `INDEX.md` records the `dist.integrity` pin, per-file sha256 hashes, and the regeneration command (`scripts/check-sdk-freshness.sh --update`).
+
+> Maintainer note (2026-07): the canonical local clone of this repo is `~/Documents/GitHub/AppOS/appos-dev-plugin`. The historical duplicate clone at `~/Documents/GitHub/appos-dev-plugin` is retired — tombstoned with a `RETIRED.md` pointing here — so edits land in exactly one working copy.
+
 ## License
 
 MIT