nuxt-extensions-core-vendoring

What this skill does

# Vendored nuxt-extensions core Knowledge Base

## Gotchas

- **Upstream tags have NO `v` prefix** — `@lenne.tech/nuxt-extensions` publishes tags like `7.19.0`, not `v7.19.0`. Using `v7.19.0` in git refs or changelog links produces 404s. This differs from `@lenne.tech/nest-server` which also drops the prefix but some tooling adds it back automatically.
- **`nuxt.config.ts` module registration is NOT auto-handled on sync** — When a new composable or module file is added upstream, the sync agent copies the file but does NOT register it in `nuxt.config.ts`. You must manually add the module reference after a sync, otherwise Nuxt does not expose the new functionality.
- **Auto-imports work for composables + components but NOT for types** — Files in `app/core/` are auto-imported by Nuxt for composables and components, but explicitly imported types (e.g. `import type { Foo } from '@lenne.tech/nuxt-extensions'`) need their paths rewritten to relative references after vendoring. This rewrite is not fully automated.
- **Local patches in `app/core/` are invisible to future syncs** — Same gotcha as nest-server-core-vendoring: the updater can't infer your intent. Document intentional local deviations in `app/core/LOCAL-PATCHES.md`.
- **1.7.0 sync brings the AI module** — The 1.7.0 baseline adds `src/runtime/composables/use-lt-ai*.ts`, `src/runtime/lib/ai.ts`, and `src/runtime/types/ai.ts` (~700 LoC). After sync, projects MUST add an `ltExtensions.ai: { enabled, basePath }` section to `nuxt.config.ts` — auto-imports do not work until the option is registered. Default option in upstream is `enabled: true`, so projects that never want AI should set `enabled: false` after the sync.
- **1.7.0 pre-release-only breaking renames** — Only relevant for projects that vendored a 1.7.0 PRE-release into `app/core/`. Rename map (apply via project-wide replace after sync): `useLtAiSnippets` → `useLtAiPrompts`, `LtAiPromptSnippet` → `LtAiPrompt`, `LtAiPromptSnippetInput` → `LtAiPromptInput`, `LtAiPromptTemplate` → `LtAiSlot`, `LtAiPromptTemplateInput` → `LtAiSlotInput`, `UseLtAiSnippetsReturn` → `UseLtAiPromptsReturn`. Additionally: the EXECUTION payload type for `useLtAi.prompt()` was renamed `LtAiPromptInput` → `LtAiPromptRunInput` (CRUD input keeps the conventional `LtAiPromptInput` name). Projects that synced a 1.6.x or earlier baseline are unaffected.

This skill provides **knowledge and resources** for lenne.tech projects that have
vendored the @lenne.tech/nuxt-extensions module into their source tree. For automated
execution, use the matching agents:

- `lt-dev:nuxt-extensions-core-updater` via `/lt-dev:frontend:update-nuxt-extensions-core` --
  pulls upstream changes into the vendored core, with AI-driven curation against
  local patches
- `lt-dev:nuxt-extensions-core-contributor` via `/lt-dev:frontend:contribute-nuxt-extensions-core` --
  identifies substantial local changes to the vendored core and prepares them as
  Upstream-Pull-Requests to the nuxt-extensions repository

## When This Skill Activates

- Discussing the vendored nuxt-extensions pattern
- Asking how to sync frontend core from upstream into a vendored project
- Asking how to port a local frontend fix back to the upstream repository
- Troubleshooting nuxt.config.ts module registration after vendoring
- Planning an upstream-sync with conflict resolution for the frontend core
- Explaining the difference to the classic npm-based update flow for nuxt-extensions

## Skill Boundaries

