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

package/skills/sw-document-feature/reference/scaffold/guidelines/index.md

@@ -0,0 +1,50 @@
+---
+title: Guidelines
+nav_order: 7
+type: reference
+purpose: Where this project's own coding and QA rules live, and how they relate to Shopware's.
+scope: docs/project-wiki/guidelines/. Not the rules themselves — those come from the Shopware platform guidelines unless overridden here.
+last_synced: {{DATE}}
+verified_against: Shopware {{SHOPWARE_VERSION}}
+resync: Add a row below whenever a project guideline file is created or removed.
+tags: [guidelines, platform]
+---
+
+# Guidelines
+
+{{PROJECT_NAME}} has no coding guidelines of its own yet. Architecture, code and QA guidelines are
+inherited as-is from the Shopware platform guidelines, served by the ShopwareDevKnowledgeBase MCP
+at `platform/guidelines/<version>/` (the Shopware major, e.g. `6.7` for Shopware {{SHOPWARE_VERSION}}): the base files `architecture-guidelines.md`,
+`code-guidelines.md`, `qa-guidelines.md`, plus surface files (`be-`, `fe-`, `admin-`,
+`storefront-…guidelines.md`).
+
+[Documentation guidelines](documentation-guidelines.md) is the exception: it holds this wiki's own
+documentation rules (page shape, frontmatter, status vocabulary) and has no platform counterpart,
+so it is served as is, never merged.
+
+## Recording a project rule
+
+A rule is written here only to override, extend, waive, or add to a platform guideline — never to
+restate it. It comes only from a person's statement or an accepted ADR, never invented.
+
+The rule lives in `guidelines/<same file name as the platform file>.md` — no version folder: project
+guidelines always apply to the Shopware version installed in this project — with a `merge:` key
+naming which platform section it acts on and how. Coding agents and verifiers never read this
+file directly — they call `read_doc guidelines/<version>/<file>.md` on the MCP, which returns the
+effective file: the platform text with this project's sections merged in.
+
+## Project files
+
+<!-- guidelines-toc:start -->
+| documentation-guidelines.md | Wiki page shape, frontmatter, status vocabulary and terminology rules — project-only, no platform counterpart. |
+<!-- guidelines-toc:end -->
+
+Regenerated by `sw-document-feature` whenever it writes or edits a guideline file; text outside
+the markers is hand-maintained.
+
+---
+
+*Scope: `docs/project-wiki/guidelines/`, not the rules themselves — those are the Shopware
+platform guidelines unless a row above overrides them. · Last synced: {{DATE}} · Verified against
+Shopware {{SHOPWARE_VERSION}} · Re-sync: add a row whenever a project guideline file is created or
+removed.*

package/skills/sw-document-feature/reference/scaffold/index.md

@@ -0,0 +1,68 @@
+---
+title: Home
+nav_order: 1
+type: index
+purpose: Entry point and wiki index for the {{PROJECT_NAME}} documentation.
+scope: Everything under docs/project-wiki/. Does not cover Shopware core docs (use the ShopwareDevKnowledgeBase MCP for those).
+last_synced: {{DATE}}
+verified_against: Shopware {{SHOPWARE_VERSION}}
+resync: Regenerate the domain map from domains/index.md whenever a domain or feature page is added.
+tags: [index, wiki]
+---
+
+# Project documentation
+
+Everything this team knows about **this** Shopware project: what we built, why we built it that
+way, where it lives in the code, and how to run and debug it. Shopware's own behaviour is not
+repeated here — where stock Shopware already answers a question, we link to Shopware's docs
+instead. Coding guidelines are inherited from the Shopware platform guidelines; project deviations
+live in [Guidelines](guidelines/index.md).
+
+## Start here
+
+| If you are… | Go to |
+|---|---|
+| New to the project | [Tech stack](baseline/tech-stack.md) — versions, services, how to run it locally |
+| Looking for a feature | [Domains](domains/index.md) — pick a domain, then Administration or Storefront |
+| Asking "why is it built this way?" | [Decision records](adr/index.md) |
+| Checking a coding rule | [Guidelines](guidelines/index.md) |
+| Debugging something | [Debugging](domains/platform/debugging.md) · [Logging](domains/platform/logging.md) |
+| Unsure what a word means | [Glossary](baseline/glossary.md) |
+| Writing or generating a page | [Documentation guidelines](guidelines/documentation-guidelines.md) |
+
+## Domains
+
+Feature documentation is organised by business domain, then by the surface the user acts on —
+Administration (merchant) or Storefront (shopper).
+
+<!-- sw-document-feature adds one row per domain when the domain is created. Keep in sync with domains/index.md. -->
+
+| Domain | What it covers |
+|---|---|
+| [Platform](domains/platform/index.md) | Cross-cutting infrastructure: extensions, configuration, logging, debugging, environments |
+
+## All sections
+
+- [Tech stack](baseline/tech-stack.md) — the versions and services every feature is built and verified against
+- [Glossary](baseline/glossary.md) — project terms mapped to Shopware's own terminology
+- [Domains](domains/index.md) — feature documentation per domain and surface
+- [Decision records](adr/index.md) — the technical and process decisions behind the project
+- [Guidelines](guidelines/index.md) — this project's coding rules, inherited from Shopware unless overridden
+- [Documentation guidelines](guidelines/documentation-guidelines.md) — page types, front matter, status vocabulary, what not to document
+- [Overview](README.md) — what this wiki is and how it is published
+
+## About this wiki
+
+Pages are written and kept in sync by the `sw-document-feature` skill, which documents a feature
+only after it has been verified in the code. Each page states when it was last synced and which
+Shopware version it was verified against, so a stale page is visible as stale rather than wrong.
+
+The path a feature takes: PRD `specs/NNNN-slug.md` → tech spec `specs/NNNN-slug-spec.md` →
+implementation in `custom/plugins/<PluginName>` → `sw-verify-feature` → `sw-document-feature` →
+the pages here.
+
+---
+
+*Scope: everything under `docs/project-wiki/`. · Last synced: {{DATE}} · Verified against
+Shopware {{SHOPWARE_VERSION}} · Re-sync: run `sw-document-feature` after each `sw-verify-feature` report;
+`last_synced` is bumped only on the pages that run touches.*

