diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json
index 4df6677..a01fb69 100644
--- a/.cursor-plugin/marketplace.json
+++ b/.cursor-plugin/marketplace.json
@@ -11,37 +11,42 @@
     {
       "name": "teaching",
       "source": "teaching",
-      "description": "Skill mapping, practice plans, and learning retrospectives."
+      "description": "USER LEVEL: You get a structured path with checkpoints and retros—less thrashing, clearer progress signals on what to drill next. PROJECT LEVEL: Onboarding and mentorship scale because skill goals and practice cadence are explicit instead of tribal knowledge. Builds skill maps, practice plans, and learning retrospectives with milestones so improvement is deliberate instead of random prompt attempts. BEST SUITED FOR: • Developers leveling up on a new language, stack, or framework • Mentors needing repeatable lesson and practice scaffolding • Teams capturing how they teach internal tools and APIs"
     },
     {
       "name": "continual-learning",
       "source": "continual-learning",
-      "description": "Incremental transcript-driven memory updates for AGENTS.md using high-signal bullet points only."
+      "description": "USER LEVEL: You stop repeating the same stylistic rules, name choices, and workflow quirks every Monday—the assistant remembers what actually stuck. PROJECT LEVEL: Shared agent guidance reflects how the team works today, not a stale template from the repo’s first commit. Mines transcripts for durable preferences and facts, then appends concise bullets to AGENTS.md so future sessions start aligned. BEST SUITED FOR: • Long-lived monorepos with evolving conventions • Teams heavy on Cursor and shared AGENTS.md guidance • Projects where small decisions deserve persistent agent memory"
     },
     {
       "name": "cursor-team-kit",
       "source": "cursor-team-kit",
-      "description": "Internal team workflows used by Cursor developers for CI, code review, and shipping."
+      "description": "USER LEVEL: You inherit battle-tested habits from Cursor engineers when CI breaks, reviews stall, or diffs need tightening before merge. PROJECT LEVEL: Teams converge on repeatable PR and CI hygiene instead of inventing bespoke runbooks per repo. Cursor’s internal shipping playbook as skills—CI triage and fixes, PR flow, conflicts, smoke and compiler checks, cleanup passes, and summaries. BEST SUITED FOR: • Repositories with active GitHub Actions or similar CI • Maintainers juggling multiple PRs and flaky checks • Groups adopting structured review and ship discipline"
     },
     {
       "name": "create-plugin",
       "source": "create-plugin",
-      "description": "Scaffold and validate new Cursor plugins."
+      "description": "USER LEVEL: You create a valid plugin skeleton without memorizing manifest edge cases or marketplace wiring. PROJECT LEVEL: Internal extensions and partner plugins stay consistent, cutting review churn from broken metadata. Scaffolds marketplace-ready Cursor plugins—folder layout, manifest, optional skills and MCP—and runs quality checks before publish. BEST SUITED FOR: • Teams packaging MCP servers with skills and rules • Authors preparing Cursor marketplace submissions • Platform groups standardizing plugin templates"
     },
     {
       "name": "ralph-loop",
       "source": "ralph-loop",
-      "description": "Iterative self-referential AI loops using the Ralph Wiggum technique."
+      "description": "USER LEVEL: You offload grindy fix-test cycles while keeping guardrails (hooks) that prevent infinite thrash. PROJECT LEVEL: Deterministic refactors or test stabilizations finish without micromanaging every intermediate step. Runs an agent loop on a focused task—repeat the same prompt with hook-driven stop conditions until the work converges. BEST SUITED FOR: • Large mechanical refactors with clear completion checks • Flaky test stabilization and iterative repro cycles • Tasks where partial progress compounds across attempts"
     },
     {
       "name": "agent-compatibility",
       "source": "agent-compatibility",
-      "description": "CLI-backed repo compatibility scans plus Cursor agents that audit startup, validation, and docs against reality."
+      "description": "USER LEVEL: You avoid losing an afternoon to outdated README steps agents obediently follow into failure. PROJECT LEVEL: Onboarding and automation keep pace when toolchains rotate—docs and CI claims get verified, not assumed. CLI-backed audits that compare install scripts, CI, and docs with what actually runs so agents and humans share a truthful quick start. BEST SUITED FOR: • Complex local setups with many prerequisites • Fast-moving repos where docs drift from reality • Organizations onboarding coding agents broadly"
     },
     {
       "name": "cli-for-agent",
       "source": "cli-for-agent",
-      "description": "Patterns for designing CLIs that coding agents can run reliably: flags, help with examples, pipelines, errors, idempotency, dry-run."
+      "description": "USER LEVEL: You design or review CLI UX that agents can drive without surprise prompts or missing non-interactive paths. PROJECT LEVEL: Internal tools and release CLIs become reliable citizens in CI and agent workflows instead of brittle shells. Patterns for CLIs built for automation—flags, layered help with examples, stdin, actionable errors, idempotency, dry-run. BEST SUITED FOR: • Products exposing developer CLIs • Platform teams wrapping tooling for autonomous runners • Repos where scripts are part of the contract with agents"
+    },
+    {
+      "name": "appwrite",
+      "source": "appwrite",
+      "description": "USER LEVEL: You describe outcomes in plain language (collections, users, functions) and the assistant uses your project’s API key against the real endpoint—less tab switching and fewer stale examples. PROJECT LEVEL: Schemas, permissions, and Functions stay aligned with production because the agent operates on the same Appwrite project your app uses, with reviews still gated by your key scopes. Connects Cursor to your live Appwrite project through the official Appwrite API MCP server and skills so agents read and change real backend resources—not guesses from docs alone. BEST SUITED FOR: • Web and mobile apps built on Appwrite Auth, Databases, and Storage • Teams managing collections, indexes, and Cloud Functions in Appwrite • Self-hosted or Appwrite Cloud projects needing agent-driven operations"
     }
   ]
 }
