@execuro-sw-ecosystem/sw-ecosystem-agentic-harness 0.1.7 → 0.1.8

package/CHANGELOG.md

@@ -7,6 +7,58 @@ release.
 
 ## [Unreleased]
 
+## [0.1.8] - 2026-09-19
+
+### Changed
+
+- **The lock file moved to `var/sw-ai-sdk/harness.lock.json`, and the
+  `.gitignore` line is gone with it.** A Shopware project ignores the whole of
+  `var/` through the `shopware/core` Flex recipe (`/var/*`, with a single
+  `!/var/.htaccess` negation) and already keeps its machine-local state there
+  — `var/cache`, `var/log` — so the installer no longer creates a directory in
+  the repository root and no longer writes to `.gitignore` at all. A root with
+  no `var/` (`--scope user` under $HOME, or a checkout that is not a Shopware
+  project) keeps `.sw-ai-sdk/` and its managed line, unchanged. Nothing here
+  reads a path outside the install root, on any platform.
+  **Migration is automatic and lossless:** a lock still at the old path is
+  read, rewritten to the new one, and the old file, its directory and the
+  managed `.gitignore` block are removed. Declined rules, recorded agents and
+  file hashes all survive, so the first run after upgrading reinstalls nothing
+  — it reports `migrated[]` in `--json` and one line in the human summary.
+  `lock_file` in every result body now carries the resolved path; anything
+  that hard-coded `.sw-ai-sdk/` should read that key instead.
+
+### Removed
+
+- **BREAKING: the "extra component" mechanism is gone.** The CLI no longer
+  detects, installs, updates or removes the two optional visual editors
+  (Specs Editor, Tender Discovery Tool); each package installs its own skill,
+  orchestrated by the `sw-setup` skill. Removed with it: the
+  `extra_components[]` key from `status --json`, the `--no-extra-components`
+  flag on `install`/`plan`/`apply`, the `skipped` field from `plan`'s and
+  `apply`'s `summary` (nothing else could produce that state), the
+  `skill-copy` action kind, and the "Optional extra components" section of
+  `guide`. Anything reading `extra_components[]` or counting `summary.skipped`
+  must stop.
+  **Why:** the mechanism had never once worked. It spawned `npx --no-install
+  <pkg>@<pin> install-skill --print` and required stdout to begin with `---`,
+  but both editors document a `source:`/`next_step:` preamble before the skill
+  document, so the check could never pass and neither skill was ever installed.
+  `--no-install` also suppresses installing but not resolving, so every
+  `status`, `plan` and `apply` issued a real request to the npm registry —
+  `status` was never offline-safe, contrary to what the module claimed.
+- The two editors are now invoked as `@latest` everywhere, including in the
+  `allowed-tools` permission grants of `sw-design-requirements`,
+  `sw-design-solution` and `sw-discover-tender`, which still named an exact
+  version and would therefore have denied the calls. The `@latest` check now
+  guards `allowed-tools` lines as well as prose.
+
+### Added
+
+- `status --json` reports `skills_dir` per agent — the directory that agent
+  actually reads skills from, and the `--target` `sw-setup` hands to an
+  editor package's own `install-skill`/`uninstall-skill`.
+
 ## [0.1.7] - 2026-09-19
 
 ### Changed

package/README.md

@@ -43,16 +43,20 @@ identity, not an npm package name — and can be run standalone in any stdio MCP
 client without this harness.
 
 The two editors are **optional add-ons**, and each ships its own skill inside
-its package rather than here. `sw-setup` offers to install them; a host that
-declines is fully set up without them, and `--editor` on `sw-design-requirements`,
-`sw-design-solution` or `sw-discover-tender` then stops with one line saying so.
+its package rather than here. They are not this CLI's business at all: it
+neither detects nor installs them. `sw-setup` owns their whole lifecycle —
+it offers them, and installs, updates and removes each one with that
+package's own `install-skill`/`uninstall-skill --target <skills dir>`. A
+project that declines is fully set up without them, and `--editor` on
+`sw-design-requirements`, `sw-design-solution` or `sw-discover-tender` then
+stops with one line saying so.
 
 ## Commands
 
 | Command | What it does |
 | --- | --- |
 | `install` | installs into the resolved coding agent(s) (see Flags below); the same as `apply --yes` |