package/skills/sw-document-feature/reference/scaffold/vanilla/README.md

@@ -0,0 +1,24 @@
+---
+title: "Shopware Project Wiki"
+nav_exclude: true
+tags: [readme, meta]
+---
+
+# Shopware Project Wiki
+
+This documentation was produced by the **Shopware Ecosystem AI SDK**. It is structured, atomic documentation written to be consumed by coding agents (MCP/LLM tooling) and, at the same time, to serve as the project's living documentation for the whole team — PMs, architects, developers, QA.
+
+## What is inside
+
+- `domains/<domain>/` → one feature page per surface (`administration/`, `storefront/`); `adr/` holds decision records; `domains/platform/` covers cross-cutting infrastructure (extensions, configuration, logging, debugging, environments); `guidelines/` holds this project's coding rules, inherited from Shopware unless overridden, plus [documentation guidelines](guidelines/documentation-guidelines.md).
+- Entry point is [index.md](index.md); the rules every page follows are in [guidelines/documentation-guidelines.md](guidelines/documentation-guidelines.md).
+- Kept in sync by the `sw-document-feature` skill after each feature verification (`sw-verify-feature`).
+
+## Browsing this wiki
+
+Every page is plain Markdown — no config files, no static-site build step or generator, nothing beyond docs and folder structure. Browse it directly in GitHub's file view, in any IDE, or on the command line with `cat`/`grep`. A Jekyll/GitHub Pages structure is a separate flavor of this same wiki, chosen once when it's first created — ask for that flavor next time if the project outgrows plain Markdown.
+
+---
+
+*Generated {{DATE}} · verified against Shopware {{SHOPWARE_VERSION}} · the rules for pages live in
+[guidelines/documentation-guidelines.md](guidelines/documentation-guidelines.md).*

package/skills/sw-document-feature/reference/scaffold/vanilla/adr/index.md

@@ -0,0 +1,36 @@
+---
+title: Decision records
+has_children: true
+nav_order: 5
+type: index
+purpose: Index of all decision records for this project — technical, process, and significant business decisions.
+scope: Every ADR under adr/. Routine business/functional rationale lives in the domain index feature tables, not here.
+last_synced: {{DATE}}
+verified_against: Shopware {{SHOPWARE_VERSION}}
+resync: The block between the adr-toc markers is regenerated by sw-document-feature on every run (readable on GitHub). WIP ADRs stay in specs/ until promoted.
+tags: [adr, index]
+---
+
+# Decision records
+
+The decisions this project is built on — technical, process, and the business decisions that shaped
+the architecture. A record lands here only once it is both accepted and actually built; until then
+it stays a work-in-progress file under `specs/*-adr-*.md`.
+
+Records follow Shopware's own ADR convention: `YYYY-MM-DD-title.md`, front matter
+`title`/`date`/`area`/`tags`/`authors`/`status`, and the sections Context / Decision / Consequences.
+This folder is the source of truth — later status changes (superseded, deprecated) are made here, by
+people. Nothing in it is generated by tooling.
+
+## Table of contents
+
+<!-- Regenerated by sw-document-feature on every run (step 5b, reference/adr-promotion.md §4). Do not edit between the markers; everything outside them is hand-maintained. -->
+<!-- adr-toc:start -->
+No decision records yet — the first one appears here once an accepted decision has been built.
+<!-- adr-toc:end -->
+
+---
+
+*Scope: accepted and built decisions only — routine functional rationale lives in the domain index
+feature tables. · Last synced: {{DATE}} · Verified against Shopware {{SHOPWARE_VERSION}} · Re-sync: the table of
+contents is regenerated by `sw-document-feature`; WIP records stay in `specs/` until promoted.*

package/skills/sw-document-feature/reference/scaffold/vanilla/index.md