diff --git a/README.md b/README.md
index e84e9a0..07061aa 100644
--- a/README.md
+++ b/README.md
@@ -4,15 +4,30 @@ Official Cursor plugins for popular developer tools, frameworks, and SaaS produc
 
 ## Plugins
 
-| `name` | Plugin | Author | Category | `description` (from marketplace) |
-|:-------|:-------|:-------|:---------|:-------------------------------------|
-| `continual-learning` | [Continual Learning](continual-learning/) | Cursor | Developer Tools | Incremental transcript-driven memory updates for AGENTS.md using high-signal bullet points only. |
-| `cursor-team-kit` | [Cursor Team Kit](cursor-team-kit/) | Cursor | Developer Tools | Internal team workflows used by Cursor developers for CI, code review, and shipping. |
-| `create-plugin` | [Create Plugin](create-plugin/) | Cursor | Developer Tools | Scaffold and validate new Cursor plugins. |
-| `agent-compatibility` | [Agent Compatibility](agent-compatibility/) | Cursor | Developer Tools | CLI-backed repo compatibility scans plus Cursor agents that audit startup, validation, and docs against reality. |
-| `cli-for-agent` | [CLI for Agents](cli-for-agent/) | Cursor | Developer Tools | Patterns for designing CLIs that coding agents can run reliably: flags, help with examples, pipelines, errors, idempotency, dry-run. |
-
-Author values match each plugin’s `plugin.json` `author.name` (Cursor lists `plugins@cursor.com` in the manifest).
+| `name` | Plugin | Author | Category | Notes |
+|:-------|:-------|:-------|:---------|:------|
+| `appwrite` | [Appwrite](appwrite/) | Appwrite | Developer Tools | Appwrite API MCP (`uvx mcp-server-appwrite`) + skills; configure `.mcp.json` / Cursor MCP env. |
+| `continual-learning` | [Continual Learning](continual-learning/) | Cursor | Developer Tools | Transcript-driven updates to AGENTS.md. |
+| `cursor-team-kit` | [Cursor Team Kit](cursor-team-kit/) | Cursor | Developer Tools | CI, PR, and shipping skills. |
+| `create-plugin` | [Create Plugin](create-plugin/) | Cursor | Developer Tools | Plugin scaffolding and checks. |
+| `ralph-loop` | [Ralph Loop](ralph-loop/) | Cursor | Developer Tools | Iterative agent loops with hooks. |
+| `teaching` | [Teaching](teaching/) | Cursor | Utilities | Skill maps, practice plans, retrospectives. |
+| `agent-compatibility` | [Agent Compatibility](agent-compatibility/) | Cursor | Developer Tools | Audits docs/CI vs runnable reality. |
+| `cli-for-agent` | [CLI for Agents](cli-for-agent/) | Cursor | Developer Tools | CLI design patterns for automation. |
+
+Marketplace copy is **composed** from structured `marketplaceDetail` in each `.cursor-plugin/plugin.json` (`USER LEVEL`, `PROJECT LEVEL`, overview line, `BEST SUITED FOR` bullets) so the Cursor detail view (`marketplace-editor__description`) stays a single paragraph **without duplicated “integrate with your projects” phrasing**—edit the YAML-like fields, then run `npm run compose`.
+
+### After Cursor refreshes plugin cache
+
+Cursor may overwrite `~/.cursor/plugins/cache/cursor-public/**` when it re-downloads packages. To re-apply manifests from this repo:
+
+```bash
+npm run after-cursor-update
+```
+
+That runs `compose` then `sync-cache`. Optionally install a git hook: `powershell -ExecutionPolicy Bypass -File scripts/install-git-post-merge-hook.ps1` (runs the same after `git pull`).
+
+Author values match each plugin’s `plugin.json` `author.name` where listed (Cursor lists `plugins@cursor.com` in Cursor-authored manifests).
 
 ## Repository structure
 
diff --git a/agent-compatibility/.cursor-plugin/plugin.json b/agent-compatibility/.cursor-plugin/plugin.json
index 3b6be7a..c8a8c5c 100644
--- a/agent-compatibility/.cursor-plugin/plugin.json
+++ b/agent-compatibility/.cursor-plugin/plugin.json
@@ -2,7 +2,7 @@
   "name": "agent-compatibility",
   "displayName": "Agent Compatibility",
   "version": "1.0.0",
-  "description": "CLI-backed repo compatibility scans plus Cursor agents that audit startup, validation, and docs against reality.",
+  "description": "USER LEVEL: You avoid losing an afternoon to outdated README steps agents obediently follow into failure. PROJECT LEVEL: Onboarding and automation keep pace when toolchains rotate—docs and CI claims get verified, not assumed. CLI-backed audits that compare install scripts, CI, and docs with what actually runs so agents and humans share a truthful quick start. BEST SUITED FOR: • Complex local setups with many prerequisites • Fast-moving repos where docs drift from reality • Organizations onboarding coding agents broadly",
   "author": {
     "name": "Cursor",
     "email": "plugins@cursor.com"
@@ -28,5 +28,15 @@
     "workflow"
   ],
   "skills": "./skills/",
-  "agents": "./agents/"
+  "agents": "./agents/",
+  "marketplaceDetail": {
+    "summary": "CLI-backed audits that compare install scripts, CI, and docs with what actually runs so agents and humans share a truthful quick start.",
+    "userLevel": "You avoid losing an afternoon to outdated README steps agents obediently follow into failure.",
+    "projectLevel": "Onboarding and automation keep pace when toolchains rotate—docs and CI claims get verified, not assumed.",
+    "bestSuitedFor": [
+      "Complex local setups with many prerequisites",
+      "Fast-moving repos where docs drift from reality",
+      "Organizations onboarding coding agents broadly"
+    ]
+  }
 }
