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

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

@@ -0,0 +1,44 @@
+---
+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: Generated by Jekyll from the files in adr/; 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.
+
+{% assign adrs = site.pages | where_exp: "p", "p.dir contains '/adr/'" | where_exp: "p", "p.name != 'index.md'" | sort: "date" | reverse %}
+{% if adrs.size > 0 %}
+| Date | Title | Area | Status |
+|---|---|---|---|
+{% for p in adrs %}| {{ p.date | date: "%Y-%m-%d" }} | [{{ p.title }}]({{ p.url | relative_url }}) | {{ p.area }} | {{ p.status }} |
+{% endfor %}
+{% endif %}
+
+## 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/baseline/glossary.md

@@ -0,0 +1,55 @@
+---
+title: Glossary
+nav_order: 3
+type: project
+purpose: Map project-specific words to Shopware's official terminology.
+scope: Terms used in PRDs, specs, and docs. Not a Shopware glossary.
+last_synced: {{DATE}}
+verified_against: Shopware {{SHOPWARE_VERSION}}
+resync: Add a row whenever a PRD introduces a new project term.
+tags: [glossary, terminology]
+---
+
+# Glossary
+
+One vocabulary across PRDs, specs, code and these pages. When the business has its own word for
+something Shopware already names, the Shopware name wins in docs and code — this page records the
+mapping so nobody has to guess.
+
+## Shopware terms we use
+
+| Term | Meaning |
+|---|---|
+| Administration | The merchant back office (Vue application, Admin API) |
+| Storefront | The shopper-facing site (Twig/JS, Store API) |
+| Sales Channel | A storefront/API channel with its own domain, language, currency |
+| Extension | A plugin, app, or theme — say *plugin* only when it is one |
+| Store API / Admin API | The two HTTP APIs; Storefront uses the Store API, Administration the Admin API |
+| Shopping Experiences | The CMS (layouts, blocks, elements) |
+| Flow Builder | Event-driven automation configured in the Administration |
+| Rule Builder | Conditions used by prices, promotions, shipping, payment |
+| Catalogues | Products, categories, properties, manufacturers |
+| Customer group | Customer segmentation used by prices and rules |
+| Dynamic product group | Rule-based product set (product streams) |
+
+## Project terms
+
+<!-- One row per project word that differs from Shopware's. Note which domain owns a custom entity. -->
+
+| Project term (from PRDs) | What it maps to | Notes |
+|---|---|---|
+
+*Nothing recorded yet — add a row whenever a PRD introduces a new project term.*
+
+## Terms we do not use
+
+Don't say **admin panel** or **backend** — say *Administration*. Don't say **frontend** or **shop
+front** — say *Storefront*. Don't say **shop** for a channel — say *Sales Channel*. Don't say
+**plugin** when the thing may be an app or theme — say *Extension*. Don't say **module** or
+**addon** — say *Extension*. Don't say **CMS page** — say *Shopping Experiences layout*.
+
+---
+
+*Scope: project terms and the Shopware terms they map to — not a Shopware glossary. · Last synced:
+{{DATE}} · Verified against Shopware {{SHOPWARE_VERSION}} · Re-sync: add a row whenever a PRD introduces a new
+project term.*

package/skills/sw-document-feature/reference/scaffold/baseline/tech-stack.md

