opt-editor Install
This is NOT the opt-editor you know. Read node_modules/@reopt-ai/opt-editor/dist/docs/ before writing code.
When to apply
Consumer project depends on @reopt-ai/opt-editor. Triggers: "install", "init", "setup", "upgrade", "update" — with or without an opt- / editor prefix.
Invocation
/opt-editor-install # Auto-branch (missing → init, installed → upgrade)
/opt-editor-install --with-ai # Init + AI streaming integration
/opt-editor-install 2.0.0 # Upgrade to a specific version
/opt-editor-install --dry-run # Analyze only
Step 1 — Pin agent rules into AGENTS.md / CLAUDE.md
Source: the module's own agent-rules file once it ships one (@reopt-ai/opt-editor does not, as of 2.0.0). Fallback: agent-rules.md bundled with this skill. Wrap content between:
<!-- BEGIN:reopt/opt-editor-agent-rules -->
…content from source…
<!-- END:reopt/opt-editor-agent-rules -->
Idempotent: replace only between markers.
Step 2 — Consumer-side setup (this skill owns; docs cannot)
Public npm registry — no token or scoped .npmrc entry is required. Inspect the project .npmrc and npm config get @reopt-ai:registry; if the scope still resolves to GitHub Packages, remove only the legacy project entry @reopt-ai:registry=https://npm.pkg.github.com. Preserve unrelated registry/auth settings, and ask before changing user/global npm config.
Prereqs — Node 20+, React 19+, bun or npm. AI integration uses optional peers ai >= 7 and zod >= 3; do not install them for a non-AI editor.
App wiring — properties of the consumer app:
import "@reopt-ai/opt-editor/styles.css" at the app root.- Catalog file (
catalog.ts or similar) — block-definition registry.
- AI endpoint (when
--with-ai): a Vercel AI SDK–compatible route.
2.0 upgrade gate — move runtime Zod schema values (patchOpSchema, patchOpsArraySchema, createEditorOperationSchema, catalog schema builders) from @reopt-ai/opt-editor/server to /schemas; type-only imports may stay on /server, and /ai-sdk imports are unchanged. Before loading persisted V1 JSON, migrate props → attrs and rich-text attrs.text → canonical content, with a backup and a data-level dry run. The README's bun run migrate:v1-to-v2 is a source-repo script and is not shipped in the npm tarball; do not invoke it as a consumer command.
Step 3 — Route to module docs
| Task signal |
Read |
| Start here — doc index |
dist/docs/index.md |
| Getting started / install / upgrade |
dist/docs/01-getting-started.md |
| API (components, hooks, store, serialization, types) |
dist/docs/02-api/ |
| AI streaming integration |
dist/docs/02-api/04-ai-stream.md, dist/docs/03-recipes/03-ai-streaming.md |
| 2.0 canonical V2 storage migration |
README.md § Input Contract (the one-shot source script itself is not published) |
| High-level AI ops / agent-mode tools (EditorOperation, OperationCompiler) |
dist/docs/03-recipes/08-editor-operations.md |
Diff-mode suggestion review (mode="diff") |
dist/docs/03-recipes/09-diff-review-integration.md |
| Recipes (basic, custom blocks, markdown, image, …) |
dist/docs/03-recipes/ |
| Troubleshooting |
dist/docs/05-troubleshooting.md |
Pipeline (auto-branch)
| # |
Step |
Init |
Upgrade |
| 1 |
Detect current state |
✓ |
✓ |
| 2 |
Public-registry preflight + legacy override cleanup |
✓ |
✓ |
| 3 |
Install / update package |
✓ |
✓ |
| 4 |
CSS import check |
✓ |
✓ |
| 5 |
Catalog generation |
✓ |
– |
| 6 |
Editor component generation |
✓ |
– |
| 7 |
Breaking-change edits |
– |
✓ |
| 8 |
Deprecated fixes (opt-in) |
– |
✓ |
| 9 |
2.0 import/data migration gate + summary |
– |
✓ |
Detailed procedure lives in module docs — start at dist/docs/index.md, then dist/docs/01-getting-started.md. Read before acting.
Safety
- Never upgrade without an impact scan (run
--dry-run first).
- Confirm before overwriting existing files.
- Apply breaking-change edits in logical groups — never bulk-apply.
- Do not finish until
tsc --noEmit passes.
- Always provide a rollback path.
Verify
npx tsc --noEmit passes, including server imports of runtime schemas from /schemas.- Editor mounts and
StaticRenderer renders a stored canonical V2 EditorSpec (rich text in content) without console warnings.
- An AI-enabled setup completes one streamed patch through the AI SDK v7 route.
1---2name: opt-editor-install3description: Install, upgrade, or migrate @reopt-ai/opt-editor in a consumer project. Auto-branches by current install state. Triggers on "opt-editor install", "opt-editor init", "opt-editor setup", "editor install", "editor init", "opt-editor upgrade", "opt-editor update", "editor upgrade", "editor update", "opt-editor 2 migration", "editor schema migration", "migrate EditorSpec".4---56# opt-editor Install78> This is NOT the opt-editor you know. Read `node_modules/@reopt-ai/opt-editor/dist/docs/` before writing code.910## When to apply1112Consumer project depends on `@reopt-ai/opt-editor`. Triggers: "install", "init", "setup", "upgrade", "update" — with or without an `opt-` / `editor` prefix.1314## Invocation1516```17/opt-editor-install # Auto-branch (missing → init, installed → upgrade)18/opt-editor-install --with-ai # Init + AI streaming integration19/opt-editor-install 2.0.0 # Upgrade to a specific version20/opt-editor-install --dry-run # Analyze only21```2223## Step 1 — Pin agent rules into AGENTS.md / CLAUDE.md2425Source: the module's own agent-rules file once it ships one (`@reopt-ai/opt-editor` does not, as of 2.0.0). Fallback: `agent-rules.md` bundled with this skill. Wrap content between:2627```28<!-- BEGIN:reopt/opt-editor-agent-rules -->29…content from source…30<!-- END:reopt/opt-editor-agent-rules -->31```3233**Idempotent:** replace only between markers.3435## Step 2 — Consumer-side setup (this skill owns; docs cannot)36371. **Public npm registry** — no token or scoped `.npmrc` entry is required. Inspect the project `.npmrc` and `npm config get @reopt-ai:registry`; if the scope still resolves to GitHub Packages, remove only the legacy project entry `@reopt-ai:registry=https://npm.pkg.github.com`. Preserve unrelated registry/auth settings, and ask before changing user/global npm config.38392. **Prereqs** — Node 20+, React 19+, bun or npm. AI integration uses optional peers `ai >= 7` and `zod >= 3`; do not install them for a non-AI editor.40413. **App wiring** — properties of the consumer app:42 - `import "@reopt-ai/opt-editor/styles.css"` at the app root.43 - Catalog file (`catalog.ts` or similar) — block-definition registry.44 - AI endpoint (when `--with-ai`): a Vercel AI SDK–compatible route.45464. **2.0 upgrade gate** — move runtime Zod schema values (`patchOpSchema`, `patchOpsArraySchema`, `createEditorOperationSchema`, catalog schema builders) from `@reopt-ai/opt-editor/server` to `/schemas`; type-only imports may stay on `/server`, and `/ai-sdk` imports are unchanged. Before loading persisted V1 JSON, migrate `props` → `attrs` and rich-text `attrs.text` → canonical `content`, with a backup and a data-level dry run. The README's `bun run migrate:v1-to-v2` is a source-repo script and is not shipped in the npm tarball; do not invoke it as a consumer command.4748## Step 3 — Route to module docs4950| Task signal | Read |51|---|---|52| Start here — doc index | `dist/docs/index.md` |53| Getting started / install / upgrade | `dist/docs/01-getting-started.md` |54| API (components, hooks, store, serialization, types) | `dist/docs/02-api/` |55| AI streaming integration | `dist/docs/02-api/04-ai-stream.md`, `dist/docs/03-recipes/03-ai-streaming.md` |56| 2.0 canonical V2 storage migration | `README.md` § Input Contract (the one-shot source script itself is not published) |57| High-level AI ops / agent-mode tools (EditorOperation, OperationCompiler) | `dist/docs/03-recipes/08-editor-operations.md` |58| Diff-mode suggestion review (`mode="diff"`) | `dist/docs/03-recipes/09-diff-review-integration.md` |59| Recipes (basic, custom blocks, markdown, image, …) | `dist/docs/03-recipes/` |60| Troubleshooting | `dist/docs/05-troubleshooting.md` |6162## Pipeline (auto-branch)6364| # | Step | Init | Upgrade |65|---|---|---|---|66| 1 | Detect current state | ✓ | ✓ |67| 2 | Public-registry preflight + legacy override cleanup | ✓ | ✓ |68| 3 | Install / update package | ✓ | ✓ |69| 4 | CSS import check | ✓ | ✓ |70| 5 | Catalog generation | ✓ | – |71| 6 | Editor component generation | ✓ | – |72| 7 | Breaking-change edits | – | ✓ |73| 8 | Deprecated fixes (opt-in) | – | ✓ |74| 9 | 2.0 import/data migration gate + summary | – | ✓ |7576Detailed procedure lives in module docs — start at `dist/docs/index.md`, then `dist/docs/01-getting-started.md`. Read before acting.7778## Safety7980- Never upgrade without an impact scan (run `--dry-run` first).81- Confirm before overwriting existing files.82- Apply breaking-change edits in logical groups — never bulk-apply.83- Do not finish until `tsc --noEmit` passes.84- Always provide a rollback path.8586## Verify87881. `npx tsc --noEmit` passes, including server imports of runtime schemas from `/schemas`.892. Editor mounts and `StaticRenderer` renders a stored canonical V2 `EditorSpec` (rich text in `content`) without console warnings.903. An AI-enabled setup completes one streamed patch through the AI SDK v7 route.
reopt-ai