diff --git a/agent-compatibility/README.md b/agent-compatibility/README.md
index 5dcd861..09fd86d 100644
--- a/agent-compatibility/README.md
+++ b/agent-compatibility/README.md
@@ -1,5 +1,22 @@
 # Agent Compatibility
 
+<!-- cursor-plugin-enhancements:begin -->
+
+## Who this is for
+
+### For you (user level)
+You trust the README again: the assistant checks whether install, test, and lint commands in docs match what the repo really does.
+
+### For your projects (project level)
+Open-source and inner-source projects reduce onboarding friction and agent failure modes when “quick start” drift silently breaks.
+
+### Best suited for
+- Polyglot or fast-moving repos where docs fall behind scripts
+- Projects onboarding agents as first-class “users” of the repo
+- Maintainers preparing for external contributors or marketplace plugins
+
+<!-- cursor-plugin-enhancements:end -->
+
 Cursor plugin for checking how well a repo holds up under agent workflows. It pairs the published `agent-compatibility` CLI with focused reviews for startup, validation, and docs reliability.
 
 By default, the full pass returns one overall score and one short list of the highest-leverage fixes. If the user wants the full breakdown, the agents can expose the component scores and the reasoning behind them.
diff --git a/appwrite/.cursor-plugin/plugin.json b/appwrite/.cursor-plugin/plugin.json
new file mode 100644
index 0000000..da58919
--- /dev/null
+++ b/appwrite/.cursor-plugin/plugin.json
@@ -0,0 +1,41 @@
+{
+  "name": "appwrite",
+  "displayName": "Appwrite",
+  "version": "1.0.0",
+  "description": "USER LEVEL: You describe outcomes in plain language (collections, users, functions) and the assistant uses your project’s API key against the real endpoint—less tab switching and fewer stale examples. PROJECT LEVEL: Schemas, permissions, and Functions stay aligned with production because the agent operates on the same Appwrite project your app uses, with reviews still gated by your key scopes. Connects Cursor to your live Appwrite project through the official Appwrite API MCP server and skills so agents read and change real backend resources—not guesses from docs alone. BEST SUITED FOR: • Web and mobile apps built on Appwrite Auth, Databases, and Storage • Teams managing collections, indexes, and Cloud Functions in Appwrite • Self-hosted or Appwrite Cloud projects needing agent-driven operations",
+  "author": {
+    "name": "Appwrite",
+    "email": "team@appwrite.io"
+  },
+  "homepage": "https://appwrite.io",
+  "repository": "https://github.com/appwrite/appwrite",
+  "license": "MIT",
+  "keywords": [
+    "appwrite",
+    "baas",
+    "backend",
+    "mcp",
+    "database",
+    "auth",
+    "functions"
+  ],
+  "category": "developer-tools",
+  "tags": [
+    "backend",
+    "cloud",
+    "api",
+    "mcp"
+  ],
+  "skills": "./skills/",
+  "mcpServers": ".mcp.json",
+  "marketplaceDetail": {
+    "summary": "Connects Cursor to your live Appwrite project through the official Appwrite API MCP server and skills so agents read and change real backend resources—not guesses from docs alone.",
+    "userLevel": "You describe outcomes in plain language (collections, users, functions) and the assistant uses your project’s API key against the real endpoint—less tab switching and fewer stale examples.",
+    "projectLevel": "Schemas, permissions, and Functions stay aligned with production because the agent operates on the same Appwrite project your app uses, with reviews still gated by your key scopes.",
+    "bestSuitedFor": [
+      "Web and mobile apps built on Appwrite Auth, Databases, and Storage",
+      "Teams managing collections, indexes, and Cloud Functions in Appwrite",
+      "Self-hosted or Appwrite Cloud projects needing agent-driven operations"
+    ]
+  }
+}
diff --git a/appwrite/.mcp.json b/appwrite/.mcp.json
new file mode 100644
index 0000000..420e063
--- /dev/null
+++ b/appwrite/.mcp.json
@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "appwrite": {
+      "command": "uvx",
+      "args": ["mcp-server-appwrite"],
+      "env": {
+        "APPWRITE_PROJECT_ID": "YOUR_PROJECT_ID",
+        "APPWRITE_API_KEY": "YOUR_API_KEY",
+        "APPWRITE_ENDPOINT": "https://cloud.appwrite.io/v1"
+      }
+    }
+  }
+}
diff --git a/appwrite/README.md b/appwrite/README.md
new file mode 100644
index 0000000..3b9429f
--- /dev/null
+++ b/appwrite/README.md
@@ -0,0 +1,14 @@
+# Appwrite plugin
+
+Official-style integration pattern: **skills** teach when and how to use Appwrite safely; **MCP** (`mcp-server-appwrite` via `uvx`) performs live API operations.
+
+## MCP setup
+
+1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/) so `uvx` is available.
+2. Create an Appwrite API key with the scopes you are willing to expose to the assistant.
+3. In `.mcp.json`, replace placeholders—or override env vars in **Cursor Settings → MCP** for this server.
+4. For self-hosted Appwrite, set `APPWRITE_ENDPOINT` to your instance API URL (see Appwrite docs for the `/v1` base).
+
+## Tool surface
+
+Additional APIs (users, storage, functions, …) are opt-in flags on `mcp-server-appwrite` to control context size.
diff --git a/appwrite/skills/appwrite/SKILL.md b/appwrite/skills/appwrite/SKILL.md
new file mode 100644
index 0000000..2ea615d
--- /dev/null
+++ b/appwrite/skills/appwrite/SKILL.md
@@ -0,0 +1,10 @@
+---
+name: appwrite
+description: Use when the user works with Appwrite (Auth, Databases, Functions, Storage, teams) and needs accurate API operations or setup guidance inside Cursor.
+---
+
+# Appwrite
+
+- Ensure `.mcp.json` uses real `APPWRITE_PROJECT_ID`, `APPWRITE_API_KEY`, and the correct `APPWRITE_ENDPOINT` (self-hosted installs use their own URL).
+- Prefer enabling only the Appwrite MCP tool groups you need (`uvx mcp-server-appwrite --help`) to preserve model context.
+- Follow least-privilege API keys; never commit secrets—configure them in Cursor MCP settings or environment.
diff --git a/cli-for-agent/.cursor-plugin/plugin.json b/cli-for-agent/.cursor-plugin/plugin.json
index c0d3a06..764a861 100644
--- a/cli-for-agent/.cursor-plugin/plugin.json
+++ b/cli-for-agent/.cursor-plugin/plugin.json
@@ -2,7 +2,7 @@
   "name": "cli-for-agent",
   "displayName": "CLI for Agents",
   "version": "1.0.0",
