@lenne.tech/cli 1.10.0 → 1.11.1

package/docs/VENDOR-MODE-WORKFLOW.md

@@ -0,0 +1,471 @@
+# Vendor-Mode Workflow — Step-by-Step
+
+Practical guide for converting a lenne.tech fullstack project from **npm mode** to **vendor mode**, updating it, and optionally rolling back.
+
+**In short:** In vendor mode the framework code (`@lenne.tech/nest-server`, `@lenne.tech/nuxt-extensions`) is copied directly into the project (`src/core/` and `app/core/`) instead of being installed via npm.
+
+> **Complete reference**: All commands and background information can be found in the [LT-ECOSYSTEM-GUIDE](./LT-ECOSYSTEM-GUIDE.md).
+
+---
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Part 1: Convert npm → vendor](#part-1-convert-npm--vendor)
+- [Part 2: Update in vendor mode](#part-2-update-in-vendor-mode)
+- [Part 3: Roll back vendor → npm](#part-3-roll-back-vendor--npm)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Prerequisites
+
+Before you start, make sure:
+
+| Check | Command |
+|-------|---------|
+| lt CLI installed | `lt --version` |
+| Claude Code with lt-dev plugin | `/lt-dev:plugin:check` |
+| Project is a fullstack monorepo | Directories `projects/api/` and `projects/app/` exist |
+| Working tree is clean | `git status` shows no uncommitted changes |
+| You are on a feature branch | `git checkout -b feature/vendor-mode` |
+
+---
+
+## Part 1: Convert npm → vendor
+
+### Step 1: Check status
+
+**Command:**
+```bash
+lt status
+```
+
+**What happens:** Shows the current framework mode for backend and frontend. You expect to see `npm (@lenne.tech/nest-server dependency)` and `npm (@lenne.tech/nuxt-extensions dependency)`.
+
+---
+
+### Step 2: Dry-run — show plan
+
+**Command (from monorepo root):**
+```bash
+lt fullstack convert-mode --to vendor --dry-run
+```
+
+**What happens:** The CLI scans `projects/api/` and `projects/app/`, detects the current modes, and shows **what would happen** without making any changes. Verify the output:
+- Both subprojects as `npm → vendor`
+- Upstream versions are auto-detected from the respective `package.json` files
+
+---
+
+### Step 3: Run the conversion
+
+**Command:**
+```bash
+lt fullstack convert-mode --to vendor --noConfirm
+```
+
+**What happens:**
+1. **Backend**: clones `@lenne.tech/nest-server` into `/tmp/`, copies `src/core/` + `src/index.ts` + `src/core.module.ts` + `src/test/` + `src/templates/` + `src/types/` + `LICENSE` into `projects/api/src/core/`, applies the flatten-fix (4 edge-case files), rewrites all consumer imports from `@lenne.tech/nest-server` to relative paths, merges upstream dependencies dynamically into `package.json`, converts `express` value-imports to type-imports (vendor compatibility), creates `src/core/VENDOR.md`, prepends a vendor-notice block to `CLAUDE.md`
+2. **Frontend**: clones `@lenne.tech/nuxt-extensions` into `/tmp/`, copies `src/module.ts` + `src/runtime/` into `projects/app/app/core/`, replaces `'@lenne.tech/nuxt-extensions'` in `nuxt.config.ts` with `'./app/core/module'`, rewrites the 4 explicit consumer imports, removes the npm dependency, creates `app/core/VENDOR.md`
+
+The temp directories in `/tmp/` are cleaned up automatically.
+
+---
+
+### Step 4: Reinstall dependencies
+
+**Command (from monorepo root):**
+```bash
+pnpm install
+```
+
+**What happens:** pnpm installs the newly merged dependencies (that transitively came from the framework) and removes `@lenne.tech/nest-server` and `@lenne.tech/nuxt-extensions` from `node_modules/`.
+
+---
+
+### Step 5: Validate backend
+
+**Commands:**
+```bash
+cd projects/api
+pnpm exec tsc --noEmit
+pnpm run lint
+pnpm test
+cd ..
+```
+
+**What happens:**
+- `tsc --noEmit`: TypeScript check over the entire backend code including the vendored `src/core/`. Expectation: no errors.
+- `pnpm run lint`: oxlint over src/ + tests/. Expectation: 0 errors.
+- `pnpm test`: vitest e2e suite. Expectation: all tests green (initial run may take ~10 min due to TypeScript transform of the vendored core).
+
+---
+
+### Step 6: Validate frontend
+
+**Commands:**
+```bash
+cd projects/app
+pnpm run lint
+pnpm run build
+cd ..
+```
+
+**What happens:**
+- `lint`: oxlint over app/. Expectation: 0 errors.
+- `build`: Nuxt build runs prepare → build → nitro output. Expectation: `✨ Build complete!`
+
+---
+
+### Step 7: Check status again
+
+**Command:**
+```bash
+lt status
+```
+
+**Expected output:**
+```
+Monorepo Subprojects:
+  Backend:  projects/api → vendor (src/core/, VENDOR.md)
+  Frontend: projects/app → vendor (app/core/, VENDOR.md)
+```
+
+---
+
+### Step 8: Commit changes
+
+**Commands:**
+```bash
+git add -A
+git commit -m "chore: convert fullstack to vendor mode
+
+- Backend: @lenne.tech/nest-server vendored into src/core/
+- Frontend: @lenne.tech/nuxt-extensions vendored into app/core/
+- Both VENDOR.md files track baseline + sync history"
+```
+
+**What happens:** The commit typically contains ~500 new files (vendored core) and modified consumer imports.
+
+---
+
+## Part 2: Update in vendor mode
+
+After the conversion you still need to keep your project in sync with upstream changes. In vendor mode this happens **curated** via Claude Code agents.
+
+### Workflow A: Comprehensive update (recommended)
+
+**Command (in Claude Code):**
+```
+/lt-dev:fullstack:update-all
+```
+
+**What happens:**
+1. **Phase 1**: Detects the modes of both subprojects (vendor in this case)
+2. **Phase 2**: Generates `UPDATE_PLAN.md` with version gaps and waits for your approval
+3. **Phase 3**: Backend sync via `nest-server-core-updater` agent (clone upstream, diff, human review, apply, reapply flatten-fix)
+4. **Phase 4**: Frontend sync via `nuxt-extensions-core-updater` agent (clone upstream, diff, human review, apply)
+5. **Phase 5**: Package maintenance via `npm-package-maintainer` (FULL MODE)
+6. **Phase 6**: `CLAUDE.md` sync from upstream starters
+7. **Phase 7**: Cross-validation (build, lint, tests for both subprojects)
+8. **Phase 8**: Final report
+
+---
+
+### Workflow B: Update backend only
+
+**Command:**
+```
+/lt-dev:backend:update-nest-server-core
+```
+
+**What happens:** Same as Phase 3 of Workflow A — syncs `src/core/` with upstream changes.
+
+---
+
+### Workflow C: Update frontend only
+
+**Command:**
+```
+/lt-dev:frontend:update-nuxt-extensions-core
+```
+
+**What happens:** Same as Phase 4 of Workflow A — syncs `app/core/` with upstream changes.
+
+---
+
+### Workflow D: Sync to a specific version
+
+**Command:**
+```
+/lt-dev:backend:update-nest-server-core --target 11.25.0
+```
+
+**What happens:** Instead of syncing to HEAD, a specific upstream version is pulled. Useful for stable major/minor releases.
+
+---
+
+### Freshness check
+
+**Command (available in both subprojects):**
+```bash
+cd projects/api  # or projects/app
+pnpm run check:vendor-freshness
+```
+
+**What happens:** Reads the baseline version from `VENDOR.md` and compares it with the current version on npm. Non-blocking warning if a newer version exists. Automatically executed by `pnpm run check`.
+
+---
+
+### After the update: validation
+
+**Command (from monorepo root):**
+```bash
+pnpm run check
+```
+
+**What happens:** Runs audit + format:check + lint + tests + build + server-start per subproject. Must pass green before you commit the update.
+
+---
+
+### Upstream contribution (optional)
+
+If you have made local patches in the vendored core that are **generally useful** (bugfix, new feature, type correction), you can prepare them as upstream PRs:
+
+**Backend patches:**
+```
+/lt-dev:backend:contribute-nest-server-core
+```
+
+**Frontend patches:**
+```
+/lt-dev:frontend:contribute-nuxt-extensions-core
+```
+
+**What happens:** The agent scans `git log` since the VENDOR.md baseline, filters out cosmetic commits, categorizes substantial commits as `upstream-candidate` or `project-specific`, cherry-picks the candidates onto a fresh upstream branch, generates a PR body draft, and shows you a summary. **The push is done manually by you after review.**
+
+---
+
+## Part 3: Roll back vendor → npm
+
+In case vendor mode doesn't work for your project or you want to go back to the npm dependency.
+
+### Step 1: Check local patches
+
+**Command:**
+```bash
+cat projects/api/src/core/VENDOR.md | grep -A 20 "## Local changes"
+cat projects/app/app/core/VENDOR.md | grep -A 20 "## Local changes"
+```
+
+**What happens:** Shows the "Local changes" table from both `VENDOR.md` files. **If substantial patches are listed there, they will be lost during the rollback!**
+
+---
+
+### Step 2: Contribute patches upstream (if any)
+
+**Recommendation**: Before rolling back, contribute the local patches:
+
+```
+/lt-dev:backend:contribute-nest-server-core
+/lt-dev:frontend:contribute-nuxt-extensions-core
+```
+
+**What happens:** See "Upstream contribution" above. After merging the upstream PRs the rollback can happen without data loss.
+
+---
+
+### Step 3: Dry-run — show plan
+
+**Command (from monorepo root):**
+```bash
+lt fullstack convert-mode --to npm --dry-run
+```
+
+**What happens:** Shows `vendor → npm` for both subprojects. The versions to install are read from the `VENDOR.md` baselines.
+
+---
+
+### Step 4: Run the rollback
+
+**Command:**
+```bash
+lt fullstack convert-mode --to npm --noConfirm
+```
+
+**What happens:**
+1. **Backend**:
+   - Reads the baseline version from `src/core/VENDOR.md`
+   - Warns about local patches in the "Local changes" table
+   - Rewrites all consumer imports from relative paths back to `@lenne.tech/nest-server`
+   - Deletes `src/core/`
+   - Restores `@lenne.tech/nest-server` in `package.json` (with baseline version)
+   - Restores `migrate:*` scripts to `node_modules/.bin/`
+   - Removes vendor artifacts: `bin/migrate.js`, `migrations-utils/ts-compiler.js`, `migration-guides/`
+   - Removes the vendor marker from `CLAUDE.md`
+2. **Frontend**:
+   - Reads the baseline version from `app/core/VENDOR.md`
+   - Rewrites the 4 explicit consumer imports back to `@lenne.tech/nuxt-extensions`
+   - Deletes `app/core/`
+   - Restores `@lenne.tech/nuxt-extensions` in `package.json`
+   - Rewrites `nuxt.config.ts`: `'./app/core/module'` → `'@lenne.tech/nuxt-extensions'`
+   - Removes the `check:vendor-freshness` script
+   - Removes the vendor marker from `CLAUDE.md`
+
+---
+
+### Step 5: Reinstall dependencies
+
+**Command:**
+```bash
+pnpm install
+```
+
+**What happens:** pnpm installs `@lenne.tech/nest-server` and `@lenne.tech/nuxt-extensions` freshly from the npm registry.
+
+---
+
+### Step 6: Validate
+
+**Commands:**
+```bash
+cd projects/api && pnpm exec tsc --noEmit && pnpm run lint && pnpm test && cd ..
+cd projects/app && pnpm run lint && pnpm run build && cd ..
+```
+
+**What happens:** Makes sure everything still works after the rollback. `tsc` in the backend verifies that the `@lenne.tech/nest-server` types from `node_modules/` are now found. The frontend build verifies that Nuxt loads the module as an npm dependency.
+
+---
+
+### Step 7: Check status again
+
+**Command:**
+```bash
+lt status
+```
+
+**Expected output:**
+```
+Monorepo Subprojects:
+  Backend:  projects/api → npm (@lenne.tech/nest-server dependency)
+  Frontend: projects/app → npm (@lenne.tech/nuxt-extensions dependency)
+```
+
+---
+
+### Step 8: Commit changes
+
+**Commands:**
+```bash
+git add -A
+git commit -m "chore: revert fullstack to npm mode
+
+- Backend: back to @lenne.tech/nest-server X.Y.Z npm dependency
+- Frontend: back to @lenne.tech/nuxt-extensions A.B.C npm dependency
+- Vendored cores (src/core/, app/core/) removed"
+```
+
+---
+
+## Troubleshooting
+
+### Problem: `tsc` fails with `new Error('msg', { cause })` error
+
+**Cause:** TypeScript target is too old (ES2020 or lower).
+
+**Fix:** In `projects/api/tsconfig.json` set the target to `"es2022"`:
+```json
+{
+  "compilerOptions": {
+    "target": "es2022"
+  }
+}
+```
+
+---
+
+### Problem: Vitest error `'express' does not provide an export named 'Response'`
+
+**Cause:** In vendor mode the TypeScript source of the core is evaluated directly by vitest. Value-imports of TypeScript type-only exports break.
+
+**Fix:** Should have been fixed automatically by the CLI. If not, update all affected files:
+```typescript
+// Before
+import { Request, Response } from 'express';
+
+// After
+import type { Request, Response } from 'express';
+```
+
+---
+
+### Problem: Conversion fails with "Destination path already exists"
+
+**Cause:** The project already has project-specific `bin/` or `migration-guides/` directories that collide with upstream contents.
+
+**Fix:** Back up the contents, delete the directories, run the conversion again, copy the contents back.
+
+```bash
+cp projects/api/bin/migrate.js /tmp/migrate-backup.js
+cp -r projects/api/migration-guides /tmp/migration-guides-backup
+rm -rf projects/api/bin projects/api/migration-guides
+lt fullstack convert-mode --to vendor --noConfirm
+# After conversion:
+mv /tmp/migration-guides-backup/MY-FILE.md projects/api/migration-guides/
+```
+
+---
+
+### Problem: Some consumer imports missing from the rewrite after conversion
+
+**Symptom:** `lt fullstack convert-mode` shows a warning like `X file(s) still contain '@lenne.tech/nest-server' imports`.
+
+**Fix:** Manually check the reported files and rewrite the imports to relative paths. The warning shows the exact paths.
+
+---
+
+### Problem: Tests fail under parallel load (flakiness)
+
+**Cause:** TypeScript source loading in vendor mode is slower than pre-compiled `dist/` — this exposes existing timing-sensitive test races.
+
+**Fix options:**
+- Make individual flaky tests robust (retry pattern, polling instead of `setTimeout`)
+- As a workaround, `retry: 3` is already active in `vitest-e2e.config.ts`
+- Last resort: `poolOptions.forks.singleFork: true` (makes tests sequential — ~4× slower)
+
+---
+
+### Problem: Upstream sync finds conflicts
+
+**Symptom:** `/lt-dev:backend:update-nest-server-core` shows conflicts between upstream changes and local patches.
+
+**Fix:** The agent pauses and presents the conflicts. You can:
+- `approve all` — take all upstream picks (local patches overwritten)
+- `approve clean` — only conflict-free picks
+- `reject <file>` — skip a specific file
+- `show <file>` — render the hunk
+- `done` — proceed with current selection
+
+---
+
+## Quick Reference
+
+| Action | Command |
+|--------|---------|
+| Check status | `lt status` |
+| Dry-run npm→vendor | `lt fullstack convert-mode --to vendor --dry-run` |
+| npm→vendor | `lt fullstack convert-mode --to vendor --noConfirm` |
+| Vendor update | `/lt-dev:fullstack:update-all` |
+| Backend-only update | `/lt-dev:backend:update-nest-server-core` |
+| Frontend-only update | `/lt-dev:frontend:update-nuxt-extensions-core` |
+| Freshness check | `pnpm run check:vendor-freshness` |
+| Full check | `pnpm run check` |
+| Upstream PR (backend) | `/lt-dev:backend:contribute-nest-server-core` |
+| Upstream PR (frontend) | `/lt-dev:frontend:contribute-nuxt-extensions-core` |
+| Dry-run vendor→npm | `lt fullstack convert-mode --to npm --dry-run` |
+| vendor→npm | `lt fullstack convert-mode --to npm --noConfirm` |
+
+---
+
+> **Further reading**: Architecture, concepts, and reference for all CLI and plugin functions in the [LT-ECOSYSTEM-GUIDE](./LT-ECOSYSTEM-GUIDE.md).

package/docs/commands.md

@@ -2,6 +2,12 @@
 
 This document provides a comprehensive reference for all `lt` CLI commands. For configuration file options, see [lt.config.md](./lt.config.md).
 
+## Related Documentation
+
+- **[LT-ECOSYSTEM-GUIDE](./LT-ECOSYSTEM-GUIDE.md)** — Complete reference for `lt` CLI **and** the `lt-dev` Claude-Code Plugin including architecture, vendor-mode workflows, agents, and skills
+- **[VENDOR-MODE-WORKFLOW](./VENDOR-MODE-WORKFLOW.md)** — Step-by-step guide for converting a project from npm mode to vendor mode, updating it, and optional rollback
+- **[lt.config.md](./lt.config.md)** — Configuration file reference
+
 ## Table of Contents
 
 - [CLI Commands](#cli-commands)
@@ -202,6 +208,67 @@ lt server test
 
 ---
 
+### `lt server convert-mode`
+
+Convert an existing API (NestJS) project between npm mode and vendor mode for `@lenne.tech/nest-server`.
+
+**Usage:**
+```bash
+lt server convert-mode --to <vendor|npm> [options]
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `--to <mode>` | Target mode: `vendor` or `npm` (required) |
+| `--upstream-branch <ref>` | Upstream branch/tag to vendor from (only with `--to vendor`) |
+| `--version <version>` | nest-server version to install (only with `--to npm`, default: from VENDOR.md baseline) |
+| `--dry-run` | Show the resolved plan without making any changes |
+| `--noConfirm` | Skip confirmation prompt |
+
+**Behavior:**
+
+- **npm → vendor:**
+  - Clones `@lenne.tech/nest-server` from GitHub at the specified tag (default: currently installed version)
+  - Copies `src/core/`, `src/index.ts`, `src/core.module.ts`, `src/test/`, `src/templates/`, `src/types/`, and `LICENSE` to `<api-root>/src/core/`
+  - Applies flatten-fix on `index.ts`, `core.module.ts`, `test.helper.ts`, `core-persistence-model.interface.ts`
+  - Rewrites all consumer imports from `'@lenne.tech/nest-server'` to relative paths
+  - Merges upstream dependencies dynamically into `package.json`
+  - Rewrites `migrate:*` scripts to use local `bin/migrate.js` with `ts-compiler.js` bootstrap
+  - Adds `check:vendor-freshness` script
+  - Creates `src/core/VENDOR.md` with baseline version + commit SHA
+  - Prepends a vendor-mode notice block to `CLAUDE.md`
+
+- **vendor → npm:**
+  - Extracts baseline version from `src/core/VENDOR.md` (warns if local patches exist)
+  - Rewrites consumer imports back to `@lenne.tech/nest-server`
+  - Deletes `src/core/`
+  - Restores `@lenne.tech/nest-server` dependency in `package.json`
+  - Restores `migrate:*` scripts to `node_modules/.bin/` paths
+  - Removes vendor artifacts (`bin/`, `migrations-utils/ts-compiler.js`, `migration-guides/`) and `CLAUDE.md` marker
+
+**Examples:**
+```bash
+# Convert existing npm project to vendor mode at a specific version
+cd projects/api
+lt server convert-mode --to vendor --upstream-branch 11.24.3 --noConfirm
+
+# Preview what the conversion would do
+lt server convert-mode --to vendor --dry-run
+
+# Convert vendored project back to npm with a specific version
+lt server convert-mode --to npm --version 11.24.3 --noConfirm
+```
+
+**Note:** nest-server tags have **no** `v` prefix — use e.g. `11.24.3`, not `v11.24.3`.
+
+For mode-aware update workflows after conversion, use:
+- `/lt-dev:backend:update-nest-server-core` (vendor mode)
+- `/lt-dev:backend:update-nest-server` (npm mode)
+- `/lt-dev:fullstack:update-all` (coordinated backend + frontend)
+
+---
+
 ## Git Commands
 
 All git commands support the `--noConfirm` flag and can be configured via `defaults.noConfirm` or `commands.git.noConfirm`.
@@ -462,6 +529,10 @@ lt fullstack init [options]
 | `--frontend-branch <branch>` | Branch of frontend starter to use (ng-base-starter or nuxt-base-starter) |
 | `--frontend-copy <path>` | Copy frontend from local template directory |
 | `--frontend-link <path>` | Symlink frontend to local template (fastest, changes affect original) |
+| `--framework-mode <mode>` | Backend framework consumption mode: `npm` (classic) or `vendor` (pilot, core copied to `src/core/`) |
+| `--framework-upstream-branch <ref>` | Upstream `nest-server` branch/tag to vendor from (only with `--framework-mode vendor`) |
+| `--frontend-framework-mode <mode>` | Frontend framework consumption mode: `npm` or `vendor` (nuxt-extensions copied to `app/core/`) |
+| `--dry-run` | Print the resolved plan without making any changes |
 | `--git` | Push initial commit to remote repository (git is always initialized) |
 | `--git-link <url>` | Git remote repository URL (required when `--git` is true) |
 | `--noConfirm` | Skip confirmation prompts |
@@ -485,6 +556,74 @@ Additionally, the API's `CLAUDE.md` is patched to reflect the selected API mode
 
 ---
 
+### `lt fullstack convert-mode`
+
+Convert **both** backend (`projects/api/`) and frontend (`projects/app/`) of a fullstack monorepo between npm mode and vendor mode in a single command. Auto-detects the subprojects, shows the plan for each side, and orchestrates the backend + frontend conversions sequentially.
+
+**Usage:**
+```bash
+lt fullstack convert-mode --to <vendor|npm> [options]
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `--to <mode>` | Target mode: `vendor` or `npm` (required) |
+| `--framework-upstream-branch <ref>` | Backend upstream branch/tag (only with `--to vendor`, e.g. `11.24.3`) |
+| `--frontend-framework-upstream-branch <ref>` | Frontend upstream branch/tag (only with `--to vendor`, e.g. `1.5.3`) |
+| `--framework-version <version>` | Backend nest-server version (only with `--to npm`, default: from `VENDOR.md` baseline) |
+| `--frontend-framework-version <version>` | Frontend nuxt-extensions version (only with `--to npm`, default: from `VENDOR.md` baseline) |
+| `--skip-backend` | Skip backend conversion (frontend only) |
+| `--skip-frontend` | Skip frontend conversion (backend only) |
+| `--dry-run` | Show the resolved plan without making any changes |
+| `--noConfirm` | Skip confirmation prompt |
+
+**Subproject Detection:**
+
+The command searches for subprojects in this order:
+- Backend: `projects/api/` → `packages/api/`
+- Frontend: `projects/app/` → `packages/app/`
+
+Subprojects that are already in the target mode or not found are gracefully skipped.
+
+**Behavior:**
+
+For each subproject that needs conversion:
+- **Backend**: delegates to the same pipeline as `lt server convert-mode`
+- **Frontend**: delegates to the same pipeline as `lt frontend convert-mode`
+- **Failure isolation**: If backend fails, frontend still runs (unless `--dry-run`). Final summary lists per-subproject status.
+
+**Examples:**
+```bash
+# Convert both subprojects to vendor mode at current versions (auto-detected)
+cd my-monorepo
+lt fullstack convert-mode --to vendor --noConfirm
+
+# Convert to vendor with explicit versions
+lt fullstack convert-mode --to vendor \
+  --framework-upstream-branch 11.24.3 \
+  --frontend-framework-upstream-branch 1.5.3 \
+  --noConfirm
+
+# Preview the plan without changes
+lt fullstack convert-mode --to vendor --dry-run
+
+# Convert back to npm (preserves local patches by warning before execution)
+lt fullstack convert-mode --to npm --noConfirm
+
+# Only convert backend (frontend stays as-is)
+lt fullstack convert-mode --to vendor --skip-frontend --noConfirm
+```
+
+**Note:** nest-server tags use **no** `v` prefix (e.g. `11.24.3`). nuxt-extensions tags also use **no** `v` prefix (e.g. `1.5.3`).
+
+For mode-aware update workflows after conversion, use:
+- `/lt-dev:fullstack:update-all` (comprehensive, mode-aware)
+- `/lt-dev:backend:update-nest-server-core` (backend vendor mode)
+- `/lt-dev:frontend:update-nuxt-extensions-core` (frontend vendor mode)
+
+---
+
 ## Deployment Commands
 
 ### `lt deployment create`
@@ -593,6 +732,63 @@ lt frontend nuxt --copy /path/to/nuxt-base-starter/nuxt-base-template
 
 ---
 
+### `lt frontend convert-mode`
+
+Convert an existing frontend (Nuxt) project between npm mode and vendor mode for `@lenne.tech/nuxt-extensions`.
+
+**Usage:**
+```bash
+lt frontend convert-mode --to <vendor|npm> [options]
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `--to <mode>` | Target mode: `vendor` or `npm` (required) |
+| `--upstream-branch <ref>` | Upstream branch/tag to vendor from (only with `--to vendor`) |
+| `--version <version>` | nuxt-extensions version to install (only with `--to npm`, default: from VENDOR.md baseline) |
+| `--dry-run` | Show the resolved plan without making any changes |
+| `--noConfirm` | Skip confirmation prompt |
+
+**Behavior:**
+
+- **npm → vendor:**
+  - Clones `@lenne.tech/nuxt-extensions` from GitHub at the specified tag (default: currently installed version)
+  - Copies `src/module.ts`, `src/index.ts`, `src/runtime/`, and `LICENSE` to `<app-root>/app/core/`
+  - Rewrites `nuxt.config.ts` module entry from `'@lenne.tech/nuxt-extensions'` to `'./app/core/module'`
+  - Rewrites explicit consumer imports in `app/**/*.{ts,vue}` and `tests/**/*.ts` to relative paths
+  - Removes `@lenne.tech/nuxt-extensions` from `package.json` dependencies
+  - Merges upstream runtime dependencies (e.g. `@nuxt/kit`)
+  - Adds `check:vendor-freshness` script
+  - Creates `app/core/VENDOR.md` with baseline version + commit SHA
+  - Prepends a vendor-mode notice block to `CLAUDE.md`
+
+- **vendor → npm:**
+  - Extracts baseline version from `app/core/VENDOR.md` (warns if local patches exist)
+  - Rewrites consumer imports back to `@lenne.tech/nuxt-extensions`
+  - Deletes `app/core/`
+  - Restores `@lenne.tech/nuxt-extensions` dependency in `package.json`
+  - Rewrites `nuxt.config.ts` module entry back
+  - Removes vendor scripts and `CLAUDE.md` marker
+
+**Examples:**
+```bash
+# Convert existing npm project to vendor mode at a specific version
+cd projects/app
+lt frontend convert-mode --to vendor --upstream-branch 1.5.3 --noConfirm
+
+# Convert vendored project back to npm with a specific version
+lt frontend convert-mode --to npm --version 1.5.3 --noConfirm
+```
+
+**Note:** nuxt-extensions tags have **no** `v` prefix — use e.g. `1.5.3`, not `v1.5.3`.
+
+For mode-aware update workflows after conversion, use:
+- `/lt-dev:frontend:update-nuxt-extensions-core` (vendor mode)
+- `/lt-dev:fullstack:update-all` (coordinated backend + frontend)
+
+---
+
 ## Config Commands
 
 ### `lt config init`