| User Intent                                                | Correct Skill                         |
| ---------------------------------------------------------- | ------------------------------------- |
| "Sync vendored frontend core from upstream 1.5.3"          | **THIS SKILL**                        |
| "Port this composable fix back to nuxt-extensions"         | **THIS SKILL**                        |
| "Update nuxt-extensions via npm"                           | developing-lt-frontend                |
| "Create a new Nuxt composable"                             | developing-lt-frontend                |
| "Fix a CVE via npm audit"                                  | maintaining-npm-packages              |
| "Sync vendored backend core from upstream"                 | nest-server-core-vendoring            |
| "Modify @lenne.tech/nuxt-extensions itself and test via pnpm link" | contributing-to-lt-framework   |

## Detecting a Vendored Frontend Project

A project is considered **vendored** if **all** of the following are true:

1. `app/core/VENDOR.md` exists (in the frontend subproject root, e.g. `projects/app/app/core/VENDOR.md`)
2. `package.json` does **not** list `@lenne.tech/nuxt-extensions` in
   `dependencies` or `devDependencies`
3. `app/core/` contains the nuxt-extensions source (composables, components, plugins, etc.)

A project is **npm-based** (classic) if:

- `@lenne.tech/nuxt-extensions` is a regular dependency in `package.json`
- There is no `VENDOR.md` under `app/core/`

The `fullstack-updater` (classic agent) detects this automatically and delegates
to `nuxt-extensions-core-updater` for vendored projects.

## Modification Policy (when to touch `app/core/`)

Vendoring copies the nuxt-extensions source into the project tree so Claude
Code can read it directly -- this is a **comprehension aid**, not an
invitation to fork. The policy:

1. **Change `app/core/` ONLY when the change is generally useful to all
   nuxt-extensions consumers.** Valid reasons:
   - Bugfixes that apply to every consumer
   - Framework enhancements with broad applicability (new composables,
     better defaults, SSR fixes)
   - Closing security vulnerabilities
   - Type/config compatibility fixes that every consumer would hit
2. **Every other change belongs in project code** (outside `app/core/`),
   via project-level composables, components, middleware, or plugin
   overrides. Project-specific business rules, customer branding, or
   proprietary integrations must never live in the vendored core.
3. **Generally-useful changes MUST be submitted as an upstream PR** to
   `github.com/lenneTech/nuxt-extensions`. Use
   `/lt-dev:frontend:contribute-nuxt-extensions-core` to prepare the PR.
   Do not let useful fixes rot in a single project's vendor tree -- they
   belong upstream so every consumer benefits and the local patch
   disappears on the next sync.
4. **When in doubt, ask before editing `app/core/`.** The contributor
   agent exists precisely to keep the vendor tree close to upstream.

The `nuxt-extensions-core-contributor` agent enforces this distinction by
categorizing every local commit as **upstream-candidate** (generic) vs.
**project-specific** (stays local) vs. **unclear** (asks the human).

## The Frontend Vendor Model (one-way curation)

The vendored frontend core lives as **first-class project code**. Flow is:

```
Upstream (github.com/lenneTech/nuxt-extensions)
    |
    | /lt-dev:frontend:update-nuxt-extensions-core  (curated, one-way)
    v
Project vendor (app/core/)
    |
    | /lt-dev:frontend:contribute-nuxt-extensions-core  (manual review, cherry-pick)
    v
Upstream PR (via normal GitHub review process)
```

**Local patches are expected.** Projects legitimately modify the vendored core
when business rules, integration adapters, or bugfixes are needed before upstream
ships them. Those patches persist through syncs.

**Changes are never auto-pushed.** The contributor agent prepares PR drafts --
a human reviews and submits them through normal GitHub workflow. No git-subtree
push, no automatic upstream replay.

## No Flatten-Fix Needed

Unlike the backend vendor model (nest-server), the nuxt-extensions source structure
is **already flat**. The upstream repository organizes its code directly in `src/`
without a nested `core/` subdirectory, so when vendored into `app/core/`, no
import-path rewriting is needed for internal files.

This is an explicit simplification compared to the backend vendoring pattern:
- **Backend (nest-se