-  "description": "Patterns for designing CLIs that coding agents can run reliably: non-interactive flags, layered help with examples, pipelines, actionable errors, idempotency, and dry-run.",
+  "description": "USER LEVEL: You design or review CLI UX that agents can drive without surprise prompts or missing non-interactive paths. PROJECT LEVEL: Internal tools and release CLIs become reliable citizens in CI and agent workflows instead of brittle shells. Patterns for CLIs built for automation—flags, layered help with examples, stdin, actionable errors, idempotency, dry-run. BEST SUITED FOR: • Products exposing developer CLIs • Platform teams wrapping tooling for autonomous runners • Repos where scripts are part of the contract with agents",
   "author": {
     "name": "Cursor",
     "email": "plugins@cursor.com"
@@ -26,5 +26,15 @@
     "automation",
     "developer-tools"
   ],
-  "skills": "./skills/"
+  "skills": "./skills/",
+  "marketplaceDetail": {
+    "summary": "Patterns for CLIs built for automation—flags, layered help with examples, stdin, actionable errors, idempotency, dry-run.",
+    "userLevel": "You design or review CLI UX that agents can drive without surprise prompts or missing non-interactive paths.",
+    "projectLevel": "Internal tools and release CLIs become reliable citizens in CI and agent workflows instead of brittle shells.",
+    "bestSuitedFor": [
+      "Products exposing developer CLIs",
+      "Platform teams wrapping tooling for autonomous runners",
+      "Repos where scripts are part of the contract with agents"
+    ]
+  }
 }
diff --git a/cli-for-agent/README.md b/cli-for-agent/README.md
index 6aaedae..bccb996 100644
--- a/cli-for-agent/README.md
+++ b/cli-for-agent/README.md
@@ -1,5 +1,22 @@
 # CLI for Agents
 
+<!-- cursor-plugin-enhancements:begin -->
+
+## Who this is for
+
+### For you (user level)
+You learn how to spot CLIs that will frustrate agents (hidden prompts, ambiguous errors) and how to fix them before they waste a long autonomous run.
+
+### For your projects (project level)
+Tooling and platform teams ship command-line interfaces that are safe for scripts and coding agents—fewer “it works interactively but not in CI” surprises.
+
+### Best suited for
+- Developer tools, CLIs, and internal scripts consumed by automation
+- Repos adding agent-run make/npx/pnpm targets
+- Reviewing third-party CLIs before wiring them into agent playbooks
+
+<!-- cursor-plugin-enhancements:end -->
+
 Cursor plugin with a single skill that encodes patterns for **CLIs meant to be driven by coding agents**: non-interactive flags first, layered `--help` with examples, stdin and pipelines, fast actionable errors, idempotency, `--dry-run`, and predictable command structure.
 
 ## What it includes
diff --git a/continual-learning/.cursor-plugin/plugin.json b/continual-learning/.cursor-plugin/plugin.json
index 8382ba9..a7170bf 100644
--- a/continual-learning/.cursor-plugin/plugin.json
+++ b/continual-learning/.cursor-plugin/plugin.json
@@ -2,7 +2,7 @@
   "name": "continual-learning",
   "displayName": "Continual Learning",
   "version": "1.0.0",
-  "description": "Incrementally learns durable user preferences and workspace facts from transcript changes and keeps AGENTS.md up to date with plain bullet points.",
+  "description": "USER LEVEL: You stop repeating the same stylistic rules, name choices, and workflow quirks every Monday—the assistant remembers what actually stuck. PROJECT LEVEL: Shared agent guidance reflects how the team works today, not a stale template from the repo’s first commit. Mines transcripts for durable preferences and facts, then appends concise bullets to AGENTS.md so future sessions start aligned. BEST SUITED FOR: • Long-lived monorepos with evolving conventions • Teams heavy on Cursor and shared AGENTS.md guidance • Projects where small decisions deserve persistent agent memory",
   "author": {
     "name": "Cursor",
     "email": "plugins@cursor.com"
@@ -26,5 +26,15 @@
   ],
   "agents": "./agents/",
   "skills": "./skills/",
-  "hooks": "./hooks/hooks.json"
+  "hooks": "./hooks/hooks.json",
+  "marketplaceDetail": {
+    "summary": "Mines transcripts for durable preferences and facts, then appends concise bullets to AGENTS.md so future sessions start aligned.",
+    "userLevel": "You stop repeating the same stylistic rules, name choices, and workflow quirks every Monday—the assistant remembers what actually stuck.",
+    "projectLevel": "Shared agent guidance reflects how the team works today, not a stale template from the repo’s first commit.",
+    "bestSuitedFor": [
+      "Long-lived monorepos with evolving conventions",
+      "Teams heavy on Cursor and shared AGENTS.md guidance",
+      "Projects where small decisions deserve persistent agent memory"
+    ]
+  }
 }
