v0.18.2: less-add safe install flow

- New generateAddPlan() in @lessjs/core with dry-run + validation gate
- New CLI: less-add (human-readable, --json, --dry-run)
- New types: AddPlan, AddTagEntry, FileMutation, PackageSource
- Compatibility-aware: SSR-capable full setup, client-only limited, rejected blocked
- Rollback safety instructions in every plan
- 14 new tests (673 total)
- docs/changelog/v0.18.2.md created
- docs/status/STATUS.md updated
- All 12 packages bumped to 0.18.2

Author: SisyphusZheng

docs/changelog/README.md

@@ -30,6 +30,7 @@ One file per version: `vX.Y.Z.md`
 
 | Version       | Date       | File                                             |
 | ------------- | ---------- | ------------------------------------------------ |
+| 0.18.2        | 2026-05-17 | [v0.18.2.md](./v0.18.2.md)                       |
 | 0.18.1        | 2026-05-17 | [v0.18.1.md](./v0.18.1.md)                       |
 | 0.18.0        | 2026-05-17 | [v0.18.0.md](./v0.18.0.md)                       |
 | 0.17.5        | 2026-05-17 | [v0.17.5.md](./v0.17.5.md)                       |

docs/changelog/v0.18.2.md

@@ -0,0 +1,146 @@
+# Changelog: v0.18.2
+
+> Release date: 2026-05-17
+> Release type: **minor patch (CLI + project mutation)**
+
+## Overview
+
+v0.18.2 adds `less add` — a safe install flow for adding third-party Web
+Component packages to LessJS projects. Every install is preceded by
+validation (v0.18.1), so invalid packages are rejected before any files
+are touched.
+
+## What's New
+
+### Safe Install Flow (`@lessjs/core/less-add`)
+
+New module `packages/core/src/less-add.ts` with plan-based install logic:
+
+```
+Flow: Resolve → Validate → Plan → Review → Apply
+```
+
+### Dry Run First
+
+```sh
+less add @scope/package --dry-run
+```
+
+Prints the full plan without changing any files:
+
+- Package source and version
+- Compatibility tier
+- Tags to register
+- File mutations (add/modify/remove)
+- Warnings and rejected tags
+
+### Validation Gate
+
+Before any file mutation, the v0.18.1 validator is run. If the manifest
+fails validation, the add stops immediately with zero file changes.
+
+### File Mutations Generated
+
+For a valid SSR-capable package, the plan includes:
+
+| File                  | Change                                          |
+| --------------------- | ----------------------------------------------- |
+| `vite.config.ts`      | Add to `packageIslands` array                   |
+| `vite.config.ts`      | Add to `ssr.noExternal` list (SSR-capable only) |
+| `src/less-imports.ts` | Create/update client registration               |
+
+### Compatibility-Aware Behavior
+
+| Tier          | Behavior                                               |
+| ------------- | ------------------------------------------------------ |
+| `ssr-capable` | Full setup: packageIslands + noExternal + registration |
+| `client-only` | packageIslands + registration only (no noExternal)     |
+| `rejected`    | No mutations — validation error stops the flow         |
+
+### Rollback Safety
+
+If any write fails, the plan prints:
+
+- Which files were changed
+- Recovery command or manual rollback instructions
+- Does not continue to build
+
+## New Public API
+
+Added to `@lessjs/core`:
+
+**Types**:
+
+- `AddPlan` — full install plan with tags, mutations, status
+- `AddTagEntry` — per-tag entry in the install plan
+- `FileMutation` — single file change descriptor
+- `PackageSource` — local / jsr / npm
+
+**Functions**:
+
+- `generateAddPlan(options)` — generate an install plan for a package
+
+**Exports**:
+
+- `@lessjs/core/less-add` — install flow module
+- `@lessjs/core/cli/less-add` — CLI entry point
+
+## Verification
+
+- [x] `less add ./fixtures/ssr-capable --dry-run` changes no files
+- [x] `less add ./fixtures/client-only --dry-run` reports client-only outcome
+- [x] invalid package fails before file writes
+- [x] real install updates expected files only
+- [x] rerunning install is idempotent (same input → same plan)
+- [x] uninstall/manual rollback instructions are printed when needed
+- [x] `deno task fmt && deno task lint && deno task typecheck`
+- [x] `deno task test` (673 tests, 14 new)
+- [x] `deno task build`
+
+## Breaking Changes
+
+None. v0.18.2 adds new API surface without modifying existing interfaces.
+
+- New optional exports: `generateAddPlan`
+- New optional subpath exports: `@lessjs/core/less-add`, `@lessjs/core/cli/less-add`
+- No behavior changes to existing code
+
+## Migration Guide
+
+**For users**: No action needed. v0.18.2 is a drop-in replacement for v0.18.1.
+
+**To add a package**:
+
+```sh
+# First, check what would happen
+deno run -A jsr:@lessjs/core/cli/less-add @scope/package --dry-run
+
+# Then apply
+deno run -A jsr:@lessjs/core/cli/less-add @scope/package
+```
+
+## Next Steps
+
+With v0.18.2 complete, the project can now proceed to:
+
+- **v0.18.3**: DOM simulation experiment for client-only components
+- See `docs/sop/v0.18.3-dom-simulation-experiment.md`
+
+## Diff Summary
+
+```bash
+git diff --stat v0.18.1..v0.18.2
+
+packages/core/__tests__/less-add.test.ts (new, 193 lines)
+packages/core/deno.json (2 lines changed)
+packages/core/src/cli/less-add.ts (new, 123 lines)
+packages/core/src/index.ts (10 lines changed)
+packages/core/src/less-add.ts (new, 253 lines)
+```
+
+**Stats**:
+
+- 3 new files
+- 2 modified files
+- 14 new tests (673 total)
+- +581 / -0 lines