@@ -0,0 +1,48 @@
+---
+title: Tech stack
+nav_order: 2
+type: project
+purpose: The fixed technical baseline every feature is built and verified against.
+scope: Versions, runtime, tooling, environment shape. Not per-feature configuration (see domains/platform/configuration.md).
+last_synced: {{DATE}}
+verified_against: Shopware {{SHOPWARE_VERSION}}
+resync: Update after any Shopware, PHP, or shopware-cli upgrade; bump verified_against on all pages in the same change.
+tags: [baseline, versions]
+---
+
+# Tech stack
+
+What this project runs on. Every feature page is verified against the versions below, so when one
+of them changes, the pages that were verified against the old one become visibly stale.
+
+<!-- Fill from the repo, never from memory: Shopware = composer.lock shopware/core; PHP and Node = the docker-dev image tag in compose.yaml; Database = the database service image; shopware-cli = `shopware-cli --version`. Replace _TBD_ rows only with a verified value; never invent one. -->
+
+## Versions
+
+| Component | Version | Where it comes from |
+|---|---|---|
+| Shopware | {{SHOPWARE_VERSION}} | `composer.json` / `composer.lock` (`shopware/core`) |
+
+*PHP, database, Node and shopware-cli versions not recorded yet — fill from `compose.yaml`,
+`.shopware-project.yml`, and `shopware-cli --version` when known.*
+
+The project is Composer-based, built from the `shopware/production` template.
+
+## Where things live
+
+- Extensions: `custom/plugins/`, `custom/apps/`, `custom/static-plugins/` — see the
+  [extensions inventory](../domains/platform/extensions-inventory.md).
+- Specs and PRDs: `specs/`. This wiki: `docs/project-wiki/`.
+- Local environment and non-local environments:
+  [Environments and deployment](../domains/platform/environments-and-deployment.md).
+
+## Related
+
+- [Glossary](glossary.md)
+- [Platform](../domains/platform/index.md)
+
+---
+
+*Scope: versions and environment shape only. · Last synced: {{DATE}} · Verified against Shopware
+{{SHOPWARE_VERSION}} · Re-sync: compare with `composer.json`, `composer.lock`, `compose.yaml` and
+`.shopware-project.yml` after any upgrade.*

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

@@ -0,0 +1,55 @@
+---
+title: Domains
+has_children: true
+nav_order: 4
+type: index
+purpose: Map of business domains and their features on each surface.
+scope: All domains under docs/project-wiki/domains/. Feature rows are summaries; detail lives on the feature pages.
+last_synced: {{DATE}}
+verified_against: Shopware {{SHOPWARE_VERSION}}
+resync: sw-document-feature updates the feature columns; check rows against each domain index.
+tags: [index, domains]
+---
+
+# Domains
+
+Feature documentation is grouped by business domain. Pick a domain, then the surface the user acts
+on — Administration for the merchant, Storefront for the shopper.
+
+<!-- sw-document-feature adds a row when it creates a domain. Only domains that have a directory appear here. -->
+
+| Domain | Purpose | Administration | Storefront |
+|---|---|---|---|
+| [Platform](platform/index.md) | Cross-cutting infrastructure, extensions, configuration, observability | — | — |
+
+Each feature carries its own status on the domain page it belongs to.
+
+## Canonical domains
+
+Domains are created on demand from this list — never invent a slug outside it without an ADR
+(`area: process`). A domain only appears in the table above once it has a directory here. Guidance:
+`reference/domain-guidelines.md` in the `sw-document-feature` skill.
+
+| Slug | Domain | Covers |
+|---|---|---|
+| `catalogues` | Catalogues | Products, variants, categories, properties, manufacturers, Dynamic product groups, availability |
+| `checkout` | Checkout | Cart, shipping and payment selection, order placement |
+| `orders` | Orders | Post-checkout order lifecycle, documents, returns, states |
+| `customers` | Customers | Accounts, registration, Customer groups, addresses, B2B roles |
+| `content` | Content | Shopping Experiences layouts, media, SEO, snippets/translations |
+| `marketing` | Marketing | Promotions, newsletters, product reviews, cross-selling |
+| `sales-channels` | Sales Channels | Sales Channel setup, domains, languages, currencies, countries, taxes |
+| `automation` | Automation | Flow Builder flows, Rule Builder rules, scheduled tasks, mail templates |
+| `settings` | Settings | System settings and merchant configuration that no other domain owns |
+| `integrations` | Integrations | ERP/PIM/payment/shipping connectors, imports/exports, webhooks |
+| `platform` | Platform | Cross-cutting infrastructure (no features, no surfaces) |
+
+## Adding a domain
+
+Create `domains/<slug>/index.md` from `reference/templates/domain-index.md` in the `sw-document-feature` skill, add a row above and in the [wiki home](../index.md) domain table.
+
+---
+
+*Scope: domain level only — feature detail lives on the feature pages. · Last synced: {{DATE}} ·
+Verified against Shopware {{SHOPWARE_VERSION}} · Re-sync: reconcile with each `domains/<domain>/index.md` feature
+table.*

package/skills/sw-document-feature/reference/scaffold/domains/platform/configuration.md