diff --git a/continual-learning/README.md b/continual-learning/README.md
index 410fe92..604bfe2 100644
--- a/continual-learning/README.md
+++ b/continual-learning/README.md
@@ -1,5 +1,22 @@
 # Continual Learning
 
+<!-- cursor-plugin-enhancements:begin -->
+
+## Who this is for
+
+### For you (user level)
+You stop re-explaining the same editor prefs, branch strategy, or naming quirks—the durable bits accumulate in AGENTS.md without bloating it with noise.
+
+### For your projects (project level)
+Teams share a living AGENTS.md that reflects how this codebase is actually worked on, improving both human and agent onboarding over time.
+
+### Best suited for
+- Long-running projects with recurring conventions worth memorializing
+- Solo devs who want the assistant to “remember” stable preferences safely
+- Repos that already use or want a lightweight AGENTS.md contract
+
+<!-- cursor-plugin-enhancements:end -->
+
 Automatically and incrementally keeps `AGENTS.md` up to date from transcript changes.
 
 The plugin combines:
diff --git a/create-plugin/.cursor-plugin/plugin.json b/create-plugin/.cursor-plugin/plugin.json
index 7a0f947..57057d8 100644
--- a/create-plugin/.cursor-plugin/plugin.json
+++ b/create-plugin/.cursor-plugin/plugin.json
@@ -2,7 +2,7 @@
   "name": "create-plugin",
   "displayName": "Create Plugin",
   "version": "1.0.0",
-  "description": "Scaffold and validate new Cursor plugins. Handles directory setup, manifest generation, and pre-submission quality checks for the marketplace.",
+  "description": "USER LEVEL: You create a valid plugin skeleton without memorizing manifest edge cases or marketplace wiring. PROJECT LEVEL: Internal extensions and partner plugins stay consistent, cutting review churn from broken metadata. Scaffolds marketplace-ready Cursor plugins—folder layout, manifest, optional skills and MCP—and runs quality checks before publish. BEST SUITED FOR: • Teams packaging MCP servers with skills and rules • Authors preparing Cursor marketplace submissions • Platform groups standardizing plugin templates",
   "author": {
     "name": "Cursor",
     "email": "plugins@cursor.com"
@@ -25,5 +25,15 @@
   ],
   "skills": "./skills/",
   "rules": "./rules/",
-  "agents": "./agents/"
+  "agents": "./agents/",
+  "marketplaceDetail": {
+    "summary": "Scaffolds marketplace-ready Cursor plugins—folder layout, manifest, optional skills and MCP—and runs quality checks before publish.",
+    "userLevel": "You create a valid plugin skeleton without memorizing manifest edge cases or marketplace wiring.",
+    "projectLevel": "Internal extensions and partner plugins stay consistent, cutting review churn from broken metadata.",
+    "bestSuitedFor": [
+      "Teams packaging MCP servers with skills and rules",
+      "Authors preparing Cursor marketplace submissions",
+      "Platform groups standardizing plugin templates"
+    ]
+  }
 }
diff --git a/create-plugin/README.md b/create-plugin/README.md
index 51470c8..b196a79 100644
--- a/create-plugin/README.md
+++ b/create-plugin/README.md
@@ -1,5 +1,22 @@
 # Create plugin
 
+<!-- cursor-plugin-enhancements:begin -->
+
+## Who this is for
+
+### For you (user level)
+You go from idea to valid plugin layout quickly—manifests, skills folders, MCP stubs—without rereading the whole spec every time.
+
+### For your projects (project level)
+Platform and DX teams can standardize internal plugins (skills, rules, MCP) with the same structure Cursor expects in the marketplace.
+
+### Best suited for
+- Authors publishing or dogfooding Cursor plugins
+- Companies packaging internal tools as repeatable agent surfaces
+- Anyone avoiding hand-rolled broken manifests
+
+<!-- cursor-plugin-enhancements:end -->
+
 Meta workflows for creating Cursor plugins that are marketplace-ready.
 
 ## Installation
diff --git a/cursor-team-kit/.cursor-plugin/plugin.json b/cursor-team-kit/.cursor-plugin/plugin.json
index 549ba3d..20d7e29 100644
--- a/cursor-team-kit/.cursor-plugin/plugin.json
+++ b/cursor-team-kit/.cursor-plugin/plugin.json
@@ -2,7 +2,7 @@
   "name": "cursor-team-kit",
   "displayName": "Cursor Team Kit",
   "version": "1.0.0",
-  "description": "Internal workflows used by Cursor developers for CI, code review, and shipping. Covers the full dev loop: CI monitoring and fixing, PR creation, merge conflicts, smoke tests, compiler checks, code cleanup, and work summaries.",
+  "description": "USER LEVEL: You inherit battle-tested habits from Cursor engineers when CI breaks, reviews stall, or diffs need tightening before merge. PROJECT LEVEL: Teams converge on repeatable PR and CI hygiene instead of inventing bespoke runbooks per repo. Cursor’s internal shipping playbook as skills—CI triage and fixes, PR flow, conflicts, smoke and compiler checks, cleanup passes, and summaries. BEST SUITED FOR: • Repositories with active GitHub Actions or similar CI • Maintainers juggling multiple PRs and flaky checks • Groups adopting structured review and ship discipline",
   "author": {
     "name": "Cursor",
     "email": "plugins@cursor.com"
@@ -26,5 +26,15 @@
   ],
   "skills": "./skills/",
   "agents": "./agents/",
