@webship.co/workspace-typo3 0.0.0-stage → 1.0.8

package/README.md

@@ -1,3 +1,198 @@
-# Temporary Holding Version
+# @webship.co/workspace-typo3
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TYPO3 for the [Webship Workspace](https://github.com/webship/workspace) dashboard: a builder
+that makes a real TYPO3 site in a container, a typo3 console tool for the sites it built, the default
+accounts, the [TYPO3 step pack](https://github.com/webship/typo3-steps) wired into the
+workspace's testing setup, and its AI items — two agents, a skill, a command and a prompt —
+each listed in the workspace folder of its kind.
+
+The workspace is container-based (DDEV by default): a TYPO3 project is a row like any other, so
+the row menus the core draws (start, stop, launch, backup, clone, remove, tests) work on it unchanged.
+
+It is made from the reference platform plugin,
+[`@webship.co/workspace-wordpress`](https://github.com/webship/workspace-wordpress).
+
+## Use it
+
+```bash
+cd ~/workspace
+bash core/scripts/plugins.sh --require github:webship/workspace-typo3   # npm install into the dashboard
+bash core/scripts/plugins.sh --activate typo3                            # plugins.typo3 in settings.yml
+bash core/scripts/plugins.sh --install typo3                             # commands, functions, args, AI items
+bash core/scripts/plugins.sh --configure typo3                           # nothing to configure: it has no settings file
+```
+
+The same four steps are buttons on the dashboard's **Settings → Plugins** page. `--install` is
+idempotent. `--uninstall` removes what it placed; an AI item you edited stays.
+
+Everything the plugin carries lands in the folder it belongs to, when that folder is an active
+workspace folder:
+
+| What | Lands in |
+| --- | --- |
+| `cmd-typo3-project.sh`, `cmd-tools-typo3-cli.sh` | every active sites folder: `dev/`, `test/`, `sandboxes/`, `demos/` |
+| The agents `typo3-site-builder`, `typo3-tester` | `ai-agents/` |
+| The skill `typo3-scenarios` | `ai-skills/` |
+| The command `/typo3-test` | `ai-commands/` |
+| The prompt `typo3-build-and-test` | `ai-prompts/` |
+
+There they are listed like any other item of the folder, and installed into Claude Code from there.
+
+It needs a Webship Workspace 1.0.7 or later.
+
+## What it needs
+
+A workspace starts empty, so the manifest says what else this plugin needs (`needs`):
+
+- one sites folder, for the builder and the tool: `dev`, `test`, `sandboxes`, `demos` (`dev` is the one added when none is there). The folder also carries `cmd-tools-testing.sh` and the Users tools this plugin's hooks answer to.
+- `ai-agents`, `ai-skills`, `ai-commands` and `ai-prompts`: the AI folders its agents, its skill, its command and its prompt are placed in.
+
+`--require` says so, `--activate` and `--install` stop until the workspace has them, and `--with-needs` adds what is missing first:
+
+```bash
+bash core/scripts/plugins.sh --activate typo3 --with-needs   # dev and the four AI folders are required, activated and installed first
+bash core/scripts/plugins.sh --install typo3
+```
+
+Everything the builder runs for a site runs in the site's own container, through the container tool the workspace already needs; the plugin asks for no command of its own on the machine.
+
+A workspace that knows none of this (Webship Workspace 1.0.8 and older) ignores the keys: add a sites folder and the AI folders yourself, then `--install typo3` again. A kind whose folder is not there is skipped, and the install says so.
+
+## What the package holds
+
+| Path | What it is |
+| --- | --- |
+| `commands/cmd-typo3-project.sh` | The builder, in the Build list as **TYPO3 (13.4 LTS)**, installed into every sites folder |
+| `commands/cmd-tools-typo3-cli.sh` | The typo3 console for one project: what the site is, a command, updates, caches, the default accounts |
+| `scripts/functions/fun-typo3.sh` | The bash functions behind both, sourced by bootstrap once installed; the names the core's tools look for (`set_typo3_users`, `add_typo3_users`, `cancel_typo3_users`, `testing_configure_typo3`) |
+| `scripts/args/arg-typo3.sh`, `arg-typo3-cli.sh` | Their argparse; the Build form draws the builder's flags from the first |
+| `testing/site.feature` | The first feature a TYPO3 project gets when testing is set up |
+| `ai/agents/typo3-site-builder.md` | The agent that builds and maintains TYPO3 sites with these commands |
+| `ai/agents/typo3-tester.md` | The agent that writes and runs scenarios with the TYPO3 step pack |
+| `ai/skills/typo3-scenarios/` | The skill: the step pack's phrases by area, the traps found on a real site, three example features |
+| `ai/commands/typo3-test.md` | The slash command `/typo3-test <site>`: set up, match every step, run, report |
+| `ai/prompts/typo3-build-and-test.md` | The prompt: a whole launch command for a new session |
+| `docs/plugin-items-pattern.md` | How a plugin carries its own commands and AI items, and how to prove it |
+| `src/index.ts` | `register(api)`: what the assistant is told about TYPO3 here |
+| `features/typo3.feature` | Scenarios for the dashboard's own browser suite |
+
+The `workspacePlugin` block in `package.json` is the manifest the installer reads.
+
+## The commands
+
+Run them from a sites folder. `--help` is safe on both.
+
+### Build a site
+
+```bash
+cd ~/workspace/dev
+bash cmd-typo3-project.sh mysite --install --add-users
+```
+
+| Flag | What it does |
+| --- | --- |
+| `--version <x>` | The release to create the project from, as a Composer constraint of `typo3/cms-base-distribution`: `^13.4` (the default, TYPO3 13.4 LTS), or a number such as `13.4.20` |
+| `--install` | Set the site up, with the workspace account as its administrator, and add the official Introduction package: a site with pages, content and a search |
+| `--add-users` | With `--install`: add the default accounts, an administrator and an editor |
+| `--bare` | With `--install`: leave the Introduction package out (a backend, and no site or page yet) |
+| `--php-version <x>` | The PHP of the project container (`8.3`) |
+| `--launch` | Open the site when it is ready |
+
+The site answers at `https://mysite.ddev.site`, the backend at `/typo3`. The build runs
+`ddev config --project-type=typo3` with the docroot `public` and the Node.js of the workspace (24),
+creates the project with Composer in the container (`typo3/cms-base-distribution`), and sets it up
+with TYPO3's own `setup` command. The setup is given the container's database values
+(`db` / `db` / `db`), the same in every project, and nothing personal. A project of the same name
+is deleted first.
+
+The Introduction package (`typo3/cms-introduction`, on the Bootstrap Package theme) is the site the
+step pack is written for; with it the build also runs the upgrade wizard its search content needs
+and points the search results at the templates of Indexed Search.
+
+TYPO3 asks for an administrator password of 8 characters or more, with an upper and a lower case
+letter, a digit and a sign: the setup stops when the workspace account's does not pass.
+
+### Work on a site
+
+```bash
+bash cmd-tools-typo3-cli.sh mysite                                    # version, address, sites, backend accounts
+bash cmd-tools-typo3-cli.sh mysite --run "extension:list --active"
+bash cmd-tools-typo3-cli.sh mysite --run "list"                       # every command of the console
+bash cmd-tools-typo3-cli.sh mysite --flush                            # flush every cache
+bash cmd-tools-typo3-cli.sh mysite --update                           # Composer packages, extension setup, caches
+bash cmd-tools-typo3-cli.sh mysite --add-users                        # the default accounts
+bash cmd-tools-typo3-cli.sh mysite --cancel-users                     # delete them
+```
+
+### The default accounts
+
+| Account | Role | Handle in the tests |
+| --- | --- | --- |
+| `administrator` | administrator (not a system maintainer: the Extensions module and the Admin Tools stay with the workspace account) | `admin` |
+| `editor` | the backend group "Advanced editors" (from the Introduction package) | `editor` |
+
+Each has the address `<account>@example.com` and the password of the workspace's other default
+lists. They are for local sites and for tests; the site's own administrator is the workspace
+account and is never written into a test. The row's Users menu (**Add the test users**),
+`bash cmd-tools-add-users.sh mysite typo3` and `bash cmd-tools-cancel-users.sh mysite typo3` add
+and remove the same list. On a site without the Introduction package the editor is created without
+a group.
+
+### Test a site
+
+```bash
+bash cmd-tools-testing.sh mysite                 # webship-js, the step pack, the users registry, a first feature
+bash cmd-tools-testing.sh mysite --run           # run the suite in the container
+bash cmd-tools-testing.sh mysite --run --path tests/features/site.feature
+```
+
+`cmd-tools-testing.sh` is the workspace's own. For a TYPO3 project it also adds
+`@webship-js/typo3-steps` to `package.json`, lists its step definitions in `cucumber.js` after
+webship-js's own, writes the users registry (the handles above, overridable with
+`TYPO3_<HANDLE>_USER` and `TYPO3_<HANDLE>_PASS`), places `tests/features/site.feature` when the
+project has none, and makes sure the default accounts are on the site. Run it again and it adds what
+is missing and keeps what you changed.
+
+## The AI items
+
+`ai/` in the package holds one folder per kind, the manifest's `ai` block names each item, and
+`--install` places it in the workspace folder of that kind.
+
+| Kind | Item | Use it to |
+| --- | --- | --- |
+| Agent | `typo3-site-builder` | Build, update, maintain or remove a TYPO3 site with the commands above, in containers only |
+| Agent | `typo3-tester` | Set the testing stack up, look at the site in the Playwright MCP browser first, write scenarios from the pack's steps and run them; it never creates an account in a suite and never writes a platform name into a step phrase |
+| Skill | `typo3-scenarios` | Write a scenario from phrases that exist: the pack's steps by area (the backend and its modules, the page tree, records and content elements, the public site), the handles of the users registry, the traps found on a real site, and three features that pass on a fresh site |
+| Command | `/typo3-test <site> [feature or @tag]` | Run the suite of a site from inside a session: set up when missing, match every step, run, report what failed and why |
+| Prompt | `typo3-build-and-test` | Start a session that builds a site with the Introduction package, says what it is, sets the testing stack up and runs the first feature |
+
+After `--install` each is in its folder on the dashboard. **Install** there puts an agent, a skill
+or a command into Claude Code (`~/.claude/agents`, `~/.claude/skills`, `~/.claude/commands`), or
+from the command line:
+
+```bash
+cd ~/workspace/ai-agents   && bash cmd-tools-ai-items.sh typo3-tester --install
+cd ~/workspace/ai-skills   && bash cmd-tools-ai-items.sh typo3-scenarios --install
+cd ~/workspace/ai-commands && bash cmd-tools-ai-items.sh typo3-test --install
+```
+
+A prompt is not installed: it is the whole `claude …` launch command of a new session, and the
+dashboard's **New screen** form lists it as a template. By hand, fill the placeholders in and run
+the command of the file from the folder it names.
+
+The items are written for any AI CLI, with Claude Code as the default shape: the frontmatter and
+the file layout are Claude Code's, the body of each item is plain Markdown that names no tool or
+feature of one CLI, a command says in words what its arguments are, and the text between the
+triple quotes of a prompt can be given to another AI CLI as it is.
+
+Every step phrase the items show is checked against the definitions of the step pack and of
+webship-js (`tests/fixtures/step-definitions.txt`), and every command and flag against the
+plugin's own. The shape is the reference's: [`docs/plugin-items-pattern.md`](docs/plugin-items-pattern.md).
+
+## Develop it
+
+```bash
+npm install     # builds dist/ (TypeScript)
+npm run lint
+npm test        # the manifest, the commands, the AI items, the functions against a scaffolded project
+```

package/ai/agents/typo3-site-builder.md

@@ -0,0 +1,114 @@
+---
+name: typo3-site-builder
+description: Use this agent to build, maintain, update or remove a TYPO3 site in the Webship Workspace — a new site from `cmd-typo3-project.sh`, typo3 console work through `cmd-tools-typo3-cli.sh` (extensions, caches, upgrade wizards, updates, the default accounts), start, stop, backup and remove through the workspace's own tools. It works in containers only and never on the host. Invoke for "build a TYPO3 site", "add this extension to <site>", "update TYPO3 on <site>", "add the test accounts", or "remove the TYPO3 sandbox". For writing and running test scenarios, hand over to `typo3-tester`.
+model: fable
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+---
+
+# typo3-site-builder
+
+You build and look after TYPO3 sites in a Webship Workspace (`~/workspace`), a container-based
+workspace (DDEV by default). Everything goes through the `cmd-*.sh` commands of a sites folder
+(`dev/`, `test/`, `sandboxes/`, `demos/`) and through the project's container. The commands come from
+the TYPO3 plugin (`@webship.co/workspace-typo3`); if a folder has no
+`cmd-typo3-project.sh`, the plugin is not installed there: say so, and name the steps
+(`bash core/scripts/plugins.sh --require @webship.co/workspace-typo3`, `--activate typo3`,
+`--install typo3`) instead of working around it.
+
+Read the command before quoting a flag: `bash <command> --help` is always safe.
+
+## Build a site
+
+```bash
+cd ~/workspace/sandboxes                      # or dev, test, demos
+bash cmd-typo3-project.sh mysite --install --add-users
+```
+
+| Flag | What it does |
+| --- | --- |
+| `--version <x>` | The release to create the project from, as a Composer constraint of `typo3/cms-base-distribution`: `^13.4` (the default, TYPO3 13.4 LTS), or a number such as `13.4.20`. |
+| `--install` | Sets TYPO3 up, with the workspace account (`account:` in `core/config/settings.yml`) as its administrator, and adds the official Introduction package: a site with pages, content and a search. Without it the code is there and the installer waits at `/typo3/install.php`. |
+| `--add-users` | With `--install`: the default accounts, `administrator` (an administrator) and `editor` (in the backend group "Advanced editors"). |
+| `--bare` | With `--install`: leaves the Introduction package out. The backend is there; there is no site and no page yet, so the front page answers with an error until you make one. |
+| `--php-version <x>` | The PHP of the project container (`8.3` by default). |
+| `--launch` | Opens the site when it is ready. |
+
+The site answers at `https://<name>.ddev.site`, the backend at `/typo3`. It is a Composer project:
+the docroot is `public/`, the configuration is in `config/`. The builder **deletes a project of the
+same name first**: a build is a clean slate, so never point it at a site somebody still needs. The
+name is a folder, a container project and a host name: short, lowercase, letters and digits.
+
+TYPO3 asks for an administrator password of 8 characters or more, with an upper and a lower case
+letter, a digit and a sign. When the workspace account's does not pass, the setup says so and the
+build stops: do not invent another password, ask for the setting to be changed.
+
+## Work on a site
+
+```bash
+bash cmd-tools-typo3-cli.sh mysite                                  # what it is: version, address, sites, backend accounts
+bash cmd-tools-typo3-cli.sh mysite --run "extension:list --active"
+bash cmd-tools-typo3-cli.sh mysite --run "upgrade:list"
+bash cmd-tools-typo3-cli.sh mysite --flush                          # every cache
+bash cmd-tools-typo3-cli.sh mysite --update                         # the Composer packages, the extension setup, the caches
+bash cmd-tools-typo3-cli.sh mysite --add-users                      # the default accounts
+bash cmd-tools-typo3-cli.sh mysite --cancel-users                   # and away again
+```
+
+`--run "list"` prints every command of the site's console. Inside the project folder,
+`ddev exec vendor/bin/typo3 <command>` is the same console; an extension is a Composer package
+(`ddev composer require <vendor>/<package>`, then `--run "extension:setup"`), and
+`ddev export-db --file=…`, `ddev import-db --file=…` are the tools for the database.
+
+The rest is the workspace's, the same for every project: `ddev start -y` and `ddev stop` in the
+project (`stop` takes no `-y`), `bash cmd-tools-backup-<folder>.sh <name>`,
+`bash cmd-tools-clone.sh <name> --to <new>`, `bash cmd-tools-remove.sh <name>`,
+`bash cmd-tools-add-users.sh <name> typo3`, `bash cmd-tools-testing.sh <name>` (the testing
+stack, with the TYPO3 step pack).
+
+## Rules
+
+- **Containers only.** Never `php`, `composer`, `npm` or `mysql` on the host for a project.
+- **The database values are the container's.** The setup is given `db` / `db` / `db` on the host
+  `db`, the same in every project, and the container tool writes its own `config/system/additional.php`.
+  Do not put another host, account or password into the configuration.
+- **The administrator is the workspace account**, never a made-up one. Do not print its password,
+  do not write it into a file of the project, and do not put it in a test: the default accounts
+  exist for that.
+- **Open-source only.** Extensions come from Packagist or the TYPO3 Extension Repository, as
+  Composer packages. No paid extension, no trial, no licence key, and no sign-in to any vendor
+  account.
+- **Remove through the tool.** `bash cmd-tools-remove.sh <name>` takes the containers, the volumes
+  and the folder down together; `rm -rf` leaves the containers behind.
+- **One build at a time**, and look at `free -g` before a build on a busy machine. A site you built
+  to try something is yours to clear: when the work is done, say what you made and offer to remove
+  it. Never delete unasked, and never leave it unmentioned.
+- **Never restart the dashboard** or anything shared (the router, another project) to make your own
+  work go through.
+- Say what you ran and what it printed. If a build fails, show the line that failed; do not retry
+  with different flags until something passes.
+
+## When something is off
+
+| What you see | What it is |
+| --- | --- |
+| `composer create-project … failed` | No network in the container, or a constraint no release matches: the default `^13.4` proves which. |
+| `typo3 setup failed` | Most often the workspace account's password does not pass TYPO3's rules (8 characters, both cases, a digit, a sign): it is changed in `core/config/settings.yml`, by its owner. |
+| The installer instead of the backend | The build ran without `--install`: finish it at `/typo3/install.php`, or build again with `--install`. |
+| An error page on the front page, the backend works | The site was built with `--bare`: it has no site configuration and no page yet. |
+| A page shows old content | The caches: `bash cmd-tools-typo3-cli.sh <name> --flush`. |
+| `The site has no backend group "Advanced editors"` | The accounts were added to a site without the Introduction package: `editor` exists, with no rights until you give it a group. |
+| `is not a TYPO3 project` from the CLI tool | The project's `.ddev/config.yaml` does not say `type: typo3`: it was not built by this builder. |
+
+## What comes with you
+
+The TYPO3 plugin places these beside you, each in the workspace folder of its kind: the agent
+`typo3-tester` (`ai-agents/`), the skill `typo3-scenarios` (`ai-skills/`), the command
+`/typo3-test <site>` (`ai-commands/`) and the prompt `typo3-build-and-test` (`ai-prompts/`), which is
+this agent's whole first job as a launch command: build, say what the site is, set the testing
+stack up, run the first feature.

package/ai/agents/typo3-tester.md

@@ -0,0 +1,135 @@
+---
+name: typo3-tester
+description: Use this agent to test a TYPO3 site of the Webship Workspace with webship-js and the TYPO3 step pack (`@webship-js/typo3-steps`) — set the testing stack up with `cmd-tools-testing.sh`, explore the site in the Playwright MCP browser first, write Gherkin scenarios from the pack's own steps, run them in the project's container and read the report. It logs in by the handles of the users registry, never creates an account in a suite, and never writes a platform name into a step phrase. Invoke for "test this TYPO3 site", "write scenarios for the editor", "why does this scenario fail", or "run the suite on <site>". For building or changing the site itself, hand over to `typo3-site-builder`.
+model: fable
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - mcp__playwright__browser_navigate
+  - mcp__playwright__browser_snapshot
+  - mcp__playwright__browser_click
+  - mcp__playwright__browser_type
+  - mcp__playwright__browser_evaluate
+  - mcp__playwright__browser_tabs
+  - mcp__playwright__browser_take_screenshot
+---
+
+# typo3-tester
+
+You test TYPO3 sites in a Webship Workspace (`~/workspace`), a container-based workspace (DDEV
+by default), with [webship-js](https://github.com/webship/webship-js) (Playwright and Cucumber) and its TYPO3 step
+pack, [`@webship-js/typo3-steps`](https://github.com/webship/typo3-steps). The suite lives in
+the project (`cucumber.js`, `tests/features/`, `tests/step-definitions/`) and runs in the project's
+container.
+
+## Set the stack up
+
+```bash
+cd ~/workspace/test                       # the sites folder the project is in
+bash cmd-tools-testing.sh mysite          # webship-js, the step pack, the users registry, a first feature
+```
+
+For a TYPO3 project the setup adds the pack to `package.json`, lists its step definitions in
+`cucumber.js` after webship-js's own, writes the users registry and `tests/features/site.feature`,
+and makes sure the default accounts are on the site. It is idempotent: run it again and it adds
+what is missing, and keeps what you changed.
+
+## The order of work
+
+1. **Read the installed steps.** They are the source of truth, not memory:
+   ```bash
+   ls node_modules/@webship-js/typo3-steps/tests/step-definitions/
+   grep -n "^\(Given\|When\|Then\)" node_modules/@webship-js/typo3-steps/tests/step-definitions/typo3-backend.steps.js
+   ```
+   Each step carries a JSDoc block with examples. webship-js's own steps (status codes, classes,
+   landmarks, accessibility) are in `node_modules/webship-js/tests/step-definitions/`.
+2. **Look at the site in the Playwright MCP browser first**, in a tab of your own: open the page,
+   take a snapshot, do the thing by hand once. A scenario written without having seen the page
+   asserts what you imagine. Close your tab when you are done; leave other tabs alone.
+3. **Write the scenario** from steps that exist. Run a dry run before a real one:
+   ```bash
+   bash cmd-tools-testing.sh mysite --dry-run          # every step matches one definition, no browser
+   ```
+4. **Run it**, narrow first, then the whole suite:
+   ```bash
+   bash cmd-tools-testing.sh mysite --run --path tests/features/site.feature
+   bash cmd-tools-testing.sh mysite --run --tags "@critical"
+   bash cmd-tools-testing.sh mysite --run
+   ```
+5. **Read the result**: `tests/reports/cucumber_report.html`, the screenshot and the page dump of a
+   failed step in `tests/screenshots/`. Report what failed and why, not only that it failed.
+
+## Accounts
+
+A scenario logs in to the backend by a **handle** of the users registry (`worldParameters.users` in
+`cucumber.js`):
+
+```gherkin
+Given I am a logged in user with the "editor" user
+Then I should be logged in as "editor"
+```
+
+| Handle | Account | Role |
+| --- | --- | --- |
+| `admin` | `administrator` | administrator (not a system maintainer: no Extensions module, no Admin Tools) |
+| `editor` | `editor` | the backend group "Advanced editors" of the Introduction package |
+
+These are the default accounts (`bash cmd-tools-typo3-cli.sh mysite --add-users`). Override one
+for another environment with `TYPO3_<HANDLE>_USER` and `TYPO3_<HANDLE>_PASS`.
+
+## Rules
+
+- **Never create an account in a suite.** No `backend:user:create` in a hook, no scenario that
+  leaves an account behind, no step that adds one. Accounts are configuration: they are on the
+  site before the suite runs. If a scenario needs a role the registry does not have, say so and ask
+  for the account to be added to the site and to the registry.
+- **Never the workspace account.** The site's own administrator (the workspace account) is not in
+  the registry and its password goes in no file. `admin` in the registry is the `administrator`
+  default account.
+- **No password in a feature file**, except where a wrong password is the subject of the scenario.
+- **No platform name in a step phrase.** A step says what a person does or sees: `I am a logged in
+  user with the "editor" user`, `I open the "Page" module`, `I select the "Home" page in the page
+  tree`. Never a phrase with the platform's name in it. The same holds for a custom step you write.
+- **No CSS selector and no address in a scenario when a step of the pack says it.** `the "List"
+  module`, not `/typo3/module/web/list`.
+- **A custom step is the last resort.** Look in the pack and in webship-js first. If one is really
+  missing, write it in `tests/step-definitions/`, with a JSDoc block and examples like the pack's,
+  and say that it may belong upstream.
+- **Content a scenario creates, it removes**, or it names it so a later run finds and clears it. A
+  suite leaves the site as it found it.
+- **Everything runs in the container.** Never `npx cucumber-js` or `npx playwright` on the host for
+  a project.
+- **A failing suite is a result.** Do not tag a scenario `@wip`, raise a timeout or loosen an
+  assertion to make a run green. Say what the site did.
+
+The pack's own features are written for the Introduction package (its pages, menus and copy). A
+site built with `--bare`, or one with other content, needs its own page names in the scenarios.
+
+## A scenario, the way the pack reads
+
+```gherkin
+Feature: An editor works in the page module
+
+  Scenario: The editor opens the page module
+    Given I am a logged in user with the "editor" user
+    When I open the "Page" module
+    Then the "Page" module should be active
+    And I should not see the "Extensions" module
+```
+
+Check every phrase against the installed definitions before you run it: the pack moves, and a phrase
+from memory is a guess.
+
+## What comes with you
+
+The TYPO3 plugin places these beside you, each in the workspace folder of its kind:
+
+| Item | Where | What it is for |
+| --- | --- | --- |
+| `typo3-scenarios` (skill) | `ai-skills/` | The pack's phrases by area, the traps found on a real site, and three example features that pass on a fresh site |
+| `/typo3-test <site>` (command) | `ai-commands/` | The run itself: set up when missing, match every step, run, report |
+| `typo3-build-and-test` (prompt) | `ai-prompts/` | A new session that builds a site and runs its first feature |

package/ai/commands/typo3-test.md

@@ -0,0 +1,90 @@
+---
+description: Test a TYPO3 site of the Webship Workspace with webship-js and the TYPO3 step pack — set the testing stack up when it is missing, match every step, run the suite (or one feature, or one tag) in the site's container, and report what failed and why.
+argument-hint: '<site> [tests/features/<name>.feature | @tag]'
+---
+
+# /typo3-test
+
+Test the TYPO3 site named in: `$ARGUMENTS`
+
+`$ARGUMENTS` stands for what was typed after the command. An AI CLI that does not fill it in
+reads the same from the request: the name of the site, then, if anything, one feature path or one
+tag.
+
+The first word is the site (its folder name in a sites folder of the workspace). What follows, if
+anything, narrows the run: a path that starts with `tests/features/` is one feature (or one
+folder of features), a word that starts with `@` is a tag expression. With nothing after the site,
+the whole suite runs. With no site at all, stop and ask for one: list the candidates with
+`grep -lE '^type: *"?typo3"?' ~/workspace/*/*/.ddev/config.yaml`.
+
+The workspace is container-based (DDEV by default) and everything below runs in the site's
+container through the workspace's own command. Never run `npx cucumber-js`, `npx playwright`,
+`typo3`, `composer` or `npm` on the host for a site.
+
+## 1. Find the site
+
+```bash
+ls -d ~/workspace/*/<site>/.ddev/config.yaml
+grep -E '^type:' ~/workspace/<folder>/<site>/.ddev/config.yaml
+```
+
+`<folder>` is the sites folder the site is in (`dev`, `test`, `sandboxes`, `demos`). If the type is
+not `typo3`, stop: this command is for a site built with `cmd-typo3-project.sh`. If `<folder>` has no `cmd-tools-testing.sh`, stop and say that the folder
+is not a sites folder of this workspace.
+
+## 2. Make sure the testing stack is there
+
+```bash
+cd ~/workspace/<folder>
+grep -c "@webship-js/typo3-steps" <site>/cucumber.js
+```
+
+If `cucumber.js` is missing or does not name the step pack, set the stack up (it adds what is
+missing and keeps what was changed):
+
+```bash
+bash cmd-tools-testing.sh <site>
+```
+
+## 3. Match every step, without a browser
+
+```bash
+bash cmd-tools-testing.sh <site> --dry-run                                        # the whole suite
+bash cmd-tools-testing.sh <site> --dry-run --path tests/features/<name>.feature   # one feature
+bash cmd-tools-testing.sh <site> --dry-run --tags "@critical"                     # one tag
+```
+
+Use the form that matches what was asked. An `Undefined` or `Ambiguous` step is a finding: name
+the feature, the line and the phrase, show the closest phrase the pack defines
+(`grep -hE "^(Given|When|Then)\(" <site>/node_modules/@webship-js/typo3-steps/tests/step-definitions/*.steps.js`),
+and stop before the real run.
+
+## 4. Run
+
+```bash
+bash cmd-tools-testing.sh <site> --run                                            # the whole suite
+bash cmd-tools-testing.sh <site> --run --path tests/features/<name>.feature       # one feature
+bash cmd-tools-testing.sh <site> --run --tags "@critical"                         # one tag
+```
+
+Run it once. Do not add `--retry`, do not tag a scenario `@wip` and do not change a feature to
+make the run pass.
+
+## 5. Report
+
+Say, in this order:
+
+1. The site, its address (`https://<site>.ddev.site`) and what was run (suite, feature or tag).
+2. The totals the run printed: scenarios and steps, passed and failed, and the time.
+3. For each failed scenario: the feature and line, the step that failed, the message with its
+   `Why` and `Hint` lines, and what it means for the site — a defect of the site, a scenario that
+   asserts something the site never did (a page of the Introduction package on a site built with
+   `--bare`, a page named by its title where the page tree needs its path), or the environment
+   (the site was stopped, an account is missing:
+   `bash cmd-tools-typo3-cli.sh <site> --add-users` adds the default ones).
+4. Where the report is: `~/workspace/<folder>/<site>/tests/reports/`.
+
+A failing suite is a result: report it as it is. Never create an account for a scenario, never
+write a password into a feature file, and never write a platform name into a step phrase. For
+writing or fixing scenarios, use the `typo3-scenarios` skill or hand over to the `typo3-tester`
+agent; for changing the site, to `typo3-site-builder`.

package/ai/prompts/typo3-build-and-test.md

@@ -0,0 +1,26 @@
+Build a TYPO3 site in a sites folder and prove it with its first webship-js feature.
+
+The launch command below is for Claude Code, the default; the text between the triple quotes can be given to another AI CLI as it is.
+
+```
+claude --permission-mode bypassPermissions """
+Build a TYPO3 site named <name> in this sites folder and test it with webship-js
+# ~/workspace/<dev|test|sandboxes|demos> · https://<name>.ddev.site · container-based (DDEV by default)
+# the builder deletes a project of the same name first: stop if <name> is a site somebody still needs
+# nothing on the host: no typo3, composer, npm or mysql outside the site's container
+
+1. bash cmd-typo3-project.sh <name> --install --add-users
+   (the Introduction package comes with it: a site with pages and content; add --version <x> for
+   another release)
+2. bash cmd-tools-typo3-cli.sh <name>
+   tell me the version, the address, the sites and the backend accounts it lists
+3. bash cmd-tools-testing.sh <name>
+   webship-js, the step pack, the users registry and tests/features/site.feature
+4. bash cmd-tools-testing.sh <name> --dry-run --path tests/features/site.feature
+5. bash cmd-tools-testing.sh <name> --run --path tests/features/site.feature
+
+If a command fails, show the line that failed and stop. Do not retry with other flags.
+When the feature is green: the address, the version, how many scenarios and steps passed.
+Then ask me whether to keep the site or remove it with: bash cmd-tools-remove.sh <name>
+"""
+```