@@ -0,0 +1,68 @@
+---
+title: Home
+nav_order: 1
+type: index
+purpose: Entry point and wiki index for the {{PROJECT_NAME}} documentation.
+scope: Everything under docs/project-wiki/. Does not cover Shopware core docs (use the ShopwareDevKnowledgeBase MCP for those).
+last_synced: {{DATE}}
+verified_against: Shopware {{SHOPWARE_VERSION}}
+resync: Regenerate the domain map from domains/index.md whenever a domain or feature page is added.
+tags: [index, wiki]
+---
+
+# Project documentation
+
+Everything this team knows about **this** Shopware project: what we built, why we built it that
+way, where it lives in the code, and how to run and debug it. Shopware's own behaviour is not
+repeated here — where stock Shopware already answers a question, we link to Shopware's docs
+instead. Coding guidelines are inherited from the Shopware platform guidelines; project deviations
+live in [Guidelines](guidelines/index.md).
+
+## Start here
+
+| If you are… | Go to |
+|---|---|
+| New to the project | [Tech stack](baseline/tech-stack.md) — versions, services, how to run it locally |
+| Looking for a feature | [Domains](domains/index.md) — pick a domain, then Administration or Storefront |
+| Asking "why is it built this way?" | [Decision records](adr/index.md) |
+| Checking a coding rule | [Guidelines](guidelines/index.md) |
+| Debugging something | [Debugging](domains/platform/debugging.md) · [Logging](domains/platform/logging.md) |
+| Unsure what a word means | [Glossary](baseline/glossary.md) |
+| Writing or generating a page | [Documentation guidelines](guidelines/documentation-guidelines.md) |
+
+## Domains
+
+Feature documentation is organised by business domain, then by the surface the user acts on —
+Administration (merchant) or Storefront (shopper).
+
+<!-- sw-document-feature adds one row per domain when the domain is created. Keep in sync with domains/index.md. -->
+
+| Domain | What it covers |
+|---|---|
+| [Platform](domains/platform/index.md) | Cross-cutting infrastructure: extensions, configuration, logging, debugging, environments |
+
+## All sections
+
+- [Tech stack](baseline/tech-stack.md) — the versions and services every feature is built and verified against
+- [Glossary](baseline/glossary.md) — project terms mapped to Shopware's own terminology
+- [Domains](domains/index.md) — feature documentation per domain and surface
+- [Decision records](adr/index.md) — the technical and process decisions behind the project
+- [Guidelines](guidelines/index.md) — this project's coding rules, inherited from Shopware unless overridden
+- [Documentation guidelines](guidelines/documentation-guidelines.md) — page types, front matter, status vocabulary, what not to document
+- [Overview](README.md) — what this wiki is
+
+## About this wiki
+
+Pages are written and kept in sync by the `sw-document-feature` skill, which documents a feature
+only after it has been verified in the code. Each page states when it was last synced and which
+Shopware version it was verified against, so a stale page is visible as stale rather than wrong.
+
+The path a feature takes: PRD `specs/NNNN-slug.md` → tech spec `specs/NNNN-slug-spec.md` →
+implementation in `custom/plugins/<PluginName>` → `sw-verify-feature` → `sw-document-feature` →
+the pages here.
+
+---
+
+*Scope: everything under `docs/project-wiki/`. · Last synced: {{DATE}} · Verified against
+Shopware {{SHOPWARE_VERSION}} · Re-sync: run `sw-document-feature` after each `sw-verify-feature` report;
+`last_synced` is bumped only on the pages that run touches.*

package/skills/sw-document-feature/reference/setup-wiki.md