-  "rules": "./rules/"
+  "rules": "./rules/",
+  "marketplaceDetail": {
+    "summary": "Cursor’s internal shipping playbook as skills—CI triage and fixes, PR flow, conflicts, smoke and compiler checks, cleanup passes, and summaries.",
+    "userLevel": "You inherit battle-tested habits from Cursor engineers when CI breaks, reviews stall, or diffs need tightening before merge.",
+    "projectLevel": "Teams converge on repeatable PR and CI hygiene instead of inventing bespoke runbooks per repo.",
+    "bestSuitedFor": [
+      "Repositories with active GitHub Actions or similar CI",
+      "Maintainers juggling multiple PRs and flaky checks",
+      "Groups adopting structured review and ship discipline"
+    ]
+  }
 }
diff --git a/cursor-team-kit/README.md b/cursor-team-kit/README.md
index 91e938f..6f1e9d4 100644
--- a/cursor-team-kit/README.md
+++ b/cursor-team-kit/README.md
@@ -1,5 +1,22 @@
 # Cursor Team Kit plugin
 
+<!-- cursor-plugin-enhancements:begin -->
+
+## Who this is for
+
+### For you (user level)
+You borrow Cursor’s own muscle memory for “CI red → fix → green → ship,” including conflict resolution and PR hygiene, without inventing your own checklist each time.
+
+### For your projects (project level)
+Teams that live in GitHub PRs and Actions get repeatable playbooks for loop-on-CI, smoke tests, and merge-ready diffs—especially valuable under time pressure.
+
+### Best suited for
+- Repositories with active GitHub Actions (or similar CI)
+- Contributors who want opinionated, battle-tested shipping skills
+- Maintainers drowning in flaky checks and noisy AI-generated diffs
+
+<!-- cursor-plugin-enhancements:end -->
+
 Internal-style workflows for CI, code review, shipping, and test reliability.
 
 ## Installation
diff --git a/package-lock.json b/package-lock.json
new file mode 100644
index 0000000..489b4c0
--- /dev/null
+++ b/package-lock.json
@@ -0,0 +1,90 @@
+{
+  "name": "cursor-plugins-upstream",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "cursor-plugins-upstream",
+      "devDependencies": {
+        "ajv": "^8.17.1",
+        "ajv-formats": "^3.0.1"
+      }
+    },
+    "node_modules/ajv": {
+      "version": "8.18.0",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.18.0.tgz",
+      "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fast-deep-equal": "^3.1.3",
+        "fast-uri": "^3.0.1",
+        "json-schema-traverse": "^1.0.0",
+        "require-from-string": "^2.0.2"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/epoberezkin"
+      }
+    },
+    "node_modules/ajv-formats": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/ajv-formats/-/ajv-formats-3.0.1.tgz",
+      "integrity": "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ajv": "^8.0.0"
+      },
+      "peerDependencies": {
+        "ajv": "^8.0.0"
+      },
+      "peerDependenciesMeta": {
+        "ajv": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/fast-deep-equal": {
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
+      "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/fast-uri": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz",
+      "integrity": "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/json-schema-traverse": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
+      "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/require-from-string": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
+      "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    }
+  }
+}
diff --git a/package.json b/package.json
new file mode 100644
index 0000000..1e83892
--- /dev/null
+++ b/package.json
@@ -0,0 +1,14 @@
+{
+  "name": "cursor-plugins-upstream",
+  "private": true,
+  "scripts": {
+    "validate": "node scripts/validate-plugins.mjs",
+    "compose": "node scripts/compose-marketplace-descriptions.mjs",
+    "sync-cache": "node scripts/sync-plugin-cache.mjs",
+    "after-cursor-update": "node scripts/run-after-cursor-update.mjs"
+  },
+  "devDependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1"
+  }
+}
diff --git a/ralph-loop/.cursor-plugin/plugin.json b/ralph-loop/.cursor-plugin/plugin.json
index 529e02e..c5c37f3 100644
--- a/ralph-loop/.cursor-plugin/plugin.json
+++ b/ralph-loop/.cursor-plugin/plugin.json
@@ -2,7 +2,7 @@
   "name": "ralph-loop",
   "displayName": "Ralph Loop",
   "version": "1.0.0",
-  "description": "Continuous self-referential AI loops for iterative development, implementing the Ralph Wiggum technique. Run the agent in a while-true loop with the same prompt until task completion.",
+  "description": "USER LEVEL: You offload grindy fix-test cycles while keeping guardrails (hooks) that prevent infinite thrash. PROJECT LEVEL: Deterministic refactors or test stabilizations finish without micromanaging every intermediate step. Runs an agent loop on a focused task—repeat the same prompt with hook-driven stop conditions until the work converges. BEST SUITED FOR: • Large mechanical refactors with clear completion checks • Flaky test stabilization and iterative repro cycles • Tasks where partial progress compounds across attempts",
   "author": {
     "name": "Cursor",
     "email": "plugins@cursor.com"
@@ -26,5 +26,15 @@
     "agent-loop"
   ],
   "skills": "./skills/",
-  "hooks": "./hooks/hooks.json"
+  "hooks": "./hooks/hooks.json",
+  "marketplaceDetail": {
+    "summary": "Runs an agent loop on a focused task—repeat the same prompt with hook-driven stop conditions until the work converges.",
+    "userLevel": "You offload grindy fix-test cycles while keeping guardrails (hooks) that prevent infinite thrash.",
+    "projectLevel": "Deterministic refactors or test stabilizations finish without micromanaging every intermediate step.",
+    "bestSuitedFor": [
+      "Large mechanical refactors with clear completion checks",
+      "Flaky test stabilization and iterative repro cycles",
+      "Tasks where partial progress compounds across attempts"
+    ]
+  }
 }
