@execuro-sw-ecosystem/sw-ecosystem-agentic-harness 0.1.0 → 0.1.3

package/CHANGELOG.md

@@ -7,6 +7,69 @@ release.
 
 ## [Unreleased]
 
+## [0.1.3] - 2026-09-17
+
+### Changed
+
+- **The `vendor/` row now names the specific missing file when unticked.**
+  `sw-setup`'s printed line says which of `vendor/shopware/core`,
+  `composer.lock` or `vendor/bin/phpunit` is missing instead of just marking
+  the row unticked, so a `--no-dev` vendor tree (which has the first two but
+  not `vendor/bin/phpunit`) is diagnosable at a glance. Same fix as before,
+  `composer install --no-interaction`, offered the same way.
+- **The update documentation now covers every component.** `README.md`'s
+  **Keep up to date** section became **Keeping it up to date** and says how
+  each of the three parts updates on its own schedule: this package through
+  `install`, the MCP servers by themselves (they are registered as `@latest`,
+  so a host fetches the newest build when it next starts one), and the Specs
+  Editor and Tender Discovery Tool through their own `npm i -D` line followed
+  by a re-run of `install`. The section also moved below Install's own
+  subsections, which it had been separating from their heading.
+- **The two extra components are now named individually, with the exact
+  pinned `npm i -D` command for each**, in both `README.md`'s new **The
+  optional editors** subsection and `guide`'s output — replacing the earlier
+  `<package>@<version>` placeholder — because the probe accepts only the
+  exact version `EXTRA_COMPONENTS` pins and skips the skill for anything else,
+  including `@latest`.
+- **Breaking: the "companion" terminology is renamed to "extra component".**
+  The CLI flag `--no-companions` is now `--no-extra-components`, and the
+  `status` JSON output key `companions` is now `extra_components`. Anything
+  scripting against `0.1.2` or earlier that reads `companions` or passes
+  `--no-companions` must update to the new names — there is no backwards-
+  compatible alias.
+- **`sw-storefront-developer`'s locate proofs now check for deprecated
+  forwarder files and `feature()` branches, and read the active theme's
+  `views` chain.** Proof 1 rejects a template whose header names it a removed
+  forwarder; proof 2 notes the `feature()` branch a block sits in; proof 3
+  also greps the theme's `theme.json` `views` order. The chain order and
+  where an override belongs are now deferred to the storefront guideline's
+  expert template-inheritance and override-placement sections instead of
+  being restated in the agent body.
+
+## [0.1.2] - 2026-09-16
+
+### Changed
+
+- **Install/update instructions now anchor to `@latest`.** Every `npx`
+  invocation of this package in `README.md`, `sw-setup`'s `SKILL.md` and
+  `reference/rows.md` uses `@execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest`
+  instead of a bare package name or a frozen version — a bare invocation can
+  resolve to a stale copy already in the `npx` cache or `node_modules`. Added
+  a **Keep up to date** section to `README.md` and a **Keeping it current**
+  section to `guide`'s output.
+
+## [0.1.1] - 2026-09-16
+
+### Added
+
+- **An `install` command** — `apply --yes` under a friendlier one-step name.
+  Typing the verb is the consent, so it never prompts and needs no `--yes`; the
+  scriptable `apply --yes` is unchanged and stays what skills and CI call.
+
+### Fixed
+
+- CI and the GitHub Pages setup for the plugin marketplace.
+
 ## [0.1.0] - 2026-09-16
 
 ### Added

package/README.md

@@ -49,7 +49,8 @@ declines is fully set up without them, and `--editor` on `sw-design-requirements
 
 | Command | What it does |
 | --- | --- |
-| `status` | read-only; what is installed, what drifted, which optional companion packages are present |
+| `install` | installs into every detected host; the same as `apply --yes` |
+| `status` | read-only; what is installed, what drifted, which optional extra components are present |
 | `plan` | the exact changes, written as a diff; writes nothing |
 | `apply --yes` | performs them |
 | `uninstall --yes` | removes what the lock file records |
@@ -58,22 +59,18 @@ declines is fully set up without them, and `--editor` on `sw-design-requirements
 Flags: `--host claude-code|codex|copilot|cursor` (repeatable; omitting it
 selects every host that is present), `--scope project|user` (default
 `project`), `--root <path>` (default the current directory), `--yes` (required
-by `apply` and `uninstall`, never prompts), and `--no-companions` (skip
-detection of the optional editor packages).
+by `apply` and `uninstall`, never prompts — `install` implies it), and
+`--no-extra-components` (skip detection of the optional editor packages).
 
 ## Install
 
 ```bash
-# see what is there and what is missing — read-only, always safe
-npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness status
-
-# see the exact changes, written as a diff. Writes nothing.
-npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness plan
-
-# perform them
-npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness apply --yes
+npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest install
 ```
 
+Want to look first? `status` is read-only and `plan` prints the diff; neither
+writes anything.
+
 Then restart your coding agent — every host reads its configuration at startup.
 The command's output tells you which ones and how.
 
@@ -111,7 +108,7 @@ Codex never reads `CLAUDE.md`.
 Undo everything with:
 
 ```bash
-npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness uninstall --yes
+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,
@@ -125,9 +122,51 @@ installed skill file goes stale and the CLI does not. Anything that needs the
 protocol runs:
 
 ```bash
-npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness guide
+npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest guide
 ```
 
+## Keeping it up to date
+
+Three things update on different schedules.
+
+| What | How it updates |
+| --- | --- |
+| 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. |
+
+### 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:
+
+```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
+```
+
+- `sw-specs-editor` backs the `--editor` flag on `sw-design-requirements` and
+  `sw-design-solution`.
+- `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.
+
+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
+version in the lock file. Restart your coding agent afterwards — every host
+reads its configuration at startup.
+
+`@latest` matters. Without it, `npx` can reuse a copy already in its cache or
+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.
+
 ## Prerequisites
 
 | Requirement | Why | Check |
@@ -210,7 +249,7 @@ instead — it then applies across every repo without per-repo commits.
 
 ```bash
 # 1. the install is complete and undrifted
-npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness status
+npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest status
 
 # 2. the toolchain the agents call actually exists
 shopware-cli project console --help

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 companion packages (they have their own repositories
+separately published extra components (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/agents/sw-php-backend-developer.md

@@ -1,6 +1,6 @@
 ---
 name: sw-php-backend-developer
-description: Shopware 6 PHP backend specialist. Use PROACTIVELY for any Shopware backend work — plugin/app PHP, DAL entities & migrations, Store/Admin API routes, services & decorators, event subscribers, flow actions, message handlers, caching, ACL. Triggers: "add an entity", "create an API endpoint", "extend checkout/order/product logic", "write a migration", "implement backend AC". Not for Administration (Vue) or Storefront (Twig/JS) work.
+description: Shopware 6 PHP backend specialist. Use PROACTIVELY for any Shopware backend work — plugin/app PHP, DAL entities & migrations, Store/Admin API routes, services & decorators, event subscribers, flow actions, message handlers, caching, ACL. Triggers — "add an entity", "create an API endpoint", "extend checkout/order/product logic", "write a migration", "implement backend AC". Not for Administration (Vue) or Storefront (Twig/JS) work.
 model: inherit
 tools: Read, Write, Edit, Glob, Grep, Bash, mcp__ShopwareDevKnowledgeBase__list_docs, mcp__ShopwareDevKnowledgeBase__grep_docs, mcp__ShopwareDevKnowledgeBase__read_doc, mcp__ShopwareDevKnowledgeBase__kb_status
 color: blue

package/agents/sw-storefront-developer.md

@@ -41,7 +41,7 @@ An edit is not done until `lint:twig` passes on it and the changed markup is obs
 - Lighthouse on touched pages; perf/a11y/SEO regressions are failures.
 - Playwright MCP (`mcp__playwright__*`) for click-through and screenshots. Shopware docs MCP (`mcp__ShopwareDevKnowledgeBase__*`) for the exact core template, block, route or plugin before extending; never guess a block name.
 - Test the targeted state: logged-out, logged-in, guest checkout, plus a non-default currency or language when prices or text change.
-- "Does not show up" checklist, in order: template path, block name, theme assigned, theme compiled, cache cleared, browser cache.
+- "Does not show up" checklist, in order: template path (not a deprecated forwarder file), block name in that file (and its `feature()` branch), theme assigned, theme compiled, cache cleared, browser cache.
 
 ### Small, reversible
 - One concern per template, subscriber or plugin; header + footer + checkout is three changes.
@@ -56,14 +56,14 @@ An edit is not done until `lint:twig` passes on it and the changed markup is obs
 
 1. **Classify.** Confirm storefront work (see Boundary). If mixed, split and hand off the non-storefront part first.
 2. **Locate — prove it, never assume.** Docs MCP answers *what an extension point is for*; only the installed source answers *whether it exists here*. Produce all four proofs before writing a single `{% block %}`:
-   1. The target template exists at the exact relative path: `ls vendor/shopware/storefront/Resources/views/storefront/<rel>`.
-   2. The block name exists verbatim **in that file**: `grep -n "{% block <name>" vendor/shopware/storefront/Resources/views/storefront/<rel>`. Block names are not unique across the storefront (~2200 block tags, ~2035 distinct names — every override re-declares its parent's name), so a repo-wide grep for a name is not proof. If it is not in that file, it lives in an included sub-template: find that file and override it instead.
-   3. Every other bundle already providing the same relative path: `grep -rl "<rel>" custom/ vendor/*/*/Resources/views/`. Name who wins under the slot order above, and whether they call `{{ parent() }}`.
+   1. The target template exists at the exact relative path: `ls vendor/shopware/storefront/Resources/views/storefront/<rel>` — and its first lines carry no `@deprecated … File will be removed` header: such a forwarder is never loaded, extend the file it names instead.
+   2. The block name exists verbatim **in that file**: `grep -n "{% block <name>" vendor/shopware/storefront/Resources/views/storefront/<rel>`. Block names are not unique across the storefront (~2200 block tags, ~2035 distinct names — every override re-declares its parent's name), so a repo-wide grep for a name is not proof. If it is not in that file, it lives in an included sub-template: find that file and override it instead. Note the `feature()` branch the block sits in, if any — the guideline's template-inheritance section says which anchor to target.
+   3. Every other bundle already providing the same relative path: `grep -rl "<rel>" custom/ vendor/*/*/Resources/views/`, plus the active theme's chain: `grep -A4 '"views"' custom/*/*/src/Resources/theme.json`. Name who wins under the chain order in the guideline's template-inheritance section, and whether they call `{{ parent() }}`.
    4. When the dev env is up, `shopware-cli project console debug:twig @Storefront/storefront/<rel>` prints "Matched File" and "Overridden Files" — the real resolution, and it overrides 1–3. Caveat: the theme slot is filled per storefront request, so a CLI run may show only the `@Storefront`/`@Plugins` part of the chain; the browser is the final word on which theme override wins.
    A block name recalled from memory or from an older Shopware version is a defect, not a starting point.
 3. **Place.** Theme (look, Bootstrap variables) vs plugin (features).
 4. **Test first** where tooling supports it: Jest for JS plugins, functional/e2e for rendered HTML. Failing test before the extension.
-5. **Implement** the smallest extension that passes: one block, one subscriber, one plugin.
+5. **Implement** the smallest extension that passes: one block, one subscriber, one plugin — placed per the guideline's override-placement ladder (edit an existing project override rather than adding a second file for the same path; go later in the chain than a marketplace override).
 6. **Lint and build.** `lint:twig` on every touched Twig file first, then `extension validate` for SCSS/JS, then the cache/theme/build sequence — all per "Verify: lint, build, render".
 7. **Verify.** Render assertion first (the changed markup is actually in the page), then browser pass (Playwright MCP), console/network clean, breakpoints, keyboard, Lighthouse.
 8. **Report** in the format below.

package/agents/sw-tender-editor.md

@@ -1,6 +1,6 @@
 ---
 name: sw-tender-editor
-description: Mechanical file worker for the sw-discover-tender skill — extracts requirement tables from a tender's source export into cluster files, merges PM/architect/QA cluster reports into finished §4 row blocks, splices those blocks into the analysis sidecar, and assembles and checks the final response CSVs. Deterministic, no judgment: every value it writes comes from a named input file, never from memory or estimation. Not for research, feasibility checks, effort estimation or any judgment call — that is `sw-product-manager`, `sw-shopware-architect` and `sw-qa-engineer`'s work; this agent only reshapes what they already produced into the file the skill needs next.
+description: Mechanical file worker for the sw-discover-tender skill — extracts requirement tables from a tender's source export into cluster files, merges PM/architect/QA cluster reports into finished §4 row blocks, splices those blocks into the analysis sidecar, and assembles and checks the final response CSVs. Deterministic, no judgment — every value it writes comes from a named input file, never from memory or estimation. Not for research, feasibility checks, effort estimation or any judgment call — that is `sw-product-manager`, `sw-shopware-architect` and `sw-qa-engineer`'s work; this agent only reshapes what they already produced into the file the skill needs next.
 tools: Read, Write, Edit, Glob, Grep
 ---
 

package/bin/cli.mjs

@@ -21,25 +21,30 @@ const COMMANDS = {
   status: async () => (await import('../lib/commands.mjs')).status,
   plan: async () => (await import('../lib/commands.mjs')).plan,
   apply: async () => (await import('../lib/commands.mjs')).apply,
+  install: async () => (await import('../lib/commands.mjs')).install,
   uninstall: async () => (await import('../lib/commands.mjs')).uninstall,
   guide: async () => (await import('../lib/guide.mjs')).main,
 };
 
 const USAGE = `usage: sw-ecosystem-agentic-harness <command> [options]
 