@@ -0,0 +1,142 @@
+# Set up the wiki (step 0, conditional)
+
+Bootstraps `docs/project-wiki/` from `reference/scaffold/` in this skill's directory. Runs only on the two triggers below — a normal documentation run over an existing wiki never enters this file.
+
+Non-destructive by design: it only creates files that do not exist. A file already on disk — a hand-edited `_config.yml` included — is never overwritten, never refreshed to the scaffold version.
+
+## Triggers and modes
+
+| Trigger | Mode | Ends with |
+|---|---|---|
+| `--setup` in the arguments, no `docs/project-wiki/` | **init** — ask §2, write the baseline | Report §7, then stop. Documentation is a separate run |
+| `--setup` in the arguments, wiki exists | **repair** — recreate missing manifest files, drift check | Report §7, then stop |
+| No `--setup`, no `docs/project-wiki/` | **init** — ask §2, write the baseline | Report §7, then continue at step 1 of `SKILL.md` |
+| No `--setup`, wiki exists | not entered at all | — |
+
+Questions (§2) are asked by the main run, before the sub-agent is spawned: a sub-agent has no interactive channel and cannot ask them. Only the file writing (§5) is delegated.
+
+## 1. Detect
+
+`Glob docs/project-wiki/**` and compare against the manifest (§3). Three outcomes:
+
+- No `docs/project-wiki/` at all → **init**, flavor not yet chosen.
+- Directory exists, some entries missing → **repair**.
+- All entries for the wiki's own flavor present → nothing to create; drift check (§6) only.
+
+On repair the flavor is never asked — derive it: `docs/project-wiki/_config.yml` present → Jekyll, absent → Vanilla. That derivation is also what the content steps mean by "the Jekyll flavor" (the Liquid ADR table in `adr/index.md`).
+
+## 2. Questions (init only)
+
+One call to a structured question tool if you have one (Claude Code: `AskUserQuestion`; Codex: `request_user_input`), asked once ever per wiki. Question 2 is included only when the answer to question 1 is Jekyll — if the tool cannot express that dependency, ask question 1 alone first, then 2–3 in a second call.
+
+- **Question 1 — "docs/project-wiki/ does not exist yet — set it up as a Jekyll/GitHub Pages site or a plain Markdown wiki?"**
+  - Option 1, label "Jekyll / GitHub Pages (Recommended)": adds `_config.yml`, so pages render as a themed site with left sidebar navigation and search (Just the Docs, via `remote_theme:`), plus a Liquid-generated ADR table on top of the hand-maintained ADR index; ready to publish via GitHub Pages or `jekyll serve`.
+  - Option 2, label "Vanilla / plain Markdown": no `_config.yml`, no Liquid; every page is plain Markdown, browsable anywhere with no build step.
+- **Question 2 — "How will the wiki be published?"** (Jekyll only; decides `baseurl`, see §4)
+  - Option 1, label "Its own repository (Recommended)": this folder becomes a repository root, Pages serves it from the branch root, `baseurl` is `/<repo>`.
+  - Option 2, label "From this repository, /docs branch deploy": GitHub Pages reads `_config.yml` only from the Pages source root, so a nested wiki renders **unthemed**; `baseurl` stays empty and the README's setup B applies.
+  - Option 3, label "GitHub Actions build": a workflow points a Jekyll build at this folder; `baseurl` stays empty.
+  - Option 4, label "Not decided yet": `baseurl` is filled from the detected repository per §4 — the project-site default, which is what a first publish almost always needs; the comment above it says when to blank it.
+- **Question 3 — "Site title?"** — options: the default `Shopware Project Wiki` (recommended), or the detected project name (§4) followed by " — Project Wiki". Free text via *Other* overrides both.
+
+Nothing else is asked. The wiki always lives at `docs/project-wiki/` — the path is fixed across every page, rule file and template in this skill.
+
+## 3. Manifest — the expected tree
+
+Source files live in `reference/scaffold/` (shared root) and `reference/scaffold/vanilla/` (Vanilla-flavor overlay); targets are relative to `docs/project-wiki/`. 16 files for the Jekyll flavor, 15 for Vanilla (no `_config.yml`).
+
+| Scaffold path | Target path | Required | Flavor |
+|---|---|---|---|
+| `README.md` (or `vanilla/README.md`) | `docs/project-wiki/README.md` | yes | overlay (both, content differs) |
+| `index.md` (or `vanilla/index.md`) | `docs/project-wiki/index.md` | yes | overlay (both, content differs) |
+| `_config.yml` | `docs/project-wiki/_config.yml` | Jekyll only | jekyll-only |
+| `adr/index.md` (or `vanilla/adr/index.md`) | `docs/project-wiki/adr/index.md` | yes | overlay (both, content differs) |
+| `baseline/tech-stack.md` | `docs/project-wiki/baseline/tech-stack.md` | yes | both |
+| `baseline/glossary.md` | `docs/project-wiki/baseline/glossary.md` | yes | both |
+| `domains/index.md` | `docs/project-wiki/domains/index.md` | yes | both |
+| `domains/platform/index.md` | `docs/project-wiki/domains/platform/index.md` | yes | both |
+| `domains/platform/extensions-inventory.md` | `docs/project-wiki/domains/platform/extensions-inventory.md` | yes | both |
+| `domains/platform/customization-guidelines.md` | `docs/project-wiki/domains/platform/customization-guidelines.md` | yes | both |
+| `domains/platform/configuration.md` | `docs/project-wiki/domains/platform/configuration.md` | yes | both |
+| `domains/platform/logging.md` | `docs/project-wiki/domains/platform/logging.md` | yes | both |
+| `domains/platform/debugging.md` | `docs/project-wiki/domains/platform/debugging.md` | yes | both |
+| `domains/platform/environments-and-deployment.md` | `docs/project-wiki/domains/platform/environments-and-deployment.md` | yes | both |
+| `guidelines/index.md` | `docs/project-wiki/guidelines/index.md` | yes | both |
+| `guidelines/documentation-guidelines.md` | `docs/project-wiki/guidelines/documentation-guidelines.md` | yes | both |
+
+Business domains (`domains/<slug>/`), feature pages, and ADR records are **not** part of the manifest — later steps create them from the templates, for features that actually exist. This file never invents an example domain or feature page.
+
+## 4. Values to resolve (init and repair)
+
+Detected, not asked — show them in the announce line so the user can object:
+
+| Placeholder | How to read it |
+|---|---|
+| `{{PROJECT_NAME}}` | `Read composer.json` → top-level `"name"`. If it starts with `shopware/` (e.g. `shopware/production`) or is absent → use the repository folder name (`basename` of the repo root). |
+| `{{SHOPWARE_VERSION}}` | `grep -n -A3 '"name": "shopware/core"' composer.lock` → the `"version"` line; if no `composer.lock`, `Read composer.json` → `require."shopware/core"` constraint. Normalise: strip `^ ~ v`, keep the first three numeric segments (`6.7.13.0` → `6.7.13`, `~6.6.10.0` → `6.6.10`, `v6.7.13` → `6.7.13`, `^6.7` → `6.7`). Used as `Shopware <X.Y.Z>`. |
+| `{{DATE}}` | Today, `YYYY-MM-DD`. |
+
+Replace exactly these three tokens and nothing else — the Jekyll flavor's `adr/index.md` contains Liquid `{{ p.date }}` expressions that must survive untouched.
+
+Two Jekyll-only values come from the §2 answers and are edited into `_config.yml` after substitution:
+
+- `title:` — the answer to question 3.
+- `baseurl:` — **defaults to `"/<repo>"`, not to empty.** An empty `baseurl` on a GitHub Pages project site makes every theme asset 404: the navigation still renders, the build still succeeds, and the site is served as unstyled HTML with no error anywhere. Empty is therefore the unsafe default and is used only where it is provably right.
+
+  Derive `<repo>` from `git remote get-url origin` (basename, `.git` stripped) and resolve in this order:
+
+  | Case | `baseurl` |
+  |---|---|
+  | A remote exists and `<repo>` is **not** `<org>.github.io` — a project site | `"/<repo>"` |
+  | `<repo>` is `<org>.github.io` — a user/org site served at the domain root | `""` |
+  | Question 2 answered "GitHub Actions build" | `""` |
+  | No git remote at all | `""`, and the report says it must be set to `/<repo>` once the wiki is published |
+
+  When the wiki is still nested inside the project repository, the remote found here is the *project's*, not the wiki's — write the value it implies, and add the report line that `baseurl` has to be revisited once the wiki gets its own repository.
+
+  State the resolved value in the announce line either way, so it is visible rather than implicit.
+
+## 5. Write the baseline (delegated)
+
+Spawn **one** `general-purpose` agent via the Agent tool. Everything it needs goes in the brief — it asks nothing and decides nothing:
+
+- mode (init or repair) and the exact list of target paths to write (missing ones only, on repair);
+- the flavor, and per row which source file to read: `README.md`, `index.md`, `adr/index.md` come from `reference/scaffold/vanilla/<path>` on Vanilla, otherwise from `reference/scaffold/<path>`; `_config.yml` is written on Jekyll only; the other 12 always come from the shared `reference/scaffold/<path>`;
+- the three resolved token values, and the `title` / `baseurl` values for `_config.yml`;
+- the rules: read → substitute the three tokens → write; never overwrite an existing file; never touch `domains/<business-domain>/`, feature pages or ADR records; never write outside `docs/project-wiki/`; leave Liquid expressions untouched;
+- what to return: the created/kept table of §7, nothing else.
+
+Announce the run in one line before spawning, naming the flavor and the detected values: "docs/project-wiki/ does not exist — initialising the wiki (Jekyll / GitHub Pages, acme/webshop, Shopware 6.7.13)."
+
+## 6. Drift check (`guidelines/documentation-guidelines.md` already present)
+
+Skip when `guidelines/documentation-guidelines.md` was created in this run. Otherwise `Read` both `docs/project-wiki/guidelines/documentation-guidelines.md` and `reference/scaffold/guidelines/documentation-guidelines.md`; ignore the lines `last_synced:` and `verified_against:` and the three placeholder tokens (compare by reverse-substituting the resolved values, or by dropping those lines). If the wiki copy still differs in rules or wording → do **not** overwrite; record "documentation guidelines drift" for the report (one line, which `##` section differs). The wiki copy stays authoritative for readers; the drift is information for the maintainers.
+
+Skip any `_config.yml` comparison on Vanilla — the file legitimately does not exist there, that is not drift.
+
+**Legacy wikis** — `docs/project-wiki/CONVENTIONS.md` exists and `guidelines/documentation-guidelines.md` does not: report "legacy CONVENTIONS.md found, not migrated" and ask once, same tool: "Migrate docs/project-wiki/CONVENTIONS.md to guidelines/documentation-guidelines.md?" — **Yes**: write `reference/scaffold/guidelines/documentation-guidelines.md` (tokens substituted, carrying over nothing from the old file) then delete `docs/project-wiki/CONVENTIONS.md`; **No (Recommended)**: leave both alone, repeat the report next run. Never delete `CONVENTIONS.md` without that explicit yes.
+
+## 7. Report
+
+One compact table, paths only:
+
+```
+| result | file |
+|---|---|
+| created | docs/project-wiki/domains/platform/logging.md |
+| kept | 15 files |
+| drift | docs/project-wiki/guidelines/documentation-guidelines.md (Frontmatter) |
+| flavor | Jekyll / GitHub Pages · baseurl "/acme-docs" |
+```
+
+Collapse `kept` into a count; list every `created` file; add the `drift` row (with the differing section) only when §6 found one; add the `flavor` row only on init, with the `baseurl` decision after it. On `--setup` this table is the whole run's report. Otherwise it is the first line of the report in step 7 of `SKILL.md`, and the run continues at step 1.
+
+On Jekyll, always name the resolved `baseurl` in that row, and when it was left empty add one line saying it must become `/<repo>` before the site is published as a project site — otherwise the site builds, the navigation renders, and every stylesheet 404s with no error to show for it.
+
+## Dry-run examples
+
+- **Empty project, no flag** (`composer.json` name `acme/webshop`, lock `6.7.13.0`, origin `git@github.com:acme/webshop-docs.git`): detect → no directory → ask §2 → Jekyll + own repository + default title → resolve `acme/webshop`, `6.7.13`, today, `baseurl: "/webshop-docs"` → announce → sub-agent writes 16 files → table: 16 created, `flavor | Jekyll / GitHub Pages · baseurl "/webshop-docs"`, no drift check (`guidelines/documentation-guidelines.md` was just created) → continue at step 1.
+- **Empty project, user picks Vanilla**: questions 2–3 are skipped (no `_config.yml` to configure) → 15 writes, overlay files from `reference/scaffold/vanilla/` → table: 15 created, `flavor | Vanilla / plain Markdown` → continue at step 1.
+- **`--setup`, existing wiki with `domains/platform/logging.md` deleted**: repair → flavor derived from `_config.yml` → 1 write → drift check → table: 1 created, kept count, no `flavor` row → stop. Business domains, feature pages and the hand-edited `_config.yml` untouched.
+- **`--setup`, complete wiki**: nothing missing → drift check only → table: N kept → stop.
+- **No flag, complete wiki**: this file is never opened.