@@ -0,0 +1,54 @@
+---
+title: Configuration
+nav_order: 3
+grand_parent: Domains
+parent: Platform
+type: platform
+purpose: Where each kind of setting lives and how features expose their configuration.
+scope: Environment variables, system config keys, feature flags. Values are examples, never real secrets.
+last_synced: {{DATE}}
+verified_against: Shopware {{SHOPWARE_VERSION}}
+resync: sw-document-feature adds rows for new config keys found in a spec; check against each extension's config.xml.
+tags: [platform, configuration, feature-flags]
+---
+
+# Configuration
+
+One lookup for where a given setting lives, so nobody has to grep the codebase for it.
+
+## Layers
+
+<!-- Adjust the "Where" column to this project; keep the three layers. Fill "Feature flags" from config/packages/ once one is registered. -->
+
+| Layer | Used for | Where |
+|---|---|---|
+| Environment variables | Infrastructure (DB, mailer, search, URLs) | `.env`, `.env.local`, `env.example` |
+| System config (`bin/console system:config:*`) | Merchant-editable settings, per Sales Channel | Administration → Settings → Extensions |
+
+## System config keys
+
+<!-- One row per key an extension exposes: `<Extension>.config.<key>`. Link the feature page that uses it. Never put real values or secrets here. -->
+
+| Key | Domain | Default | Notes |
+|---|---|---|---|
+
+*No project-specific config keys recorded yet.*
+
+## Feature flags
+
+<!-- One row per flag; Owner links the domain index. Flags gate everything with status partially-built. -->
+
+| Flag | Default | Owner |
+|---|---|---|
+
+*No feature flags recorded yet.*
+
+## Related
+
+- [Environments and deployment](environments-and-deployment.md), [Debugging](debugging.md)
+
+---
+
+*Scope: project-level config only, values are examples, never real secrets · Last synced: {{DATE}} ·
+Verified against Shopware {{SHOPWARE_VERSION}} · Re-sync: diff with `.env`/`.env.local`/`env.example`,
+`config/packages/*.yaml`, and each extension's `config.xml` once extensions exist.*

package/skills/sw-document-feature/reference/scaffold/domains/platform/customization-guidelines.md

@@ -0,0 +1,47 @@
+---
+title: Customization guidelines
+nav_order: 2
+grand_parent: Domains
+parent: Platform
+type: platform
+purpose: How we extend Shopware in this project, so every feature uses the same mechanisms.
+scope: Choice of extension type and extension mechanism. Not a Shopware tutorial — links to Shopware docs for mechanics.
+last_synced: {{DATE}}
+verified_against: Shopware {{SHOPWARE_VERSION}}
+resync: Review when Shopware deprecates an extension mechanism or an ADR changes a rule here.
+tags: [platform, guidelines, extensions]
+---
+
+# Customization guidelines
+
+This is the standard Shopware guidance the project follows by default; no project-specific
+exceptions are recorded yet (see [Decision records](../../adr/index.md)). Enforceable coding
+rules — architecture, code, QA — live in [Guidelines](../../guidelines/index.md), not here.
+
+## Extension type
+
+<!-- State the project's choice and link the ADR that made it once one is recorded, e.g. plugins for owned code, apps for third-party integrations, one theme for look and feel. Until then, this is Shopware's own default guidance. -->
+
+- Prefer an app where it suffices (no server-side code, distributable via the Store).
+- Otherwise a plugin (owned, deployed code).
+- Reach for a theme only for pure look-and-feel — never for business logic.
+
+## Preferred mechanisms, in order
+
+<!-- Keep this an ordered list of "reach for X before Y" with one line of rationale each. Adjust once an ADR overrides a step. -->
+
+1. Events and subscribers, over overriding core.
+2. Service decoration (abstract class, thin decorator), over overriding core.
+3. Entity extensions, over core schema changes.
+4. Twig block overrides in the extension, over copying core templates.
+
+## Related
+
+- [Guidelines](../../guidelines/index.md), [Extensions inventory](extensions-inventory.md), [Debugging](debugging.md)
+- Shopware docs: plugin fundamentals, decorating services, entity extensions (via ShopwareDevKnowledgeBase MCP).
+
+---
+
+*Scope: choice of extension type and mechanism, not a Shopware tutorial · Last synced: {{DATE}} ·
+Verified against Shopware {{SHOPWARE_VERSION}} · Re-sync: review when Shopware deprecates a mechanism or an ADR
+changes a rule here.*

package/skills/sw-document-feature/reference/scaffold/domains/platform/debugging.md