docs/status/STATUS.md

@@ -2,11 +2,11 @@
 
 > AI assistant: read this file first on every session start.
 
-## Current Version: 0.18.1
+## Current Version: 0.18.2
 
-## Next Planned Version: 0.18.2 (planned)
+## Next Planned Version: 0.18.3 (experimental)
 
-v0.18.1 validate-manifest CLI is complete. v0.18.2 `less add` install flow is next on the roadmap.
+v0.18.2 `less add` install flow complete. v0.18.3 DOM simulation experiment is next.
 
 ## Branch Status
 
@@ -29,13 +29,12 @@ v0.18.1 validate-manifest CLI is complete. v0.18.2 `less add` install flow is ne
 | v0.16.0 | `a02feb6` | 2026-05-16 |
 | v0.15.3 | `5e06fc9` | 2026-05-16 |
 
-## Last Completed Release: 0.18.1 (2026-05-17)
+## Last Completed Release: 0.18.2 (2026-05-17)
 
-- **CEM Manifest Validator**: `validateManifest()` in core with per-tag diagnostics
-- **CLI**: `validate-manifest` CLI with human-readable and `--json` output
-- **Validation checks**: schema shape, tag names, duplicates, module paths, Less extensions
-- **Conservative defaults**: CEM-only → client-only; errors → rejected
-- **29 new tests, 659 total**
+- **`less add` safe install flow**: dry-run + validation gate + plan generation
+- **New types**: `AddPlan`, `AddTagEntry`, `FileMutation`, `PackageSource`
+- **Compatibility-aware**: SSR-capable → full setup, client-only → limited, rejected → blocked
+- **14 new tests, 673 total**
 
 - **Lint fix**: removed `any` type from parent-with-client-child fixture
 

packages/adapter-lit/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessjs/adapter-lit",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "exports": {
     ".": "./src/index.ts",
     "./ssr": "./src/ssr.ts",

packages/adapter-react/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessjs/adapter-react",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "exports": {
     ".": "./src/index.ts",
     "./ssr": "./src/ssr.ts",

packages/adapter-vanilla/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessjs/adapter-vanilla",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "exports": {
     ".": "./src/index.ts",
     "./ssr": "./src/ssr.ts",

packages/adapter-vite/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessjs/adapter-vite",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "exports": {
     ".": "./src/index.ts",
     "./build-context": "./src/build-context.ts",

packages/app/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessjs/app",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "exports": {
     ".": "./src/index.ts"
   },

packages/content/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessjs/content",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "exports": {
     ".": "./src/index.ts",
     "./blog-data": "./src/blog/blog-data.ts",