package/skills/sw-document-feature/reference/source-mapping.md

@@ -0,0 +1,71 @@
+# Source mapping
+
+How each input lands on the wiki. Condense, never quote; one fact lives in one place.
+
+## PRD (`specs/NNNN-slug.md`, sections as in sw-design-requirements)
+
+| PRD section | Goes to |
+|---|---|
+| Meta table (Status, Confidence) | Nothing — a PRD's readiness is not a feature status |
+| §1 Problem & Goal, "Success looks like" | Domain index feature row → **Why** (one sentence). The feature page's intro prose links there |
+| §2 Scope (in/out) | Business user section (in scope); *Domain notes* or Gotchas for explicit out-of-scope that a reader would expect |
+| §3 Actors & Sales-Channel scope | Decides the **surfaces**: Merchant admin → administration; Guest/Registered/B2B → storefront; External system/Background → surface that triggers it. Sales Channel/language limits → Business user section |
+| §4 Domain Impact, new concepts | Developer › Where (entities) and *Domain notes* in the domain index; new concept names → glossary row |
+| §5 FR-n | Business user section, grouped by workflow, not listed one-per-FR |
+| §6 BR-n, edge cases, error behaviour | Business user (visible behaviour) + Gotchas (surprising rules); a significant BR → Why column, never an ADR unless the user provides one |
+| §7 AC-n | Not restated. Cited by id in Status (`AC-1..AC-n pass` or failing list) and in the NOT BUILT block |
+| §8 Data & Integrations | Developer › Where / Config; direction and source of truth → *Domain notes* |
+| §9 Early tech decisions `[decision]` `[constraint]` `[architect]` | Developer › Decisions, never `adr/` (the PRD skill extracts no ADRs) |
+| §10 Q-n open questions | Report line "open questions" + Gotchas as `_TBD_` if they affect documented behaviour. Never resolved by the skill |
+| §11 C-n clarification log | Already anchored in the PRD; use the decision, not the log |
+| §12 Confidence | Nothing |
+
+## Tech spec (`specs/NNNN-slug-spec.md`, written by sw-design-solution)
+
+| Spec section | Goes to |
+|---|---|
+| Per-AC architectural decision | Developer › Where / Extension points (paths, entities, routes, events, components) |
+| Per-AC implementation plan | Developer › Where only as *paths that exist*; steps are never listed |
+| Per-AC tests / e2e scenarios | Cited in Status evidence; test paths in Debug/observe if they are the fastest way to reproduce |
+| Decision Log (incl. `[architect]`, `(unverified …)`) | Developer › Decisions; unverified ones stay marked `(unverified)`. A line `[adr] <path>` → Developer › Decisions link to the promoted docs ADR, or to the WIP file marked `(WIP, <status>)` (below); `[potential ADR]` lines → report "ADR candidates (not created)" |
+| Dependencies table (`| ADR | Status | Blocks readiness |`) | Nothing beyond the `[adr]` links; status is read from the ADR file, not this table |
+| Toolchain conformance notes | Gotchas (one line) |
+| Open Questions | Report + Gotchas `_TBD_` |
+| Readiness / status | Nothing |
+
+Which surface owns what: entities, migrations, admin modules, Admin API → administration page; Storefront controllers, Twig, Store API, JS plugins → storefront page; the other page links.
+
+## ADR marker (the only spec input that yields an ADR)
+
+A spec Decision Log line `[adr] <path>` (written by sw-design-solution when the user chose *Extract as ADR*) points at `specs/NNNN-slug-adr-<topic>.md`; that **file** is the WIP ADR — the line carries no detail of its own. It becomes a docs ADR only by promotion per `adr-promotion.md` (`accepted` and its required changes found in the code; created once, never overwritten). An `[adr]` path that resolves neither to a WIP file nor to a docs ADR by `id` → report "dangling [adr] links", no page. Lines without `[adr]` never become ADRs, however far-reaching; `[potential ADR]` lines go to the report as "ADR candidates (not created)". Promotion covers every `specs/*-adr-*.md`, not only those the current spec links.
+
+## Verification report (`sw-verify-feature`, in chat)
+
+```
+AC-n | pass / not pass / partly | evidence | note
+Static analysis | pass / fail / not run | …
+DEFECT-n …
+```
+
+- All `pass` + code found → `status: built`; Status: "`built` — verified YYYY-MM-DD (AC-1..AC-n pass)".
+- Any `not pass`/`partly` → `partially-built`; ⚠️ PARTIALLY BUILT block lists those ACs with the note; `DEFECT-n` summarised in Gotchas without file:line dumps.
+- `Static analysis | fail` → one Gotchas line; it does not change AC status.
+- Use the report's date as the verification date; `last_synced` is still today.
+
+## Chat mode (no PRD/spec)
+
+Extract from the discussion, in this order, and mark anything not stated as `_TBD_`:
+
+1. **What** — the capability in one sentence per surface → the page's intro prose.
+2. **Why** — the business goal → domain index Why column. If absent, ask once (a structured question tool if you have one — Claude Code: `AskUserQuestion`; Codex: `request_user_input` — free text is fine) and anchor it.
+3. **AC-like statements** — "must", "should", "when X then Y", Given/When/Then → cite as `AC-a`, `AC-b` (letters, to signal they are chat-derived) in Status; do not invent numbers.
+4. **Names** for the built-check — extension, entities, routes, keys.
+5. **Decisions** the user stated → Developer › Decisions with `(from chat, YYYY-MM-DD)`. Only an ADR the user explicitly provides or asks to record ("record this as an ADR") → `adr/` per `page-rules.md` "ADRs".
+
+Frontmatter: `prd: null`, `spec: null`. A verification report pasted in chat still counts (above). If the gate finds nothing on disk, the status after enforce is `not-built`, and the NOT BUILT block says "no PRD, spec, or code in this repo".
+
+## Domain index row
+
+`| Feature | Why | [page](administration/<slug>.md) or — | [page](storefront/<slug>.md) or — |`
+
+Four columns, no spec and no status. The wiki is the durable record and `specs/` is working material that goes away once a feature is documented, so the source paths live only in the feature page's `spec`/`prd` front matter. A documented feature is a built feature by default, so the overview does not repeat a status that is `built` on every row — the exception is carried where a reader meets it: the page's own `status` front matter and its ⚠️ block, written when the user enforced documentation of something not built.