@@ -0,0 +1,55 @@
+---
+title: Debugging
+nav_order: 5
+grand_parent: Domains
+parent: Platform
+type: platform
+purpose: How to observe and debug this project locally, and where to look first for common failures.
+scope: Local development. Production incident handling lives in environments-and-deployment.md.
+last_synced: {{DATE}}
+verified_against: Shopware {{SHOPWARE_VERSION}}
+resync: Update when the local setup or tooling changes (see baseline/tech-stack.md).
+tags: [platform, debugging, profiler, xdebug]
+---
+
+# Debugging
+
+Where to look first when something breaks locally, and which tool answers which question.
+
+## Tools
+
+<!-- Keep the generic Shopware tools; add the project's container/service names, ports and IDE settings once known. -->
+
+- **Symfony profiler** at `/_profiler` when `APP_ENV=dev`; Store API and Admin API requests appear there too.
+- **Logs**: see [Logging](logging.md).
+- **`bin/console`** for any CLI diagnostics (`bundle:dump`, `cache:clear`, `database:migrate`, …).
+- **shopware-cli**: `shopware-cli project ci` for the full lint/static-analysis run, `shopware-cli extension validate --full` per extension.
+
+Xdebug config is not recorded in this project yet — fill in the container, `XDEBUG_MODE`, and IDE
+server name once set up.
+
+## Common failure lookups
+
+<!-- Add a row whenever a feature page's Gotchas reveal a recurring symptom; link the feature page. -->
+
+| Symptom | Look first |
+|---|---|
+| Administration module missing after change | `bin/console bundle:dump` + rebuild; check the extension's `main.js` entry and ACL privileges |
+| Storefront template change not visible | `bin/console cache:clear`, `theme:compile`; confirm the block lives in the domain extension, not the theme |
+| Custom entity not found / 500 on Admin API | migration ran? `bin/console database:migrate --all`; entity definition registered in `services.yaml` |
+| Flow not firing | `business_events` log; is the event registered as a business event? |
+
+## Surface tips
+
+- Administration: Vue devtools work on the dev build; the Admin API request log is in the profiler.
+- Storefront: `?_profiler` on any page; Twig template names visible via the profiler's Twig panel.
+
+## Related
+
+- [Configuration](configuration.md), [Customization guidelines](customization-guidelines.md)
+
+---
+
+*Scope: local development, production incidents live in environments-and-deployment.md ·
+Last synced: {{DATE}} · Verified against Shopware {{SHOPWARE_VERSION}} · Re-sync: re-run each tip on a fresh
+checkout after upgrades.*

package/skills/sw-document-feature/reference/scaffold/domains/platform/environments-and-deployment.md

@@ -0,0 +1,49 @@
+---
+title: Environments and deployment
+nav_order: 6
+grand_parent: Domains
+parent: Platform
+type: platform
+purpose: Which environments exist, how a build reaches them, and how to roll back.
+scope: Process and topology. No hostnames or credentials.
+last_synced: {{DATE}}
+verified_against: Shopware {{SHOPWARE_VERSION}}
+resync: Update when the CI pipeline or environment list changes.
+tags: [platform, deployment, environments]
+---
+
+# Environments and deployment
+
+<!-- List every environment defined in .shopware-project.yml or the CI config, local first. Fill from the repo, never invent one. -->
+
+*No environment beyond `local` is recorded for this project yet.*
+
+## Local stack
+
+<!-- One row per service the local stack exposes, read from compose.yaml / docker-dev; ports and addresses are project facts, not examples. -->
+
+*Local services not recorded yet — see [Tech stack](../../baseline/tech-stack.md) for how to read them from `compose.yaml`.*
+
+Component versions (PHP, Node, Database, Shopware) live on
+[Tech stack](../../baseline/tech-stack.md) — not repeated here.
+
+## Deployment flow
+
+<!-- Numbered steps from CI to running: build (shopware-cli project ci / build), artifact, target routine (migrations, plugin:refresh/update, theme:compile, cache warmup), rollback strategy. -->
+
+*No deployment pipeline is recorded in this repo yet.*
+
+## Rules
+
+- No manual changes on non-local containers.
+- Feature flags (see [Configuration](configuration.md)) gate anything with `status: partially-built`.
+
+## Related
+
+- [Tech stack](../../baseline/tech-stack.md), [Logging](logging.md)
+
+---
+
+*Scope: process and topology, no hostnames or credentials · Last synced: {{DATE}} · Verified
+against Shopware {{SHOPWARE_VERSION}} · Re-sync: update when a CI pipeline or a new environment is added to
+`.shopware-project.yml`.*

