@lumiastream/plugin 0.4.6 → 0.5.0

package/README.md

@@ -169,6 +169,9 @@ Plugins execute in an isolated **Node.js** process (no browser DOM). Use Node-co
 - `npm run lint` – type-check the source without emitting output.
 - `npm run package-docs` – rebuild the GPT knowledge pack in `gpt-knowledge/lumia-plugin-sdk-docs`.
 - `npm run sync:developer-docs` – sync core SDK docs and generated example pages into `../Developer-Docs/docs/plugin-sdk` (no manual copy/paste).
+- `npm run sync:skills` – refresh Codex skill docs snapshot, Claude skill docs snapshot, and Cursor rules together.
+- `npm run validate:skills` – validate Codex skill + Claude skill + Copilot instructions + Gemini instructions + Cursor rule version alignment.
+- `npm run update:assistant-files -- --target <plugin-path>` – pull latest assistant files (Claude/Copilot/Gemini/Cursor, optional Codex) from `main`.
 
 ## CLI Helpers
 
@@ -178,6 +181,197 @@ The CLI is distributed separately via `lumia-plugin`. Use it with `npx` (require
 - `npx lumia-plugin validate ./path/to/plugin` check `manifest.json`, entry files, and config for common mistakes
 - `npx lumia-plugin build ./path/to/plugin --out ./plugin.lumiaplugin` bundle the directory into a distributable archive
 
+## AI Editor Support (Codex + Claude + Copilot + Gemini CLI + Cursor)
+
+This repository ships cross-tool guidance for all three tools using this repo as source:
+
+- [https://github.com/lumiastream/Plugin-SDK](https://github.com/lumiastream/Plugin-SDK)
+
+### Codex Desktop
+
+Location:
+
+- `skills/lumia-plugin-codex-skill`
+
+What it does:
+
+- Guides Lumia plugin workflow (scaffold, implement, validate, package)
+- Maps `manifest.json` capabilities to required/recommended runtime hooks
+- Includes `plugin-audit.js` to detect manifest-to-hook mismatches
+
+Install/download into Codex Desktop:
+
+```bash
+python3 "$CODEX_HOME/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
+  --repo lumiastream/Plugin-SDK \
+  --path skills/lumia-plugin-codex-skill
+```
+
+Browser-only install (no curl):
+
+1. Download the repo zip: [Download Plugin-SDK zip](https://github.com/lumiastream/Plugin-SDK/archive/refs/heads/main.zip)
+2. Extract it and copy `skills/lumia-plugin-codex-skill` to `$CODEX_HOME/skills/lumia-plugin-codex-skill`
+3. Restart Codex Desktop
+
+Use:
+
+- Mention `$lumia-plugin-codex-skill` in your prompt
+- Example: `Use $lumia-plugin-codex-skill to scaffold and validate a lights plugin with theme support`
+
+Restart Codex Desktop after installation.
+
+### Claude
+
+Location:
+
+- `skills/lumia-plugin-claude-skill/lumia-plugin-claude-skill.md`
+
+What it does:
+
+- Provides Lumia plugin workflow and capability contract guidance for Claude sessions
+- Includes audit/validation guidance and references synced from SDK docs
+
+Install/download into another project:
+
+```bash
+curl -L https://raw.githubusercontent.com/lumiastream/Plugin-SDK/main/skills/lumia-plugin-claude-skill/lumia-plugin-claude-skill.md \
+  -o /path/to/your-plugin/CLAUDE.md
+```
+
+Browser-only install (no curl):
+
+1. Open [Claude skill file](https://raw.githubusercontent.com/lumiastream/Plugin-SDK/main/skills/lumia-plugin-claude-skill/lumia-plugin-claude-skill.md)
+2. Save it as `CLAUDE.md` in your plugin project root
+
+Optional references bundle:
+
+```bash
+git clone https://github.com/lumiastream/Plugin-SDK.git /tmp/lumia-plugin-sdk
+mkdir -p /path/to/your-plugin/.claude/lumia-plugin-references
+cp -R /tmp/lumia-plugin-sdk/skills/lumia-plugin-claude-skill/references/* /path/to/your-plugin/.claude/lumia-plugin-references/
+```
+
+Use:
+
+- Open your plugin project in Claude
+- Ask Claude to follow `CLAUDE.md` while implementing or validating the plugin
+
+### GitHub Copilot
+
+Location:
+
+- `.github/copilot-instructions.md`
+
+What it does:
+
+- Adds repository-wide Lumia plugin implementation and validation guidance for Copilot
+- Includes workflow steps and manifest capability contract checks
+
+Install/download into another project:
+
+```bash
+mkdir -p /path/to/your-plugin/.github
+curl -L https://raw.githubusercontent.com/lumiastream/Plugin-SDK/main/.github/copilot-instructions.md \
+  -o /path/to/your-plugin/.github/copilot-instructions.md
+```
+
+Browser-only install (no curl):
+
+1. Open [Copilot instructions file](https://raw.githubusercontent.com/lumiastream/Plugin-SDK/main/.github/copilot-instructions.md)
+2. Save it as `.github/copilot-instructions.md` in your plugin project
+
+Use:
+
+- Open your plugin project in VS Code or GitHub with Copilot enabled
+- Copilot Chat uses repository instructions automatically
+
+### Gemini CLI
+
+Location:
+
+- `GEMINI.md`
+
+What it does:
+
+- Provides project guidance for Gemini CLI sessions targeting Lumia plugin development
+- Includes workflow, capability contracts, and validation commands
+
+Install/download into another project:
+
+```bash
+curl -L https://raw.githubusercontent.com/lumiastream/Plugin-SDK/main/GEMINI.md \
+  -o /path/to/your-plugin/GEMINI.md
+```
+
+Browser-only install (no curl):
+
+1. Open [Gemini instructions file](https://raw.githubusercontent.com/lumiastream/Plugin-SDK/main/GEMINI.md)
+2. Save it as `GEMINI.md` in your plugin project root
+
+Use:
+
+- Run Gemini CLI from your plugin project root
+- Ask Gemini to follow `GEMINI.md` while implementing or validating plugin changes
+
+### Cursor
+
+Location:
+
+- `.cursor/rules/lumia-plugin-workflow.mdc`
+- `.cursor/rules/lumia-plugin-manifest-contracts.mdc`
+
+What it does:
+
+- Enforces Lumia plugin workflow steps while editing plugin files
+- Applies capability contract checks when `manifest.json` and runtime hooks change
+
+Install/download into another project:
+
+```bash
+mkdir -p /path/to/your-plugin/.cursor/rules
+cp .cursor/rules/lumia-plugin-*.mdc /path/to/your-plugin/.cursor/rules/
+mkdir -p /path/to/your-plugin/scripts
+cp skills/lumia-plugin-codex-skill/scripts/plugin-audit.js /path/to/your-plugin/scripts/plugin-audit.js
+```
+
+Browser-only install (no curl):
+
+1. Open [Cursor workflow rule](https://raw.githubusercontent.com/lumiastream/Plugin-SDK/main/.cursor/rules/lumia-plugin-workflow.mdc) and save as `.cursor/rules/lumia-plugin-workflow.mdc`
+2. Open [Cursor manifest rule](https://raw.githubusercontent.com/lumiastream/Plugin-SDK/main/.cursor/rules/lumia-plugin-manifest-contracts.mdc) and save as `.cursor/rules/lumia-plugin-manifest-contracts.mdc`
+3. Open [Audit script](https://raw.githubusercontent.com/lumiastream/Plugin-SDK/main/skills/lumia-plugin-codex-skill/scripts/plugin-audit.js) and save as `scripts/plugin-audit.js`
+
+Use:
+
+- Open the plugin project in Cursor
+- Cursor applies matching rules automatically based on file globs
+- Run `node scripts/plugin-audit.js <plugin-dir>` only if you copied the audit script
+
+### Easy Updates (No Full Redownload)
+
+Instead of re-downloading everything, users can pull only the latest assistant files from `main` with one command:
+
+```bash
+npm run update:assistant-files -- --target /path/to/your-plugin
+```
+
+Optional tool selection:
+
+```bash
+npm run update:assistant-files -- --target /path/to/your-plugin --tools claude,copilot,gemini,cursor
+```
+
+Optional Codex skill update (for Codex Desktop install path):
+
+```bash
+npm run update:assistant-files -- --tools codex --codex-home "$CODEX_HOME"
+```
+
+### Automatic Sync on Publish
+
+- `npm run sync:skills`
+- `npm run validate:skills`
+- `prepublishOnly` runs both before publish (covers Codex + Claude + Copilot + Gemini CLI + Cursor)
+
 ## Documentation
 
 - [Getting Started](./docs/getting-started.md)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lumiastream/plugin",
-	"version": "0.4.6",
+	"version": "0.5.0",
 	"description": "Official Lumia Stream Plugin SDK for building Lumia Stream plugins.",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -16,11 +16,14 @@
 	"scripts": {
 		"build": "tsc -p tsconfig.json",
 		"lint": "tsc --noEmit",
-		"package-docs": "node scripts/package-knowledge-pack.js && npm run sync:developer-docs",
+		"package-docs": "node scripts/package-knowledge-pack.js && npm run sync:developer-docs && npm run sync:skills",
 		"sync:developer-docs": "node scripts/sync-developer-docs.js",
+		"sync:skills": "node scripts/sync-skills.js",
+		"validate:skills": "node scripts/validate-skills.js",
+		"update:assistant-files": "node scripts/update-assistant-files.js",
 		"sync-cli-version": "node scripts/sync-cli-version.js",
 		"publish-cli": "node scripts/publish-cli.js",
-		"prepublishOnly": "npm run build && npm run sync-cli-version",
+		"prepublishOnly": "npm run build && npm run sync-cli-version && npm run sync:skills && npm run validate:skills",
 		"postpublish": "npm run publish-cli"
 	},
 	"exports": {