package/skills/sw-document-feature/reference/templates/adr.md

@@ -0,0 +1,26 @@
+---
+title: <Decision title>
+nav_order: <n>
+parent: Decision records
+date: YYYY-MM-DD
+area: <platform|checkout|catalogues|orders|customers|process>
+tags: [<tag>]
+authors: [<Name>]
+status: <accepted|superseded|deprecated>
+---
+
+# <Decision title>
+
+Shopware ADR format. File name: `adr/YYYY-MM-DD-<kebab-title>.md`. The adr index in [../adr/index.md](../adr/index.md) — its regenerated TOC block, and additionally a Liquid-rendered table on wikis using the Jekyll flavor — picks it up automatically. Filled only for an ADR the user provides in chat as accepted — never generated from the skill's own judgment; a not-yet-accepted ADR belongs in `specs/*-adr-*.md` as WIP. WIP files are not written from this template; they are promoted per `reference/adr-promotion.md` once accepted and built (same frontmatter plus `id`, `prd`, `spec`, `owner`, `promoted_from`, `promoted`, body carried over). Use `area: process` for project/process decisions and a `business` tag for business rules; routine business rationale belongs in the domain index "Why" column instead.
+
+## Context
+
+<The situation and forces. Link the spec, PRD, or feature page that triggered it.>
+
+## Decision
+
+<What we decided, present tense. One decision per ADR.>
+
+## Consequences
+
+<Positive, negative, follow-ups. If this supersedes another ADR, link it and set that ADR's status to superseded.>