package/skills/sw-document-feature/reference/scaffold/domains/platform/extensions-inventory.md

@@ -0,0 +1,40 @@
+---
+title: Extensions inventory
+nav_order: 1
+grand_parent: Domains
+parent: Platform
+type: platform
+purpose: The authoritative list of custom Extensions (plugins, apps, themes) in this project and which domain owns each.
+scope: custom/plugins, custom/apps, custom/static-plugins, and vendor-installed store extensions that deliver project features. Not Shopware core.
+last_synced: {{DATE}}
+verified_against: Shopware {{SHOPWARE_VERSION}}
+resync: sw-document-feature adds a row when a spec introduces a new extension; verify with `bin/console plugin:list` and `app:list`.
+tags: [platform, extensions, inventory]
+---
+
+# Extensions inventory
+
+Every Extension this project ships, and which domain owns it. If an extension is not listed here, it is not ours.
+
+<!-- One row per extension. Type = plugin | app | theme | package (vendor-installed). Path = custom/... or vendor/... Owning domain links the domain index. -->
+
+| Extension | Type | Path | Owning domain | Depends on | Purpose | Notes |
+|---|---|---|---|---|---|---|
+
+*No extensions installed yet — `custom/plugins/`, `custom/apps/` and `custom/static-plugins/` are
+all empty.*
+
+## Rules
+
+<!-- Record the project's own naming and ownership rules here, e.g. one plugin per domain group, a shared core plugin for cross-cutting code, technical-name prefix for config keys and log channels. Keep them as rules, not history — history goes to adr/. -->
+
+- Every extension that ships project functionality requires a row here, including vendor-installed ones.
+- An extension serving more than one domain records the sharing in the Notes column.
+- Cross-cutting code (logging, feature flags, shared traits) goes into the platform-level extension named here, never into a business-domain extension. See [Customization guidelines](customization-guidelines.md).
+
+---
+
+*Scope: custom/plugins, custom/apps, custom/static-plugins, and vendor-installed store extensions,
+not Shopware core · Last synced: {{DATE}} · Verified against Shopware {{SHOPWARE_VERSION}} · Re-sync:
+`bin/console plugin:list`, `bin/console app:list`, `ls custom/plugins custom/apps
+custom/static-plugins` vs this table.*

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

@@ -0,0 +1,39 @@
+---
+title: Platform
+has_children: true
+nav_order: 2
+parent: Domains
+type: domain
+purpose: Cross-cutting application infrastructure shared by every business domain.
+scope: Extensions inventory, customization rules, configuration, logging, debugging, environments. No business features.
+last_synced: {{DATE}}
+verified_against: Shopware {{SHOPWARE_VERSION}}
+resync: Review after each Shopware upgrade or infrastructure change; each sub-page has its own resync rule.
+tags: [platform, infrastructure, index]
+---
+
+# Platform
+
+Everything a developer needs that is not tied to a single business feature. Unlike business
+domains, Platform has no Administration/Storefront split and no feature pages — anything a
+merchant or shopper can see belongs to a business domain, not here.
+
+| Page | Answers |
+|---|---|
+| [Extensions inventory](extensions-inventory.md) | Which custom extensions exist and who owns them |
+| [Customization guidelines](customization-guidelines.md) | How we extend Shopware here (plugin vs app, decoration, events, theme) |
+| [Configuration](configuration.md) | Environment variables, system config keys, feature flags |
+| [Logging](logging.md) | Channels, destinations, levels, correlation |
+| [Debugging](debugging.md) | Profiler, Xdebug, common failure lookups |
+| [Environments and deployment](environments-and-deployment.md) | Environments, build, deploy, rollback |
+
+## Related
+
+- [Tech stack](../../baseline/tech-stack.md)
+- [Decision records](../../adr/index.md)
+
+---
+
+*Scope: infrastructure and conventions only, no business features · Last synced: {{DATE}} ·
+Verified against Shopware {{SHOPWARE_VERSION}} · Re-sync: walk the pages below after upgrades; `sw-document-feature`
+only touches the extensions inventory and configuration.*

package/skills/sw-document-feature/reference/scaffold/domains/platform/logging.md