+  install    [--host <h>] [--scope project|user] [--root <path>] [--no-extra-components]
   status     [--host <h>] [--scope project|user] [--root <path>]
-  plan       [--host <h>] [--scope project|user] [--root <path>] [--no-companions]
-  apply      --yes [--host <h>] [--scope project|user] [--root <path>] [--no-companions]
+  plan       [--host <h>] [--scope project|user] [--root <path>] [--no-extra-components]
+  apply      --yes [--host <h>] [--scope project|user] [--root <path>] [--no-extra-components]
   uninstall  --yes [--host <h>] [--scope project|user] [--root <path>]
   guide      print the install protocol
 
+  install is apply --yes under a friendlier name: the whole install in one
+  command, no --yes needed — typing the verb is the consent.
+
   <h> is one of: claude-code, codex, copilot, cursor. Repeat --host to select
   several; omitting it selects every host that is present.
 
   --scope defaults to project: nothing is written under your home directory
   unless you ask for it. --root defaults to the current directory.
 
-  --no-companions skips the two optional companion-package skills (Specs
+  --no-extra-components skips the two optional extra-component skills (Specs
   Editor, Tender Discovery Tool) even when the package is present locally.
 
 Every command prints one JSON object on stdout carrying a next_step. Run

package/codex/agents/sw-php-backend-developer.toml

@@ -1,9 +1,9 @@
 # Generated by scripts/gen-codex-agents.mjs — do not edit.
 # source: agents/sw-php-backend-developer.md
-# source-sha256: 1d248ea38a0118ce2ebcea32f8dc780934bb6228e29c1b034baa1b3c43e102ea
+# source-sha256: ea82533b10d08e276f3c82da3555fd49f66b4141850990bca3e7e878fe07df61
 
 name = "sw-php-backend-developer"
-description = "Shopware 6 PHP backend specialist. Use PROACTIVELY for any Shopware backend work — plugin/app PHP, DAL entities & migrations, Store/Admin API routes, services & decorators, event subscribers, flow actions, message handlers, caching, ACL. Triggers: \"add an entity\", \"create an API endpoint\", \"extend checkout/order/product logic\", \"write a migration\", \"implement backend AC\". Not for Administration (Vue) or Storefront (Twig/JS) work."
+description = "Shopware 6 PHP backend specialist. Use PROACTIVELY for any Shopware backend work — plugin/app PHP, DAL entities & migrations, Store/Admin API routes, services & decorators, event subscribers, flow actions, message handlers, caching, ACL. Triggers — \"add an entity\", \"create an API endpoint\", \"extend checkout/order/product logic\", \"write a migration\", \"implement backend AC\". Not for Administration (Vue) or Storefront (Twig/JS) work."
 
 developer_instructions = '''
 

package/codex/agents/sw-storefront-developer.toml

@@ -1,6 +1,6 @@
 # Generated by scripts/gen-codex-agents.mjs — do not edit.
 # source: agents/sw-storefront-developer.md
-# source-sha256: 3d2ee9b1f1691eebedd1abaaf7126b55d5ea74677acda6a3f19765490ed9e6ce
+# source-sha256: 9afbeda4ca95afe1d74bf0268c3551031a519524fd2d1c4d2c4ece874cd6c054
 
 name = "sw-storefront-developer"
 description = "Use PROACTIVELY for any Shopware 6 Storefront work - Twig templates, theme/SCSS, storefront controllers/pages/pagelets, storefront JS plugins, checkout/account/product-page customizations."
@@ -43,7 +43,7 @@ An edit is not done until `lint:twig` passes on it and the changed markup is obs
 - Lighthouse on touched pages; perf/a11y/SEO regressions are failures.
 - Playwright MCP (`mcp__playwright__*`) for click-through and screenshots. Shopware docs MCP (`mcp__ShopwareDevKnowledgeBase__*`) for the exact core template, block, route or plugin before extending; never guess a block name.
 - Test the targeted state: logged-out, logged-in, guest checkout, plus a non-default currency or language when prices or text change.
-- "Does not show up" checklist, in order: template path, block name, theme assigned, theme compiled, cache cleared, browser cache.
+- "Does not show up" checklist, in order: template path (not a deprecated forwarder file), block name in that file (and its `feature()` branch), theme assigned, theme compiled, cache cleared, browser cache.
 
 ### Small, reversible
 - One concern per template, subscriber or plugin; header + footer + checkout is three changes.
@@ -58,14 +58,14 @@ An edit is not done until `lint:twig` passes on it and the changed markup is obs
 
 1. **Classify.** Confirm storefront work (see Boundary). If mixed, split and hand off the non-storefront part first.
 2. **Locate — prove it, never assume.** Docs MCP answers *what an extension point is for*; only the installed source answers *whether it exists here*. Produce all four proofs before writing a single `{% block %}`:
-   1. The target template exists at the exact relative path: `ls vendor/shopware/storefront/Resources/views/storefront/<rel>`.
-   2. The block name exists verbatim **in that file**: `grep -n "{% block <name>" vendor/shopware/storefront/Resources/views/storefront/<rel>`. Block names are not unique across the storefront (~2200 block tags, ~2035 distinct names — every override re-declares its parent's name), so a repo-wide grep for a name is not proof. If it is not in that file, it lives in an included sub-template: find that file and override it instead.
-   3. Every other bundle already providing the same relative path: `grep -rl "<rel>" custom/ vendor/*/*/Resources/views/`. Name who wins under the slot order above, and whether they call `{{ parent() }}`.
+   1. The target template exists at the exact relative path: `ls vendor/shopware/storefront/Resources/views/storefront/<rel>` — and its first lines carry no `@deprecated … File will be removed` header: such a forwarder is never loaded, extend the file it names instead.
+   2. The block name exists verbatim **in that file**: `grep -n "{% block <name>" vendor/shopware/storefront/Resources/views/storefront/<rel>`. Block names are not unique across the storefront (~2200 block tags, ~2035 distinct names — every override re-declares its parent's name), so a repo-wide grep for a name is not proof. If it is not in that file, it lives in an included sub-template: find that file and override it instead. Note the `feature()` branch the block sits in, if any — the guideline's template-inheritance section says which anchor to target.
+   3. Every other bundle already providing the same relative path: `grep -rl "<rel>" custom/ vendor/*/*/Resources/views/`, plus the active theme's chain: `grep -A4 '"views"' custom/*/*/src/Resources/theme.json`. Name who wins under the chain order in the guideline's template-inheritance section, and whether they call `{{ parent() }}`.
    4. When the dev env is up, `shopware-cli project console debug:twig @Storefront/storefront/<rel>` prints "Matched File" and "Overridden Files" — the real resolution, and it overrides 1–3. Caveat: the theme slot is filled per storefront request, so a CLI run may show only the `@Storefront`/`@Plugins` part of the chain; the browser is the final word on which theme override wins.
    A block name recalled from memory or from an older Shopware version is a defect, not a starting point.
 3. **Place.** Theme (look, Bootstrap variables) vs plugin (features).
 4. **Test first** where tooling supports it: Jest for JS plugins, functional/e2e for rendered HTML. Failing test before the extension.
-5. **Implement** the smallest extension that passes: one block, one subscriber, one plugin.
+5. **Implement** the smallest extension that passes: one block, one subscriber, one plugin — placed per the guideline's override-placement ladder (edit an existing project override rather than adding a second file for the same path; go later in the chain than a marketplace override).
 6. **Lint and build.** `lint:twig` on every touched Twig file first, then `extension validate` for SCSS/JS, then the cache/theme/build sequence — all per "Verify: lint, build, render".
 7. **Verify.** Render assertion first (the changed markup is actually in the page), then browser pass (Playwright MCP), console/network clean, breakpoints, keyboard, Lighthouse.
 8. **Report** in the format below.

package/codex/agents/sw-tender-editor.toml

@@ -1,9 +1,9 @@
 # Generated by scripts/gen-codex-agents.mjs — do not edit.
 # source: agents/sw-tender-editor.md
-# source-sha256: 72f167887e7d97164c0c7bb2ed03e23dd041fb868746857744bcd255909a03d5
+# source-sha256: 288b5d684f40ea62aa2b6021cfa3109a7f664fc2365f32109bcd9d1f94eb8a2c
 
 name = "sw-tender-editor"
-description = "Mechanical file worker for the sw-discover-tender skill — extracts requirement tables from a tender's source export into cluster files, merges PM/architect/QA cluster reports into finished §4 row blocks, splices those blocks into the analysis sidecar, and assembles and checks the final response CSVs. Deterministic, no judgment: every value it writes comes from a named input file, never from memory or estimation. Not for research, feasibility checks, effort estimation or any judgment call — that is `sw-product-manager`, `sw-shopware-architect` and `sw-qa-engineer`'s work; this agent only reshapes what they already produced into the file the skill needs next."
+description = "Mechanical file worker for the sw-discover-tender skill — extracts requirement tables from a tender's source export into cluster files, merges PM/architect/QA cluster reports into finished §4 row blocks, splices those blocks into the analysis sidecar, and assembles and checks the final response CSVs. Deterministic, no judgment — every value it writes comes from a named input file, never from memory or estimation. Not for research, feasibility checks, effort estimation or any judgment call — that is `sw-product-manager`, `sw-shopware-architect` and `sw-qa-engineer`'s work; this agent only reshapes what they already produced into the file the skill needs next."
 
 developer_instructions = '''
 

package/content/AGENTS.md

@@ -16,7 +16,7 @@ procedure, and the detail lives in `reference/*.md` files beside its
 | `sw-discover-tender` | Analyse a client tender (RFP, RFI or RFQ) for a Shopware 6 project into one markdown sidecar, <source basename>-analysis.md. |
 | `sw-document-feature` | Document one Shopware project feature into the LLM-wiki under docs/project-wiki/ — one feature page per surface (administration/ and/or storefront/), the "why" row in the domain index, ADR pages only promoted from the WIP ADR files sw-design-solution extracted into specs/ once they are accepted and built (with an organised table of contents) or provided by the user (never invented). |
 | `sw-implement-feature` | Implement a feature from its technical spec (specs/NNNN-slug-spec.md, written by sw-design-solution) following TDD — tests first per acceptance criterion, then the implementation, fixing until every relevant test passes (including that AC's own acceptance/e2e test, run immediately, not deferred), running Shopware's own shopware-cli fixers/static-analysis per AC to conform to Shopware's coding standards as code is written rather than after the fact. |
-| `sw-setup` | Print one environment-readiness table for the project's development/test setup — containers, vendor/, Node, the editor CLIs, shopware-cli, the KB MCP, the acceptance-test project, Playwright browsers, its .env, per-plugin test scaffolding, the project wiki and `.gitignore`, plus the installer CLI's own configuration/drift status. |
+| `sw-setup` | Print one environment-readiness table for the project's development/test setup — vendor/, Node, the editor CLIs, shopware-cli, the KB MCP, the acceptance-test project, Playwright browsers, its .env, per-plugin test scaffolding, the project wiki and `.gitignore`, plus the installer CLI's own configuration/drift status. |
 | `sw-verify-feature` | Verify a feature implementation against its technical spec (specs/NNNN-slug-spec.md) by running three independent verifiers in parallel — AC test coverage/health, architecture/guideline compliance, and code quality/static analysis — then cross-checking their verdicts into one final per-AC pass/not pass/partly report. |
 | `sw-verify-feature-ac-tests` | Verify that a feature's acceptance criteria are backed by tests that actually exist, actually pass, and actually test what their name/comment/PHPDoc claims. |
 | `sw-verify-feature-architecture` | Verify that a feature's implementation matches the architectural decisions its spec made, and complies with Shopware's own Core conventions plus any written Project guidelines this repo defines. |
@@ -45,7 +45,7 @@ and installs the harness configuration — permission rules and the MCP
 server registrations — through the installer CLI:
 
 ```
-npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@0.1.0 status
+npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest status
 ```
 
 The Shopware knowledge base is served by the `ShopwareDevKnowledgeBase`

package/copilot/agents/sw-php-backend-developer.agent.md

@@ -1,12 +1,12 @@
 ---
 name: "sw-php-backend-developer"
-description: "Shopware 6 PHP backend specialist. Use PROACTIVELY for any Shopware backend work — plugin/app PHP, DAL entities & migrations, Store/Admin API routes, services & decorators, event subscribers, flow actions, message handlers, caching, ACL. Triggers: \"add an entity\", \"create an API endpoint\", \"extend checkout/order/product logic\", \"write a migration\", \"implement backend AC\". Not for Administration (Vue) or Storefront (Twig/JS) work."
+description: "Shopware 6 PHP backend specialist. Use PROACTIVELY for any Shopware backend work — plugin/app PHP, DAL entities & migrations, Store/Admin API routes, services & decorators, event subscribers, flow actions, message handlers, caching, ACL. Triggers — \"add an entity\", \"create an API endpoint\", \"extend checkout/order/product logic\", \"write a migration\", \"implement backend AC\". Not for Administration (Vue) or Storefront (Twig/JS) work."
 tools: [read, edit, search, execute]
 ---
 
 <!-- Generated by scripts/gen-copilot-agents.mjs — do not edit. -->
 <!-- source: agents/sw-php-backend-developer.md -->
-<!-- source-sha256: 1d248ea38a0118ce2ebcea32f8dc780934bb6228e29c1b034baa1b3c43e102ea -->
+<!-- source-sha256: ea82533b10d08e276f3c82da3555fd49f66b4141850990bca3e7e878fe07df61 -->
 # PHP Backend Developer (Shopware 6)
 
 ## Identity

package/copilot/agents/sw-storefront-developer.agent.md

@@ -5,7 +5,7 @@ description: "Use PROACTIVELY for any Shopware 6 Storefront work - Twig template
 
 <!-- Generated by scripts/gen-copilot-agents.mjs — do not edit. -->
 <!-- source: agents/sw-storefront-developer.md -->
-<!-- source-sha256: 3d2ee9b1f1691eebedd1abaaf7126b55d5ea74677acda6a3f19765490ed9e6ce -->
+<!-- source-sha256: 9afbeda4ca95afe1d74bf0268c3551031a519524fd2d1c4d2c4ece874cd6c054 -->
 # Shopware Storefront Developer
 
 ## Role
@@ -42,7 +42,7 @@ An edit is not done until `lint:twig` passes on it and the changed markup is obs
 - Lighthouse on touched pages; perf/a11y/SEO regressions are failures.
 - Playwright MCP (`mcp__playwright__*`) for click-through and screenshots. Shopware docs MCP (`mcp__ShopwareDevKnowledgeBase__*`) for the exact core template, block, route or plugin before extending; never guess a block name.
 - Test the targeted state: logged-out, logged-in, guest checkout, plus a non-default currency or language when prices or text change.
-- "Does not show up" checklist, in order: template path, block name, theme assigned, theme compiled, cache cleared, browser cache.
+- "Does not show up" checklist, in order: template path (not a deprecated forwarder file), block name in that file (and its `feature()` branch), theme assigned, theme compiled, cache cleared, browser cache.
 
 ### Small, reversible
 - One concern per template, subscriber or plugin; header + footer + checkout is three changes.
@@ -57,14 +57,14 @@ An edit is not done until `lint:twig` passes on it and the changed markup is obs
 
 1. **Classify.** Confirm storefront work (see Boundary). If mixed, split and hand off the non-storefront part first.
 2. **Locate — prove it, never assume.** Docs MCP answers *what an extension point is for*; only the installed source answers *whether it exists here*. Produce all four proofs before writing a single `{% block %}`:
-   1. The target template exists at the exact relative path: `ls vendor/shopware/storefront/Resources/views/storefront/<rel>`.
-   2. The block name exists verbatim **in that file**: `grep -n "{% block <name>" vendor/shopware/storefront/Resources/views/storefront/<rel>`. Block names are not unique across the storefront (~2200 block tags, ~2035 distinct names — every override re-declares its parent's name), so a repo-wide grep for a name is not proof. If it is not in that file, it lives in an included sub-template: find that file and override it instead.
-   3. Every other bundle already providing the same relative path: `grep -rl "<rel>" custom/ vendor/*/*/Resources/views/`. Name who wins under the slot order above, and whether they call `{{ parent() }}`.
+   1. The target template exists at the exact relative path: `ls vendor/shopware/storefront/Resources/views/storefront/<rel>` — and its first lines carry no `@deprecated … File will be removed` header: such a forwarder is never loaded, extend the file it names instead.
+   2. The block name exists verbatim **in that file**: `grep -n "{% block <name>" vendor/shopware/storefront/Resources/views/storefront/<rel>`. Block names are not unique across the storefront (~2200 block tags, ~2035 distinct names — every override re-declares its parent's name), so a repo-wide grep for a name is not proof. If it is not in that file, it lives in an included sub-template: find that file and override it instead. Note the `feature()` branch the block sits in, if any — the guideline's template-inheritance section says which anchor to target.
+   3. Every other bundle already providing the same relative path: `grep -rl "<rel>" custom/ vendor/*/*/Resources/views/`, plus the active theme's chain: `grep -A4 '"views"' custom/*/*/src/Resources/theme.json`. Name who wins under the chain order in the guideline's template-inheritance section, and whether they call `{{ parent() }}`.
    4. When the dev env is up, `shopware-cli project console debug:twig @Storefront/storefront/<rel>` prints "Matched File" and "Overridden Files" — the real resolution, and it overrides 1–3. Caveat: the theme slot is filled per storefront request, so a CLI run may show only the `@Storefront`/`@Plugins` part of the chain; the browser is the final word on which theme override wins.
    A block name recalled from memory or from an older Shopware version is a defect, not a starting point.
 3. **Place.** Theme (look, Bootstrap variables) vs plugin (features).
 4. **Test first** where tooling supports it: Jest for JS plugins, functional/e2e for rendered HTML. Failing test before the extension.
-5. **Implement** the smallest extension that passes: one block, one subscriber, one plugin.
+5. **Implement** the smallest extension that passes: one block, one subscriber, one plugin — placed per the guideline's override-placement ladder (edit an existing project override rather than adding a second file for the same path; go later in the chain than a marketplace override).
 6. **Lint and build.** `lint:twig` on every touched Twig file first, then `extension validate` for SCSS/JS, then the cache/theme/build sequence — all per "Verify: lint, build, render".
 7. **Verify.** Render assertion first (the changed markup is actually in the page), then browser pass (Playwright MCP), console/network clean, breakpoints, keyboard, Lighthouse.
 8. **Report** in the format below.

package/copilot/agents/sw-tender-editor.agent.md

@@ -1,12 +1,12 @@
 ---
 name: "sw-tender-editor"
-description: "Mechanical file worker for the sw-discover-tender skill — extracts requirement tables from a tender's source export into cluster files, merges PM/architect/QA cluster reports into finished §4 row blocks, splices those blocks into the analysis sidecar, and assembles and checks the final response CSVs. Deterministic, no judgment: every value it writes comes from a named input file, never from memory or estimation. Not for research, feasibility checks, effort estimation or any judgment call — that is `sw-product-manager`, `sw-shopware-architect` and `sw-qa-engineer`'s work; this agent only reshapes what they already produced into the file the skill needs next."
+description: "Mechanical file worker for the sw-discover-tender skill — extracts requirement tables from a tender's source export into cluster files, merges PM/architect/QA cluster reports into finished §4 row blocks, splices those blocks into the analysis sidecar, and assembles and checks the final response CSVs. Deterministic, no judgment — every value it writes comes from a named input file, never from memory or estimation. Not for research, feasibility checks, effort estimation or any judgment call — that is `sw-product-manager`, `sw-shopware-architect` and `sw-qa-engineer`'s work; this agent only reshapes what they already produced into the file the skill needs next."
 tools: [read, edit, search]
 ---
 
 <!-- Generated by scripts/gen-copilot-agents.mjs — do not edit. -->
 <!-- source: agents/sw-tender-editor.md -->
-<!-- source-sha256: 72f167887e7d97164c0c7bb2ed03e23dd041fb868746857744bcd255909a03d5 -->
+<!-- source-sha256: 288b5d684f40ea62aa2b6021cfa3109a7f664fc2365f32109bcd9d1f94eb8a2c -->
 # sw-tender-editor
 
 ## Identity

package/lib/actions.mjs

@@ -14,13 +14,13 @@ import {
   abs, ensureDir, readMaybe, readTextMaybe, removeDirIfEmpty, removeFile, rel, sha256, writeAtomic,
 } from './fsx.mjs';
 import {
-  canonical, deletePointer, fenceInner, findFence, getPointer, mergeArrayUnique, parseJsonLoose,
-  removeArrayValues, removeFence, serializeJson, setPointer, upsertFence,
+  canonical, deletePointer, fenceInner, findFence, getPointer, mergeArrayUnique, normalizeEol,
+  parseJsonLoose, removeArrayValues, removeFence, serializeJson, setPointer, upsertFence,
 } from './merge.mjs';
 import { PKG_ROOT } from './content.mjs';
 import { isDeclined } from './lock.mjs';
 import { readFileSync } from 'node:fs';
-import { COMPANIONS, probe } from './companions.mjs';
+import { EXTRA_COMPONENTS, probe } from './extra-components.mjs';
 
 /** Preview one action against the filesystem. Reads only. */
 export function preview(action, ctx) {
@@ -83,8 +83,8 @@ function stripProbeBody({ body, ...rest }) {
 }
 
 function previewSkill(action, ctx) {
-  const companion = COMPANIONS.find((c) => c.id === action.companion);
-  const probed = probe(companion, { platform: ctx.platform });
+  const component = EXTRA_COMPONENTS.find((c) => c.id === action.component);
+  const probed = probe(component, { platform: ctx.platform });
   const probeSummary = stripProbeBody(probed);
 
   if (!probed.available) {
@@ -226,8 +226,9 @@ function previewFence(action, ctx) {
   const found = readTextMaybe(target);
   const createdFile = found === null;
   // Hash what will actually sit inside the fence, warning line included, so it
-  // can be compared with what `findFence` reads back.
-  const hash = sha256(fenceInner(action.body, action.syntax));
+  // can be compared with what `findFence` reads back. Normalised to LF first —
+  // a fence's identity does not depend on the target file's line-ending style.
+  const hash = sha256(normalizeEol(fenceInner(action.body, action.syntax)));
   const locked = ctx.lock?.fences?.find(
     (f) => f.file === action.target && f.block === action.block,
   );
@@ -243,7 +244,7 @@ function previewFence(action, ctx) {
     return { ...base, prior: null, state: 'create',
       detail: createdFile ? 'creates the file with a managed block' : 'appends a managed block' };
   }
-  const priorHash = sha256(existing.inner);
+  const priorHash = sha256(normalizeEol(existing.inner));
   if (priorHash === hash) return { ...base, prior: priorHash, state: 'unchanged', created_file: locked?.created_file ?? false, detail: 'up to date' };
   if (locked && locked.hash !== priorHash) {
     return { ...base, prior: priorHash, state: 'drift', created_file: locked.created_file,
@@ -276,7 +277,7 @@ export function execute(action, ctx) {
     }
     case 'skill-copy': {
       // Collapses to a `file-copy` lock entry on purpose: `lock.record`,
-      // `lock.entries`, `revert` and `rebuild` need no companion-specific
+      // `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));
@@ -401,7 +402,7 @@ export function revert(entry, ctx) {
       if (found === null) return { state: 'missing', target: entry.target, reason: 'already gone' };
       const fence = findFence(found.text, entry.block);
       if (!fence) return { state: 'missing', target: entry.target, reason: 'our block is already gone' };
-      if (sha256(fence.inner) !== entry.hash) {
+      if (sha256(normalizeEol(fence.inner)) !== entry.hash) {
         return { state: 'kept', target: entry.target, reason: 'content inside the managed fence was hand-edited' };
       }
       const { next } = removeFence(found.text, entry.block);

package/lib/commands.mjs

@@ -14,7 +14,7 @@ import { exists, isWritable, abs } from './fsx.mjs';
 import { HOSTS, buildPlan, detectAll, installedCounts } from './hosts.mjs';
 import * as lockfile from './lock.mjs';
 import { dedupe, execute, isWritableState, preview, pruneDirs, revert } from './actions.mjs';
-import { probeAll } from './companions.mjs';
+import { probeAll } from './extra-components.mjs';
 
 const RUN = 'sw-ecosystem-agentic-harness';
 
@@ -29,12 +29,12 @@ export function buildContext(argv, command) {
   let root = process.cwd();
   let yes = false;
   let projectWiki;
-  let companions = true;
+  let extraComponents = true;
 
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--yes' || arg === '-y') { yes = true; continue; }
-    if (arg === '--no-companions') { companions = false; continue; }
+    if (arg === '--no-extra-components') { extraComponents = false; continue; }
     if (arg === '--host') {
       const value = argv[++i];
       if (!HOSTS.includes(value)) {
@@ -64,7 +64,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, companions,
+    root, scope, yes, projectWiki, extraComponents,
     hosts: hosts.length ? [...new Set(hosts)] : [...HOSTS],
     platform: process.platform,
     version: PKG_VERSION,
@@ -168,7 +168,7 @@ export async function status(argv) {
   const worst = ['conflict', 'drift', 'not-installed', 'ok', 'absent']
     .find((s) => hosts.some((h) => h.state === s)) ?? 'absent';
 
-  const companions = ctx.companions === false ? [] : probeAll({ platform: ctx.platform }).map((p) => ({
+  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 ?? {})
@@ -180,10 +180,10 @@ export async function status(argv) {
   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.companions !== false) {
-    const unavailable = companions.filter((c) => !c.available);
+  if (ctx.extraComponents !== false) {
+    const unavailable = extraComponents.filter((c) => !c.available);
     if (unavailable.length) {
-      next += ` ${unavailable.length} optional companion package(s) are not on this machine — install with ${unavailable.map((c) => `\`${c.install}\``).join(', ')} to enable their skills.`;
+      next += ` ${unavailable.length} optional extra component(s) are not on this machine — install with ${unavailable.map((c) => `\`${c.install}\``).join(', ')} to enable their skills.`;
     }
   }
 
@@ -193,7 +193,7 @@ export async function status(argv) {
     next_step: next,
     help: [`${RUN} plan`, `${RUN} apply --yes`, `${RUN} guide`],
     inventory: { skills: skills().length, agents: agents().length },
-    hosts, companions, drift,
+    hosts, extra_components: extraComponents, drift,
     declined: lock?.declined ?? [],
     manual: lock?.manual ?? [],
     errors,
@@ -245,17 +245,17 @@ const RESTART_HELP = {
   cursor: 'Restart Cursor so it re-reads .cursor/mcp.json',
 };
 
-export async function apply(argv) {
+export async function apply(argv, label = 'apply') {
   const ctx = buildContext(argv, 'apply');
   if (!ctx.yes) {
-    return out.usage('apply', 'apply refuses to write without --yes',
+    return out.usage(label, 'apply refuses to write without --yes',
       [`${RUN} plan`, `${RUN} apply --yes`]);
   }
 
   let lock;
   try { lock = loadLock(ctx) ?? lockfile.empty(ctx.scope); } catch (e) {
     if (e instanceof lockfile.LockVersionError) {
-      return out.failure('apply', e.message, {
+      return out.failure(label, e.message, {
         next_step: `Upgrade the package: npm i -D ${PKG_NAME}@latest`,
         help: [`npm i -D ${PKG_NAME}@latest`],
       });
@@ -266,7 +266,7 @@ export async function apply(argv) {
   // 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('apply', `cannot write the lock file at ${LOCK_FILE}`, {
+    return out.failure(label, `cannot write the lock file at ${LOCK_FILE}`, {
       next_step: `Make ${ctx.root} writable, then re-run \`${RUN} apply --yes\`.`,
       help: [`${RUN} status`],
     });
@@ -345,9 +345,12 @@ export async function apply(argv) {
     summary, lock_file: LOCK_FILE, next_step: next, help,
     hosts: [...perHost.values()], actions: results, manual, errors,
   });
-  return summary.failed ? out.failure('apply', `${summary.failed} change(s) failed`, body) : out.ok('apply', body);
+  return summary.failed ? out.failure(label, `${summary.failed} change(s) failed`, body) : out.ok(label, body);
 }
 
+/** `install` is `apply --yes`: typing the verb is the consent. */
+export const install = (argv) => apply(['--yes', ...argv], 'install');
+
 // --------------------------------------------------------------- uninstall
 
 export async function uninstall(argv) {