package/skills/sw-document-feature/reference/templates/domain-index.md

@@ -0,0 +1,36 @@
+---
+title: <Domain name>
+has_children: true
+nav_order: <n>
+parent: Domains
+type: domain
+purpose: <One sentence: what this domain covers.>
+scope: <What belongs here and what belongs to neighbouring domains.>
+last_synced: YYYY-MM-DD
+verified_against: Shopware 6.7.13
+resync: sw-document-feature updates the feature table.
+tags: [<domain-slug>, domain, index]
+---
+
+# <Domain name>
+
+<1–2 sentences: what this domain covers, what belongs to a neighbouring domain instead.>
+
+## Features
+
+| Feature | Why (business goal) | Administration | Storefront |
+|---|---|---|---|
+| <Feature> | <One sentence — the single source for the why; feature pages link here.> | [page](administration/<slug>.md) or — | [page](storefront/<slug>.md) or — |
+
+## Domain notes
+
+<Cross-feature facts: shared entities, invariants, what this domain deliberately does not do.>
+
+## Related
+
+- [../index.md](../index.md)
+
+---
+
+*Scope: <one line>. · Last synced: YYYY-MM-DD · Verified against Shopware 6.7.13 · Re-sync: reconcile the
+feature table with `domains/<domain-slug>/*/`.*