@@ -0,0 +1,46 @@
+---
+title: Logging
+nav_order: 4
+grand_parent: Domains
+parent: Platform
+type: platform
+purpose: Which log channels exist, where they go, and how to correlate entries.
+scope: Application logs from custom extensions and Shopware. Not infrastructure/container logs.
+last_synced: {{DATE}}
+verified_against: Shopware {{SHOPWARE_VERSION}}
+resync: Update when an extension registers a new Monolog channel (config/packages/monolog.yaml).
+tags: [platform, logging, observability]
+---
+
+# Logging
+
+Which log channel carries what, and where it ends up — so you look in the right file first.
+
+## Channels
+
+<!-- Shopware's own channels first (app, business_events), then one row per project channel. Destination = file path or stream, no hostnames. -->
+
+| Channel | Emitted by | Level (prod) | Destination |
+|---|---|---|---|
+| `app` | Shopware core | `error` | `var/log/prod.log`, stderr in containers |
+| `business_events` | Flow Builder, mail | `info` | `var/log/business_events.log` |
+
+*No project-specific log channel is recorded yet.*
+
+Local (`APP_ENV=dev`): everything at `debug`, also in the Symfony profiler.
+
+## Conventions
+
+<!-- Context fields every entry carries (sales_channel_id, order_number…), what must never be logged (customer PII), correlation id handling, which channel a feature must use. -->
+
+*No project-specific logging conventions recorded yet.*
+
+## Related
+
+- [Debugging](debugging.md), [Environments and deployment](environments-and-deployment.md)
+
+---
+
+*Scope: application logs from custom extensions and Shopware, not infrastructure/container logs ·
+Last synced: {{DATE}} · Verified against Shopware {{SHOPWARE_VERSION}} · Re-sync: compare with
+`config/packages/monolog.yaml` when an extension registers a new channel.*

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