-| `status` | read-only; what is installed, what drifted, which optional extra components are present |
+| `status` | read-only; what is installed, what drifted, and each agent's `skills_dir` |
 | `plan` | the exact changes, written as a diff; writes nothing |
 | `apply --yes` | performs them |
 | `uninstall --yes` | removes what the lock file records |
@@ -61,8 +65,7 @@ declines is fully set up without them, and `--editor` on `sw-design-requirements
 Flags: `--agent claude-code|codex|copilot|cursor` (repeatable), `--scope
 project|user` (default `project`), `--root <path>` (default the current
 directory), `--yes` (required by `apply` and `uninstall` — `install` implies
-it), `--no-extra-components` (skip detection of the optional editor
-packages), `--json` and `--verbose` (see Output below).
+it), `--json` and `--verbose` (see Output below).
 
 `install`/`apply` resolve which coding agent(s) to write into, in order:
 `--agent` if given; else the agents a lock file already records (a re-run
@@ -118,6 +121,17 @@ unless you ask.
 `AGENTS.md` gets a managed block too — Codex, Copilot and Cursor read it, and
 Codex never reads `CLAUDE.md`.
 
+The installer's own state — the lock file recording what it wrote — goes to
+`var/sw-ai-sdk/harness.lock.json`. A Shopware project already ignores the whole
+of `var/` through the `shopware/core` Flex recipe (`/var/*`) and already keeps
+its machine-local state there, so the repository root stays clean and **no
+`.gitignore` line is written at all**. A root with no `var/` — `--scope user`
+under your home directory, or a checkout that is not a Shopware project —
+falls back to `.sw-ai-sdk/` and gets the managed `.gitignore` line as before.
+An install recorded at the old path is moved on the next `install`, which also
+takes back the `.gitignore` line it no longer needs; nothing is reinstalled and
+no declined rule is forgotten.
+
 ### What it will not do
 
 - **It never overwrites a file it did not install.** A file already at one of
@@ -137,7 +151,7 @@ Undo everything with:
 npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest uninstall --yes
 ```
 
-It removes exactly what the lock file at `.sw-ai-sdk/harness.lock.json` records,
+It removes exactly what the lock file at `var/sw-ai-sdk/harness.lock.json` records,
 keeps anything you hand-edited, and tells you what it kept.
 
 ### From a skill
@@ -160,16 +174,16 @@ Three things update on different schedules.
 | --- | --- |
 | This package — skills, sub-agents, permission rules, MCP registrations | `npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest install` |
 | The MCP servers (`ShopwareDevKnowledgeBase`, `playwright`) | By themselves. They are registered as `@latest`, so your agent fetches the newest build the next time it starts one. Nothing to run. |
-| Specs Editor, Tender Discovery Tool | You update them. Each has its own line — see below. |
+| Specs Editor, Tender Discovery Tool | `sw-setup` does, by re-running each package's own `install-skill` at `@latest` — see below. |
 
 ### The optional editors
 
-Install or update each at the exact version this release pins — the CLI
-probes for that version and skips the skill if it finds another:
+They are installed, updated and removed by the `sw-setup` skill, not by this
+CLI, and there is no version to match against this package:
 
 ```bash
-npm i -D @execuro-sw-ecosystem/sw-specs-editor@0.1.0
-npm i -D @execuro-sw-ecosystem/sw-tender-discovery-tool@0.1.0
+npx -y @execuro-sw-ecosystem/sw-specs-editor@latest install-skill --target <skills dir>
+npx -y @execuro-sw-ecosystem/sw-tender-discovery-tool@latest install-skill --target <skills dir>
 ```
 
 - `sw-specs-editor` backs the `--editor` flag on `sw-design-requirements` and
@@ -177,9 +191,11 @@ npm i -D @execuro-sw-ecosystem/sw-tender-discovery-tool@0.1.0
 - `sw-tender-discovery-tool` backs the `--editor` flag and the `.xlsx` import
   on `sw-discover-tender`.
 
-Re-run `install` afterwards so the new skill lands in each host. `status`'s
-`extra_components[]` array reports the pinned `version` and the exact `install`
-command for whichever one is missing (`status --json`).
+`<skills dir>` is the `skills_dir` this CLI reports for that agent in
+`status --json`. Re-running the same line is the update — `@latest` plus the
+editor's own "already current" path makes it idempotent — and
+`uninstall-skill` with the same `--target` removes it. Nothing needs to be
+re-run here afterwards.
 
 Re-running `install` is safe at any time: it rewrites only what it owns,
 leaves anything you hand-edited alone (reported as drift), and records the new
@@ -192,8 +208,8 @@ in this project's `node_modules`, so you would silently keep running the
 version you first installed.
 
 To look before you change anything: `... @latest status` reports
-`installed_version`, any drift, and which extra components are present. It
-writes nothing.
+`installed_version`, any drift, and each agent's `skills_dir`. It writes
+nothing.
 
 ## Prerequisites
 

package/SECURITY.md

@@ -41,7 +41,7 @@ scripts** on install, which removes a large part of the usual npm attack
 surface.
 
 Out of scope: vulnerabilities in the coding agents themselves, in the
-separately published extra components (they have their own repositories
+separately published visual editors (they have their own repositories
 and their own reporting), or in a third-party MCP server this package merely
 registers, such as Playwright's (report those upstream).
 

package/bin/cli.mjs

@@ -28,10 +28,10 @@ const COMMANDS = {
 
 const USAGE = `usage: sw-ecosystem-agentic-harness <command> [options]
 
-  install    [--agent <a>] [--scope project|user] [--root <path>] [--no-extra-components]
+  install    [--agent <a>] [--scope project|user] [--root <path>]
   status     [--agent <a>] [--scope project|user] [--root <path>]
-  plan       [--agent <a>] [--scope project|user] [--root <path>] [--no-extra-components]
-  apply      --yes [--agent <a>] [--scope project|user] [--root <path>] [--no-extra-components]
+  plan       [--agent <a>] [--scope project|user] [--root <path>]
+  apply      --yes [--agent <a>] [--scope project|user] [--root <path>]
   uninstall  --yes [--agent <a>] [--scope project|user] [--root <path>]
   guide      print the install protocol
 
@@ -49,8 +49,10 @@ const USAGE = `usage: sw-ecosystem-agentic-harness <command> [options]
   --scope defaults to project: nothing is written under your home directory
   unless you ask for it. --root defaults to the current directory.
 
-  --no-extra-components skips the two optional extra-component skills (Specs
-  Editor, Tender Discovery Tool) even when the package is present locally.
+  The two optional visual editors (Specs Editor, Tender Discovery Tool) are
+  not this CLI's business: each ships its own skill inside its own npm
+  package, and the sw-setup skill offers, installs, updates and removes
+  them.
 
   --json      print the result object instead of the human summary
   --verbose   include the per-file detail --json carries

package/lib/actions.mjs

@@ -20,13 +20,11 @@ import {
 import { PKG_ROOT } from './content.mjs';
 import { isDeclined } from './lock.mjs';
 import { readFileSync } from 'node:fs';
-import { EXTRA_COMPONENTS, probe } from './extra-components.mjs';
 
 /** Preview one action against the filesystem. Reads only. */
 export function preview(action, ctx) {
   switch (action.kind) {
     case 'file-copy': return previewFile(action, ctx);
-    case 'skill-copy': return previewSkill(action, ctx);
     case 'json-merge': return previewJson(action, ctx);
     case 'toml-fence':
     case 'text-fence': return previewFence(action, ctx);
@@ -42,8 +40,7 @@ function previewFile(action, ctx) {
   return previewBytes(action, ctx, shipped);
 }
 
-/** The adopt/conflict/drift/update ladder, shared by `file-copy` and, with a
- * probed body instead of a shipped one, `skill-copy`. */
+/** The adopt/conflict/drift/update ladder every byte-for-byte target walks. */
 function previewBytes(action, ctx, bytes) {
   const hash = sha256(bytes);
   const target = abs(ctx.root, action.target);
@@ -74,35 +71,6 @@ function previewBytes(action, ctx, bytes) {
     detail: 'shipped content changed' };
 }
 
-// ------------------------------------------------------------ skill-copy
-
-/** Strip the probed body (a Buffer) before it lands anywhere near the
- * action, which `commands.mjs` serialises straight to stdout. */
-function stripProbeBody({ body, ...rest }) {
-  return rest;
-}
-
-function previewSkill(action, ctx) {
-  const component = EXTRA_COMPONENTS.find((c) => c.id === action.component);
-  const probed = probe(component, { platform: ctx.platform });
-  const probeSummary = stripProbeBody(probed);
-
-  if (!probed.available) {
-    const remedy = probed.state === 'absent'
-      ? `npm i -D ${probed.spec}`
-      : 'check that npx works — probing needs network-free npx --no-install';
-    return {
-      ...action, state: 'skipped', available: false,
-      probe: probeSummary, reason: probed.reason, remedy,
-    };
-  }
-
-  return {
-    ...previewBytes(action, ctx, probed.body),
-    available: true, probe: probeSummary, body: probed.body,
-  };
-}
-
 // ------------------------------------------------------------- json-merge
 
 function previewJson(action, ctx) {
@@ -275,18 +243,6 @@ export function execute(action, ctx) {
       return { kind: 'file-copy', host: action.host, target: action.target, source: action.source,
         hash: action.hash, bytes: action.bytes, created_file: action.created_file !== false, dirs };
     }
-    case 'skill-copy': {
-      // Collapses to a `file-copy` lock entry on purpose: `lock.record`,
-      // `lock.entries`, `revert` and `rebuild` need no extra-component-specific
-      // case, and `uninstall` needs no probe. `source` is provenance only —
-      // `revert` never reads it.
-      ensureDir(dirname(target));
-      writeAtomic(target, action.body);
-      const dirs = ancestorDirs(ctx.root, action.target);
-      return { kind: 'file-copy', host: action.host, target: action.target,
-        source: `npm:${action.package}#install-skill --print`,
-        hash: action.hash, bytes: action.bytes, created_file: action.created_file !== false, dirs };
-    }
     case 'json-merge': {
       // Recompute from what is on disk right now rather than writing the
       // snapshot `preview` took. Several actions can target one file — the two

package/lib/commands.mjs

@@ -8,13 +8,14 @@ import { homedir } from 'node:os';
 import { resolve } from 'node:path';
 import * as out from './out.mjs';
 import {
-  CONTENT_VERSION, LOCK_FILE, PKG_NAME, PKG_VERSION, agents, skills,
+  CONTENT_VERSION, LOCK_DIR as LOCK_DIR_LEGACY, PKG_NAME, PKG_VERSION, agents,
+  lockDir, lockFile, lockNeedsGitignore, skills,
 } from './content.mjs';
 import { exists, isWritable, abs } from './fsx.mjs';
-import { AGENTS, buildPlan, detectAll, installedCounts } from './hosts.mjs';
+import { AGENTS, buildPlan, detectAll, installedCounts, skillsDir } from './hosts.mjs';
 import * as lockfile from './lock.mjs';
 import { dedupe, execute, isWritableState, preview, pruneDirs, revert } from './actions.mjs';
-import { probeAll } from './extra-components.mjs';
+import { removeDirIfEmpty, removeFile } from './fsx.mjs';
 import { askAgents } from './prompt.mjs';
 import { RESTART } from './render.mjs';
 
@@ -31,14 +32,12 @@ export function buildContext(argv, command) {
   let root = process.cwd();
   let yes = false;
   let projectWiki;
-  let extraComponents = true;
   let asJson = false;
   let verbose = false;
 
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--yes' || arg === '-y') { yes = true; continue; }
-    if (arg === '--no-extra-components') { extraComponents = false; continue; }
     if (arg === '--json') { asJson = true; continue; }
     if (arg === '--verbose') { verbose = true; continue; }
     if (arg === '--agent') {
@@ -73,7 +72,7 @@ export function buildContext(argv, command) {
   if (!exists(root)) throw new UsageError(`--root does not exist: ${root}`, [`${RUN} ${command} --root .`]);
 
   return {
-    root, scope, yes, projectWiki, extraComponents, json: asJson, verbose,
+    root, scope, yes, projectWiki, json: asJson, verbose,
     // Empty means "nothing chosen yet" — resolveAgents() applies the
     // per-command fallback once the lock (and, for apply/install, a TTY)
     // is available to consult.
@@ -152,18 +151,11 @@ function previewAll(ctx) {
 }
 
 function summarise(actions) {
-  const s = { create: 0, update: 0, unchanged: 0, drift: 0, conflict: 0, manual: 0, skipped: 0 };
+  const s = { create: 0, update: 0, unchanged: 0, drift: 0, conflict: 0, manual: 0 };
   for (const a of actions) if (a.state in s) s[a.state] += 1;
   return s;
 }
 
-/** The `npm i -D <spec>` line(s) for every skipped skill-copy action. */
-function skippedInstalls(actions) {
-  return [...new Set(
-    actions.filter((a) => a.state === 'skipped' && a.remedy?.startsWith('npm i -D')).map((a) => a.remedy),
-  )];
-}
-
 /** Strip the fields that are machinery, not result. */
 function publicAction(a) {
   const { doc, fmt, body, value, conflict, newly_declined: nd, absolute, ...rest } = a;
@@ -202,6 +194,7 @@ export async function status(argv) {
     }
     return {
       id: d.id, detected: d.detected, marker: d.marker, writable: d.writable,
+      skills_dir: skillsDir(d.id, ctx),
       installed: installedCounts(d.id, ctx), state, notes: d.notes,
     };
   });
@@ -217,24 +210,9 @@ export async function status(argv) {
   const worst = ['conflict', 'drift', 'not-installed', 'ok', 'absent']
     .find((s) => agentStates.some((a) => a.state === s)) ?? 'absent';
 
-  const extraComponents = ctx.extraComponents === false ? [] : probeAll({ platform: ctx.platform }).map((p) => ({
-    id: p.id, package: p.pkg, version: p.version, label: p.label,
-    available: p.available, probe: p.state, reason: p.reason ?? null,
-    installed_for: Object.entries(lock?.files ?? {})
-      .filter(([target]) => target.endsWith(`/skills/${p.id}/SKILL.md`))
-      .map(([, v]) => v.host),
-    install: p.available ? null : `npm i -D ${p.spec}`,
-  }));
-
   let next = pending
     ? `Run \`${RUN} plan\` to see the ${pending} change(s) needed, then \`${RUN} apply --yes\`.`
     : `Nothing to do — the harness is installed and up to date. Run \`${RUN} plan\` any time to re-check.`;
-  if (ctx.extraComponents !== false) {
-    const unavailable = extraComponents.filter((c) => !c.available);
-    if (unavailable.length) {
-      next += ` ${unavailable.length} optional extra component(s) are not on this machine — install with ${unavailable.map((c) => `\`${c.install}\``).join(', ')} to enable their skills.`;
-    }
-  }
 
   return out.ok('status', head(ctx, {
     installed_version: lock?.version ?? null,
@@ -242,7 +220,7 @@ export async function status(argv) {
     next_step: next,
     help: [`${RUN} plan`, `${RUN} apply --yes`, `${RUN} guide`],
     inventory: { skills: skills().length, agents: agents().length },
-    agents: agentStates, extra_components: extraComponents, drift,
+    agents: agentStates, drift,
     declined: lock?.declined ?? [],
     manual: lock?.manual ?? [],
     errors,
@@ -275,10 +253,6 @@ export async function plan(argv) {
         ? ` The ${summary.conflict} conflict(s) and ${summary.manual} manual step(s) will be reported again and left to you.`
         : '')
     : `Nothing to do — every target is already up to date.`;
-  const installs = skippedInstalls(actions);
-  if (installs.length) {
-    next += ` ${summary.skipped} action(s) skipped — run ${installs.map((i) => `\`${i}\``).join(', ')} to enable them.`;
-  }
 
   return out.ok('plan', head(ctx, {
     summary, next_step: next,
@@ -311,13 +285,35 @@ export async function apply(argv, label = 'apply') {
 
   // An apply we cannot record is an apply we cannot undo. Refuse up front
   // rather than leave the user with files and no way back.
-  if (!isWritable(abs(ctx.root, LOCK_FILE))) {
-    return out.failure(label, `cannot write the lock file at ${LOCK_FILE}`, {
+  if (!isWritable(abs(ctx.root, lockFile(ctx.root)))) {
+    return out.failure(label, `cannot write the lock file at ${lockFile(ctx.root)}`, {
       next_step: `Make ${ctx.root} writable, then re-run \`${RUN} apply --yes\`.`,
       help: [`${RUN} status`],
     });
   }
 
+  // Migration: a lock that used to live in the repository root carried a
+  // managed `.gitignore` line. Under `var/` the recipe ignores it already, so
+  // that line is ours to take back rather than leave behind as litter.
+  const staleIgnore = !lockNeedsGitignore(ctx.root)
+    && (lock.fences ?? []).find((f) => f.file === '.gitignore' && f.block === 'lock');
+  const migrated = [];
+  if (staleIgnore) {
+    try {
+      const result = revert({ kind: 'text-fence', target: '.gitignore', ...staleIgnore }, ctx);
+      if (result.state !== 'kept') {
+        lock = { ...lock, fences: lock.fences.filter((f) => f !== staleIgnore) };
+        migrated.push({
+          target: '.gitignore',
+          detail: `removed the managed \`${LOCK_DIR_LEGACY}/\` line — the lock now lives in ${lockDir(ctx.root)}/, which this project already ignores`,
+        });
+      }
+    } catch {
+      // Cosmetic. An apply that installed everything must not fail over a
+      // line we were trying to tidy away.
+    }
+  }
+
   const { actions, errors } = previewAll(ctx);
   const results = [];
   const perAgent = new Map(ctx.agents.map((a) => [a, { id: a, created: 0, updated: 0, unchanged: 0, failed: 0 }]));
@@ -371,7 +367,6 @@ export async function apply(argv, label = 'apply') {
     conflict: results.filter((r) => r.state === 'conflict').length,
     drift: results.filter((r) => r.state === 'drift').length,
     manual: manual.length,
-    skipped: results.filter((r) => r.state === 'skipped').length,
     failed: results.filter((r) => r.state === 'failed').length,
   };
 
@@ -382,14 +377,11 @@ export async function apply(argv, label = 'apply') {
     ? `${summary.failed} change(s) failed — see \`errors\`. Fix those, then re-run \`${RUN} apply --yes\`.`
     : `Restart the coding agents listed in \`help\` so they pick up the new skills, sub-agents and MCP servers.`
       + (manual.length ? ` Then finish the ${manual.length} manual step(s) in \`manual\`.` : '');
-  const installs = skippedInstalls(results);
-  if (installs.length) {
-    next += ` ${summary.skipped} action(s) skipped — run ${installs.map((i) => `\`${i}\``).join(', ')} to enable them.`;
-  }
 
   const body = head(ctx, {
-    summary, lock_file: LOCK_FILE, next_step: next, help,
+    summary, lock_file: lockFile(ctx.root), next_step: next, help,
     agents: [...perAgent.values()], actions: results, manual, errors,
+    ...(migrated.length ? { migrated } : {}),
   });
   return summary.failed ? out.failure(label, `${summary.failed} change(s) failed`, body) : out.ok(label, body);
 }
@@ -423,7 +415,7 @@ export async function uninstall(argv) {
     // someone else's files, so it does nothing and says so.
     return out.ok('uninstall', head(ctx, {
       summary: { removed: 0, reverted: 0, kept: 0, missing: 0, failed: 0 },
-      next_step: `Nothing to remove — no ${LOCK_FILE} was found, so this repository has no recorded install.`,
+      next_step: `Nothing to remove — no ${lockFile(ctx.root)} was found, so this repository has no recorded install.`,
       help: [`${RUN} status`],
       kept: [], missing: [], errors: [],
     }));
@@ -458,9 +450,15 @@ export async function uninstall(argv) {
 
   if (failed === 0 && survivors.length === 0 && selected.size === AGENTS.length) {
     // Everything we recorded is gone; the lock has nothing left to describe.
-    const { removeFile } = await import('./fsx.mjs');
     removeFile(lockfile.lockPath(ctx.root));
-    pruneDirs(['.sw-ai-sdk'], ctx);
+    removeFile(lockfile.legacyLockPath(ctx.root));
+    // `pruneDirs` deliberately never touches a top-level directory — that
+    // rule protects a host's own `.claude`/`.codex`, but `.sw-ai-sdk` and
+    // `var/sw-ai-sdk` are ours, and an empty one left behind is the clutter
+    // this move set out to remove.
+    pruneDirs([lockDir(ctx.root)], ctx);
+    removeDirIfEmpty(abs(ctx.root, LOCK_DIR_LEGACY));
+    removeDirIfEmpty(abs(ctx.root, lockDir(ctx.root)));
   } else {
     // Keep a lock describing exactly what survived, so a re-run resumes.
     lockfile.write(ctx.root, rebuild(lock, survivors, selected));

package/lib/content.mjs

@@ -9,7 +9,7 @@
 import { readFileSync, readdirSync, statSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { walk } from './fsx.mjs';
+import { isDir, walk } from './fsx.mjs';
 
 export const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -25,8 +25,38 @@ export const PKG_VERSION = pkg.version;
 export const CONTENT_VERSION = 1;
 export const SUPPORTED_CONTENT = [1];
 
+/**
+ * Where the lock lives, relative to the install root.
+ *
+ * A Shopware project ignores the whole of `var/` through the `shopware/core`
+ * Flex recipe (`/var/*` with a single `!/var/.htaccess` negation), and `var/`
+ * is already where that project keeps machine-local state — `var/cache`,
+ * `var/log`. Writing the lock there keeps the repository root clean and means
+ * the installer needs no `.gitignore` line at all.
+ *
+ * A root with no `var/` — a user-scope install under $HOME, or a checkout that
+ * is not a Shopware project — keeps the original dot-directory, which is
+ * gitignored through the managed block as before. Nothing here looks at the
+ * platform or at any path outside the install root.
+ */
 export const LOCK_DIR = '.sw-ai-sdk';
 export const LOCK_FILE = `${LOCK_DIR}/harness.lock.json`;
+export const VAR_LOCK_DIR = 'var/sw-ai-sdk';
+export const VAR_LOCK_FILE = `${VAR_LOCK_DIR}/harness.lock.json`;
+
+/** `var/sw-ai-sdk` when the root has a `var/`, else `.sw-ai-sdk`. */
+export function lockDir(root) {
+  return isDir(join(root, 'var')) ? VAR_LOCK_DIR : LOCK_DIR;
+}
+
+export function lockFile(root) {
+  return `${lockDir(root)}/harness.lock.json`;
+}
+
+/** Whether this root still needs the managed `.gitignore` line for the lock. */
+export function lockNeedsGitignore(root) {
+  return lockDir(root) === LOCK_DIR;
+}
 
 function dirsIn(abs) {
   return readdirSync(abs)

package/lib/guide.mjs

@@ -6,10 +6,8 @@
 
 import * as out from './out.mjs';
 import { PKG_NAME, PKG_VERSION } from './content.mjs';
-import { EXTRA_COMPONENTS } from './extra-components.mjs';
 
 const RUN = `npx -y ${PKG_NAME}@${PKG_VERSION}`;
-const EXTRA_COMPONENT_INSTALLS = EXTRA_COMPONENTS.map((c) => `npm i -D ${c.pkg}@${c.version}`).join('\n');
 
 export const GUIDE = `# ${PKG_NAME} — install protocol
 
@@ -55,26 +53,21 @@ registers the MCP servers and permission rules they depend on.
                                              terminal
   --scope project|user                      default: project
   --root <path>                             default: the current directory
-  --no-extra-components                     skip the optional extra-component skills
   --json                                    print the result object instead of
                                              the human summary — a skill or
                                              agent always passes this
   --verbose                                 include the per-file detail
 
-## Optional extra components
+## The two visual editors
 
-Two skills — Specs Editor and Tender Discovery Tool — ship inside their own
-npm packages, not this one. \`plan\`/\`apply\` detect them offline
-(\`npx --no-install\`) and never fetch them, probing for the exact version
-this release pins — any other version, including \`@latest\`, is treated as
-absent and the skill is skipped:
-
-\`\`\`bash
-${EXTRA_COMPONENT_INSTALLS}
-\`\`\`
-
-The exact command is also in a \`skipped\` action's \`remedy\`, and in
-\`status\`'s \`extra_components\` array. Install it, then re-run \`${RUN} apply --yes\`.
+The Specs Editor and the Tender Discovery Tool are optional, ship their own
+skill inside their own npm package, and are **not installed by this CLI**.
+The \`sw-setup\` skill owns their whole lifecycle — it offers them, installs
+each one with that package's own \`install-skill --target <skills dir>\`,
+updates them by re-running it, and removes them with \`uninstall-skill\`.
+This CLI never probes for them, never reports them, and never reaches the
+network for them; \`status --json\` reports each agent's \`skills_dir\`,
+which is the target \`sw-setup\` hands them.
 
 ## What you can rely on