package/skills/sw-document-feature/reference/templates/feature-page.md

@@ -0,0 +1,64 @@
+---
+title: "<Feature name> (<Administration|Storefront>)"
+nav_order: <n>
+parent: <Domain title>
+grand_parent: Domains
+domain: <domain-slug>
+surface: <administration|storefront>
+feature: <feature-slug>
+status: <built|partially-built|planned|not-built|deprecated>
+extension: <PluginName in custom/, composer package vendor/name, or null>
+spec: <specs/NNNN-slug-spec.md or null>
+prd: <specs/NNNN-slug.md or null>
+verified_against: Shopware 6.7.13
+last_synced: YYYY-MM-DD
+tags: [<domain-slug>, <surface>]
+related: [../<other-surface>/<feature-slug>.md, ../index.md]
+---
+
+# <Feature name> — <Administration|Storefront>
+
+<1–2 sentences: what on THIS surface. For the why, link to the domain index feature entry: [Domain index](../index.md#features). Storefront half may link to the Administration half instead of restating.>
+
+## Status
+
+<If built: "`built` — verified YYYY-MM-DD (AC-1..AC-n pass).">
+
+<If NOT built / planned / partially built, this block is mandatory:>
+> ⚠️ NOT BUILT
+>
+> **What exists in the repo:** <PRD/spec/flag/partial code, with paths>
+> **What is missing:** <what sw-document-feature could not find under custom/>
+> **Reference:** <spec ACs, verification report date or "not run">. Checked against the repo on YYYY-MM-DD.
+>
+> Do not describe this feature as available. Everything below is the *intended* design from the spec.
+
+## Business user
+
+<How it is used on THIS surface only. Administration: menu path, fields, workflows, ACL. Storefront: what the shopper sees and does. Concise.>
+
+## Developer
+
+- **Where:** <extension, paths, entities, modules, routes>
+- **Extension points used:** <events, decorators, entity extensions, cart processors, Twig blocks, component overrides>
+- **Decisions:** <key choices and why; link ADRs>
+- **Config:** <keys, flags — link ../../platform/configuration.md>
+- **Debug/observe:** <log channel, profiler hints — link ../../platform/logging.md, ../../platform/debugging.md>
+- **Gotchas:** <surprises for the next developer>
+
+No code listings. At most a one-line snippet if unavoidable.
+
+## Related
+
+- Counterpart surface: [../<other-surface>/<feature-slug>.md](../index.md)
+- Domain: [../index.md](../index.md)
+- Spec / PRD / ADRs / platform pages
+
+## Decision Log
+
+<Optional. One line per user decision, override, or status change; append only, never rewrite. Omit the section if empty.>
+- YYYY-MM-DD — <e.g. User enforced documentation although the built-check found no code>
+
+---
+
+*Last synced: YYYY-MM-DD · Verified against Shopware 6.7.13 · Re-sync: re-run `sw-document-feature`.*

package/skills/sw-document-feature/reference/templates/guideline.md

@@ -0,0 +1,42 @@
+---
+title: "<Base or surface guideline file title, matching the platform file>"
+nav_order: <n>
+parent: Guidelines
+merge:
+  <platform-section-anchor>: <override|extend|waive>
+adr: [adr/<date>-<topic>.md]
+tags: [guidelines, platform]
+last_synced: YYYY-MM-DD
+verified_against: Shopware 6.7.13
+---
+
+# <Title>
+
+<1–2 sentences: what this project changes about `<same file name>` in the Shopware platform
+guidelines, and why. Everything not listed here is inherited unchanged — do not restate platform
+rules.>
+
+<!--
+Read the platform file first — `read_doc platform/guidelines/<version>/<file>.md` — and copy the
+real heading anchor for each section you act on into `merge:` above. One `## <heading>` per rule
+below, anchor matching a real platform section unless the rule is a pure addition.
+
+override — replaces the platform section in place. Body is the full replacement rule.
+extend    — inserted directly before the platform section; both apply, this one first.
+waive     — replaces the platform section; body states the reason and starts with `WAIVED:`.
+(anchor not in the platform file) — an addition, appended after the last platform section.
+-->
+
+## <Platform section heading, verbatim anchor>
+
+<The project's rule for this section. For `waive`, start with `WAIVED:` and state the reason.>
+
+## Related
+
+- [Guidelines](index.md)
+- ADR: [<id>](../adr/<file>.md) <if `adr:` is set>
+
+---
+
+*Last synced: YYYY-MM-DD · Verified against Shopware 6.7.13 · Re-sync: update when the rule
+changes or the platform file's anchor is renamed by regeneration.*