@@ -0,0 +1,102 @@
+---
+title: Documentation guidelines
+nav_order: 1
+parent: Guidelines
+tags: [guidelines, documentation]
+last_synced: {{DATE}}
+verified_against: Shopware {{SHOPWARE_VERSION}}
+type: reference
+purpose: Reader-facing rules every page under docs/project-wiki/ follows.
+scope: Structure, frontmatter, status vocabulary, terminology. Skill internals live in the sw-document-feature skill.
+resync: Update when a page type, frontmatter field, or status value changes; record structural changes as an ADR with area process.
+---
+
+# Documentation guidelines
+
+The rules every page here follows, whether a person or the `sw-document-feature` skill wrote it.
+This file has no Shopware platform counterpart — it is project-only and served as is, never merged.
+
+## Page shape
+
+Every page opens with its title, then one or two sentences of plain prose saying what the page is
+for. Maintenance metadata (scope, last synced, verified against, how to re-sync) sits in a single
+italic line at the *bottom* of the page, not above the content. Breadcrumbs and the sidebar are
+rendered by the theme from the navigation front matter — never write them into the page body.
+
+Keep pages short: one topic per page, no paragraph longer than about four lines, prefer a table or
+bullets to prose. If a section would only contain a placeholder, leave it out until there is
+something true to write.
+
+## Folders and surfaces
+
+One page per surface: `domains/<domain>/administration/<feature>.md` and
+`.../storefront/<feature>.md`, same slug on both halves, never merged. The *why* lives only in the
+domain index feature table; pages link to `../index.md#features`. `domains/platform/` is the
+cross-cutting domain, and has no surfaces.
+
+## Page types
+
+| Type | Path | Template (in the `sw-document-feature` skill) |
+|---|---|---|
+| Feature page | `domains/<domain>/<surface>/<feature>.md` | `reference/templates/feature-page.md` |
+| Domain index | `domains/<domain>/index.md` | `reference/templates/domain-index.md` |
+| Platform page | `domains/platform/<topic>.md` | no template — breadcrumb, prose intro, content sections, footer line |
+| ADR | `adr/YYYY-MM-DD-title.md` | `reference/templates/adr.md` |
+| Guideline | `guidelines/<file>.md` (no version folder — applies to the installed Shopware version) | `reference/templates/guideline.md` |
+
+## Frontmatter
+
+- All pages: `title`, `nav_order`, `tags[]` (plus `parent`/`grand_parent` when nested); durable pages also `type` (index|project|platform|domain|reference), `purpose`, `scope`, `resync`, `last_synced` (YYYY-MM-DD), `verified_against` (`Shopware <X.Y.Z>`).
+- Feature pages: `domain`, `surface` (administration|storefront), `feature` (slug), `status`, `extension` (name in `custom/`, composer package, or null), `spec`, `prd` (path or null), `related[]`.
+- ADRs: `title`, `date`, `area` (domain slug | platform | process), `tags[]`, `authors[]`, `status` (accepted|superseded|deprecated — `proposed`/`rejected` exist only in WIP files under `specs/`); exempt from `last_synced`/`verified_against`. Pages promoted from `specs/*-adr-*.md` additionally carry `id`, `prd`, `spec`, `owner`, `promoted_from` (the specs path), `promoted` (date); status changes after promotion are made here by people.
+- Guideline files: `title`, `nav_order`, `parent: Guidelines`, `tags[]`, `last_synced`, `verified_against` (per above), plus optional `merge` (map of platform section anchor → `override`\|`extend`\|`waive`) and optional `adr` (list of `adr/<date>-<topic>.md` paths). No `grand_parent`, no `versions` — a guideline file is never nested deeper than `Guidelines`, and it applies to the one installed Shopware version recorded in `verified_against`.
+
+Merge modes, applied per `##` heading anchor against the matching platform guideline file:
+
+| Mode | Effect |
+|---|---|
+| `override` | Replaces the platform section in place. |
+| `extend` | Inserted directly before the platform section; both apply, project section first. |
+| `waive` | Replaces the platform section; the project body states the reason and starts with `WAIVED:`. |
+| (anchor not in the platform file) | An addition, appended after the last platform section. |
+| (anchor matches a platform section, no declared mode) | Treated as `override` and flagged. |
+
+A `*-guidelines.md` file with no platform counterpart — like this one — is a project-only file, served as is; `merge` does not apply to it.
+
+## Status
+
+- Feature: `built` (code present, all ACs verified pass) · `partially-built` (code present, verification missing or failing) · `planned` (PRD/spec only) · `not-built` (nothing in the repo) · `deprecated` (removed or replaced).
+- Pages not `built` carry a ⚠️ status block in *Status*, directly after the intro prose.
+
+## Reference code, don't restate it
+
+No code listings, class lists, or Twig markup. A *Developer* section contains exactly: where it lives (extension, paths, entities), extension points used, key decisions and why, configuration, how to debug/observe, gotchas. An append-only `## Decision Log` may follow *Related*.
+
+## Where decisions go
+
+Feature-level technical decisions → the *Developer › Decisions* bullets of the feature page. Business rules → the "Why" column of the domain index feature table. `adr/` (with `area:`, tag `business` for business rules) is the single source of truth for accepted and built decisions: WIP ADRs are drafted by `sw-design-solution` into `specs/*-adr-*.md` on a person's confirmation and promoted here once accepted and implemented, or provided by a person as accepted; ADRs are never generated by tooling. An accepted ADR that changes a coding rule → edit the project guideline file it applies to (`guidelines/<file>.md`, served as `guidelines/<version>/<file>.md`), citing the ADR in its `adr:` frontmatter key — never restated only in the ADR.
+
+## Wiki mechanics
+
+- Folder landing pages are `index.md`; relative links only, never absolute repo paths as links.
+- Navigation front matter drives the sidebar: `nav_order` on every page, plus `parent` and
+  `grand_parent` for pages nested under a section (three levels at most), and `nav_exclude: true` for
+  a page that should stay out of the menu. `title` is the label shown in the sidebar, so it is kept
+  short and unique — `parent` references match it exactly.
+- No page carries a `layout` key: the layout is applied site-wide from `_config.yml` (`defaults:`),
+  so pages stay readable as plain Markdown with or without a build.
+- Durable pages carry `last_synced`/`verified_against`; older than 90 days or behind the installed
+  Shopware version means stale. `adr/index.md` keeps a generated table of contents (between
+  `<!-- adr-toc:start -->` / `<!-- adr-toc:end -->`, rewritten by the skill) next to its Liquid loop
+  on wikis using the Jekyll flavor; text outside the markers is hand-maintained.
+
+## Terminology
+
+Terminology is Shopware's — see the [glossary](../baseline/glossary.md), including "terms we do not use".
+
+---
+
+*Scope: structure, front matter, status vocabulary and terminology — skill internals live in
+the `sw-document-feature` skill (`reference/page-rules.md` governs how it fills pages). · Last
+synced: {{DATE}} · Verified against Shopware {{SHOPWARE_VERSION}} · Re-sync: update when a page type, front
+matter field or status value changes; record structural changes as an ADR with `area: process`.*