diff --git a/schemas/plugin.schema.json b/schemas/plugin.schema.json
index d4c539e..af92416 100644
--- a/schemas/plugin.schema.json
+++ b/schemas/plugin.schema.json
@@ -92,6 +92,32 @@
     "mcpServers": {
       "$ref": "#/$defs/mcpServers",
       "description": "MCP server configuration — a path, an inline config object, or an array of either."
+    },
+    "marketplaceDetail": {
+      "type": "object",
+      "description": "Structured marketplace copy maintained in-repo; compose into description for the Cursor marketplace UI.",
+      "additionalProperties": false,
+      "required": ["summary", "userLevel", "projectLevel", "bestSuitedFor"],
+      "properties": {
+        "summary": {
+          "type": "string",
+          "description": "One-sentence lead shown in composed marketplace description."
+        },
+        "userLevel": {
+          "type": "string",
+          "description": "How this helps you as an individual (person-level, not repo-wide)."
+        },
+        "projectLevel": {
+          "type": "string",
+          "description": "How this helps your codebase, team, or delivery pipeline."
+        },
+        "bestSuitedFor": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string" },
+          "description": "Kinds of projects or workflows where this plugin shines."
+        }
+      }
     }
   },
   "$defs": {
diff --git a/scripts/compose-marketplace-descriptions.mjs b/scripts/compose-marketplace-descriptions.mjs
new file mode 100644
index 0000000..c1b77ff
--- /dev/null
+++ b/scripts/compose-marketplace-descriptions.mjs
@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * Merges marketplaceDetail into plugin.description and mirrors short copy into
+ * root .cursor-plugin/marketplace.json entries. Run after editing marketplaceDetail.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, "..");
+const marketplacePath = resolve(root, ".cursor-plugin/marketplace.json");
+
+function loadJSON(path) {
+  return JSON.parse(readFileSync(path, "utf-8"));
+}
+
+function composeDescription(detail) {
+  const bullets = (detail.bestSuitedFor ?? []).map((b) => `• ${b}`).join(" ");
+  return [
+    `USER LEVEL: ${detail.userLevel.trim()}`,
+    `PROJECT LEVEL: ${detail.projectLevel.trim()}`,
+    detail.summary.trim(),
+    bullets ? `BEST SUITED FOR: ${bullets}` : "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+}
+
+if (!existsSync(marketplacePath)) {
+  console.error("Missing .cursor-plugin/marketplace.json");
+  process.exit(1);
+}
+
+const marketplace = loadJSON(marketplacePath);
+const descByName = {};
+
+for (const entry of marketplace.plugins ?? []) {
+  const pluginJsonPath = resolve(root, entry.source, ".cursor-plugin/plugin.json");
+  if (!existsSync(pluginJsonPath)) {
+    console.warn(`Skip ${entry.name}: no plugin.json`);
+    continue;
+  }
+  const plugin = loadJSON(pluginJsonPath);
+  const detail = plugin.marketplaceDetail;
+  if (!detail) {
+    console.warn(`Skip ${entry.name}: no marketplaceDetail`);
+    continue;
+  }
+  plugin.description = composeDescription(detail);
+  writeFileSync(pluginJsonPath, JSON.stringify(plugin, null, 2) + "\n", "utf-8");
+  descByName[entry.name] = plugin.description;
+  console.log(`Composed description for ${entry.name}`);
+}
+
+let mpChanged = false;
+for (const entry of marketplace.plugins ?? []) {
+  if (descByName[entry.name] != null && entry.description !== descByName[entry.name]) {
+    entry.description = descByName[entry.name];
+    mpChanged = true;
+  }
+}
+
+if (mpChanged) {
+  writeFileSync(
+    marketplacePath,
+    JSON.stringify(marketplace, null, 2) + "\n",
+    "utf-8"
+  );
+  console.log("Updated .cursor-plugin/marketplace.json descriptions");
+}
diff --git a/scripts/install-git-post-merge-hook.ps1 b/scripts/install-git-post-merge-hook.ps1
new file mode 100644
index 0000000..8cfc75c
--- /dev/null
+++ b/scripts/install-git-post-merge-hook.ps1
@@ -0,0 +1,30 @@
+# Run after `git pull` / merge: re-apply composed manifests into Cursor's plugin cache.
+# Install once from repo root:
+#   powershell -ExecutionPolicy Bypass -File scripts/install-git-post-merge-hook.ps1
+
+$ErrorActionPreference = "Stop"
+$RepoRoot = Split-Path -Parent (Split-Path -Parent $MyInvocation.MyCommand.Path)
+$HookDir = Join-Path $RepoRoot ".git\hooks"
+$HookPath = Join-Path $HookDir "post-merge"
+
+if (-not (Test-Path (Join-Path $RepoRoot ".git"))) {
+  Write-Error "Run this from a git clone of cursor-plugins-upstream (no .git found)."
+}
+
+$Node = "node"
+$Script = Join-Path $RepoRoot "scripts\run-after-cursor-update.mjs"
+
+$RootSh = ($RepoRoot -replace '\\', '/')
+$HookBody = @"
+#!/bin/sh
+# cursor-plugins-upstream: refresh local Cursor cache after pull
+cd "$RootSh" || exit 1
+node scripts/run-after-cursor-update.mjs || exit 1
+"@
+
+New-Item -ItemType Directory -Force -Path $HookDir | Out-Null
+Set-Content -Path $HookPath -Value $HookBody -Encoding utf8
+
+# Git for Windows: ensure hook is executable not required on Windows; use bash if present
+Write-Host "Wrote $HookPath"
+Write-Host "On Windows, Git often runs hooks via sh—verify hook runs after your next git pull."
diff --git a/scripts/run-after-cursor-update.mjs b/scripts/run-after-cursor-update.mjs
new file mode 100644
index 0000000..79852c0
--- /dev/null
+++ b/scripts/run-after-cursor-update.mjs
@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * One-shot workflow after Cursor refreshes the cursor-public cache from the network:
+ * 1) Re-compose descriptions from marketplaceDetail (if you edited structured fields).
+ * 2) Push composed manifests back into ~/.cursor/plugins/cache.
+ */
+import { spawnSync } from "child_process";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, "..");
+
+function run(node, args) {
+  const r = spawnSync(node, args, { stdio: "inherit", cwd: root });
+  if (r.status !== 0) process.exit(r.status ?? 1);
+}
+
+run(process.execPath, [resolve(root, "scripts", "compose-marketplace-descriptions.mjs")]);
+run(process.execPath, [resolve(root, "scripts", "sync-plugin-cache.mjs")]);
+console.log("after-cursor-update: done.");
diff --git a/scripts/sync-plugin-cache.mjs b/scripts/sync-plugin-cache.mjs
new file mode 100644
index 0000000..416fe59
--- /dev/null
+++ b/scripts/sync-plugin-cache.mjs
@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+/**
+ * After Cursor re-downloads cursor-public plugin packages into ~/.cursor/plugins/cache,
+ * copy manifests from this repo back into matching cache folders so restored copy wins.
+ *
+ * Usage: node scripts/sync-plugin-cache.mjs
+ * Optional: PLUGIN_NAME=appwrite node scripts/sync-plugin-cache.mjs  (single plugin)
+ */
+
+import {
+  readFileSync,
+  copyFileSync,
+  existsSync,
+  readdirSync,
+  statSync,
+} from "fs";
+import { resolve, join, dirname } from "path";
+import { homedir } from "os";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, "..");
+const cacheRoot = join(homedir(), ".cursor", "plugins", "cache", "cursor-public");
+
+const FILES_TRY = [
+  ".cursor-plugin/plugin.json",
+  ".cursor-plugin/marketplace.json",
+  ".mcp.json",
+  "mcp.json",
+];
+
+function loadJSON(p) {
+  return JSON.parse(readFileSync(p, "utf-8"));
+}
+
+function findCacheDirsForPlugin(pluginName) {
+  const out = [];
+  if (!existsSync(cacheRoot)) return out;
+  const want = String(pluginName).trim().toLowerCase();
+  for (const top of readdirSync(cacheRoot)) {
+    const p = join(cacheRoot, top);
+    if (!statSync(p).isDirectory()) continue;
+    for (const hash of readdirSync(p)) {
+      const dir = join(p, hash);
+      if (!statSync(dir).isDirectory()) continue;
+      const pj = join(dir, ".cursor-plugin", "plugin.json");
+      if (!existsSync(pj)) continue;
+      try {
+        const j = loadJSON(pj);
+        const n = String(j.name ?? "").trim().toLowerCase();
+        if (n === want) out.push(dir);
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+  return out;
+}
+
+function syncPlugin(pluginName, sourceRel) {
+  const srcDir = resolve(root, sourceRel);
+  const targets = findCacheDirsForPlugin(pluginName);
+  if (targets.length === 0) {
+    console.warn(`No cache hit for "${pluginName}" under ${cacheRoot}`);
+    return 0;
+  }
+  let n = 0;
+  for (const destRoot of targets) {
+    for (const rel of FILES_TRY) {
+      const from = join(srcDir, rel);
+      const to = join(destRoot, rel);
+      if (!existsSync(from)) continue;
+      const dir = resolve(to, "..");
+      if (!existsSync(dir)) continue;
+      copyFileSync(from, to);
+      n++;
+      console.log(`${pluginName}: ${rel} -> ${to}`);
+    }
+  }
+  return n;
+}
+
+const only = process.env.PLUGIN_NAME?.trim();
+const marketplace = loadJSON(resolve(root, ".cursor-plugin", "marketplace.json"));
+const plugins = only
+  ? marketplace.plugins.filter((e) => e.name === only)
+  : marketplace.plugins;
+
+let total = 0;
+for (const entry of plugins) {
+  total += syncPlugin(entry.name, entry.source);
+}
+console.log(`Done. ${total} file(s) copied.`);
diff --git a/teaching/.cursor-plugin/plugin.json b/teaching/.cursor-plugin/plugin.json
index 6691793..f512fca 100644
--- a/teaching/.cursor-plugin/plugin.json
+++ b/teaching/.cursor-plugin/plugin.json
@@ -2,7 +2,7 @@
   "name": "teaching",
   "displayName": "Teaching",
   "version": "1.0.0",
-  "description": "Skill mapping, practice plans, and learning retrospectives. Builds personalized roadmaps with milestones and practice checkpoints, and runs periodic reviews to adjust based on progress.",
+  "description": "USER LEVEL: You get a structured path with checkpoints and retros—less thrashing, clearer progress signals on what to drill next. PROJECT LEVEL: Onboarding and mentorship scale because skill goals and practice cadence are explicit instead of tribal knowledge. Builds skill maps, practice plans, and learning retrospectives with milestones so improvement is deliberate instead of random prompt attempts. BEST SUITED FOR: • Developers leveling up on a new language, stack, or framework • Mentors needing repeatable lesson and practice scaffolding • Teams capturing how they teach internal tools and APIs",
   "author": {
     "name": "Cursor",
     "email": "plugins@cursor.com"
@@ -24,5 +24,15 @@
     "education",
     "practice"
   ],
-  "skills": "./skills/"
+  "skills": "./skills/",
+  "marketplaceDetail": {
+    "summary": "Builds skill maps, practice plans, and learning retrospectives with milestones so improvement is deliberate instead of random prompt attempts.",
+    "userLevel": "You get a structured path with checkpoints and retros—less thrashing, clearer progress signals on what to drill next.",
+    "projectLevel": "Onboarding and mentorship scale because skill goals and practice cadence are explicit instead of tribal knowledge.",
+    "bestSuitedFor": [
+      "Developers leveling up on a new language, stack, or framework",
+      "Mentors needing repeatable lesson and practice scaffolding",
+      "Teams capturing how they teach internal tools and APIs"
+    ]
+  }
 }