@esimplicitylabs/katalyst-xspec 0.6.0 → 0.7.1

package/skills/katalyst-bdd-step-reference/SKILL.md

@@ -1,24 +1,19 @@
 ---
 name: katalyst-bdd-step-reference
-description: Complete reference of all available BDD step definitions in the Katalyst framework. Use when writing feature files, looking up step syntax, understanding what steps are available for a tag, or finding the right step for a specific action like clicking, filling forms, making API calls, or terminal interactions.
+description: Complete reference of all available BDD step definitions in the Katalyst framework. Use when writing feature files, looking up step syntax, checking exact step wording, or finding the right step for a specific action like clicking, filling forms, making API calls, or terminal interactions.
 ---
 
 # Katalyst BDD Step Reference
 
 This skill provides a complete reference of all step definitions available in @esimplicitylabs/katalyst-xspec.
 
-## Tag System
+## Where Steps Work
 
-Steps are enabled based on the feature/scenario tag:
+Built-in steps are untagged. Once registered (`registerApiSteps`, `registerUiSteps`, `registerSharedSteps`, `registerTuiSteps`, ...), **any step works in any scenario**, so a single scenario can mix API, UI and shared steps.
 
-| Tag | Available Steps | Use Case |
-|-----|-----------------|----------|
-| `@api` | API + Shared | HTTP API testing only |
-| `@ui` | UI + Shared | Browser UI testing only |
-| `@tui` | TUI + Shared | Terminal UI testing only |
-| `@hybrid` | API + UI + Shared | Combined API and UI testing |
-
-**Important:** Always tag your feature or scenario. Without a tag, steps may not be available.
+- Do not add `{ tags: ... }` to steps or type tags to scenarios; they are not needed.
+- Playwright projects pick feature files by folder (`features/api/`, `features/ui/`).
+- Tags like `@smoke` or `@wip` are optional, for the user's own filtering (`TEST_TAGS`).
 
 ## Variable Interpolation
 
@@ -31,7 +26,7 @@ When I GET "/users/{userId}"  # Becomes /users/123
 
 ## Quick Reference - Most Common Steps
 
-### API Steps (`@api` or `@hybrid`)
+### API Steps
 
 | Step | Example |
 |------|---------|
@@ -49,7 +44,7 @@ When I GET "/users/{userId}"  # Becomes /users/123
 | `Given I am authenticated as a user via API` | User API authentication |
 | `Given I set header {string} to {string}` | `Given I set header "X-Custom" to "value"` |
 
-### UI Steps (`@ui` or `@hybrid`)
+### UI Steps
 
 | Step | Example |
 |------|---------|
@@ -64,7 +59,7 @@ When I GET "/users/{userId}"  # Becomes /users/123
 | `Then the element {string} should be visible` | `Then the element "#modal" should be visible` |
 | `When I pause for debugging` | Opens Playwright Inspector |
 
-### TUI Steps (`@tui`)
+### TUI Steps
 
 | Step | Example |
 |------|---------|
@@ -73,9 +68,13 @@ When I GET "/users/{userId}"  # Becomes /users/123
 | `When I press {string}` | `When I press "Enter"` |
 | `When I press enter` | Press Enter key |
 | `Then I should see {string}` | `Then I should see "Welcome"` |
+| `Then I should see {string} in the terminal` | `Then I should see "Ready" in the terminal` |
 | `Then the screen should contain {string}` | Assert screen has text |
+| `When I fill the TUI form:` | Data table of `field`/`value` |
+
+TUI has no `I should see text {string}` (that's the UI step), and the TUI form step is `I fill the TUI form:` (UI uses `I fill the form:`).
 
-### Shared Steps (All Tags)
+### Shared Steps
 
 | Step | Example |
 |------|---------|
@@ -106,7 +105,6 @@ For complete step definitions with all parameters and examples:
 ### API CRUD Test
 
 ```gherkin
-@api
 Scenario: Create and fetch user
   Given I am authenticated as an admin via API
   When I POST "/users" with JSON body:
@@ -122,7 +120,6 @@ Scenario: Create and fetch user
 ### UI Login Test
 
 ```gherkin
-@ui
 Scenario: User login
   Given I navigate to "/login"
   When I fill in "Email" with "user@example.com"
@@ -131,10 +128,9 @@ Scenario: User login
   Then I should see text "Dashboard"
 ```
 
-### Hybrid Test (API + UI)
+### Mixed API + UI Test (no tag needed)
 
 ```gherkin
-@hybrid
 Scenario: Create via API, verify in UI
   Given I am authenticated as an admin via API
   When I POST "/users" with JSON body:

package/skills/katalyst-bdd-step-reference/references/api-steps.md

@@ -1,6 +1,6 @@
 # API Steps Reference
 
-Complete reference for API steps. Available in `@api` and `@hybrid` scenarios.
+Complete reference for API steps. Steps are untagged and work in any scenario (including alongside UI steps).
 
 ## HTTP Method Steps
 
@@ -207,7 +207,6 @@ And I store the value at "items[0].id" as "firstItemId"
 ## Complete API Example
 
 ```gherkin
-@api
 Feature: User Management API
 
   Background:

package/skills/katalyst-bdd-step-reference/references/shared-steps.md

@@ -1,6 +1,6 @@
 # Shared Steps Reference
 
-Complete reference for shared steps. Available in all scenarios regardless of tag (`@api`, `@ui`, `@tui`, `@hybrid`).
+Complete reference for shared steps. Available in all scenarios; like every built-in step, they need no tag.
 
 ## Variable Steps
 
@@ -247,7 +247,6 @@ type World = {
 ### API Test with Variables and Cleanup
 
 ```gherkin
-@api
 Feature: User Management
 
   Background:
@@ -276,7 +275,6 @@ Feature: User Management
 ### UI Test with Variables
 
 ```gherkin
-@ui
 Feature: Search
 
   Scenario: Search with generated term
@@ -291,7 +289,6 @@ Feature: Search
 ### Hybrid Test with Shared State
 
 ```gherkin
-@hybrid
 Feature: User Onboarding
 
   Scenario: Create user via API, verify in UI
@@ -322,7 +319,6 @@ Feature: User Onboarding
 ### Feature Flags Example
 
 ```gherkin
-@ui
 Feature: Feature Flag Testing
 
   Scenario: Test with feature enabled

package/skills/katalyst-bdd-step-reference/references/tui-steps.md

@@ -1,6 +1,6 @@
 # TUI Steps Reference
 
-Complete reference for TUI (Terminal User Interface) steps. Available only in `@tui` scenarios.
+Complete reference for TUI (Terminal User Interface) steps. Steps are untagged and work in any scenario once `registerTuiSteps(test)` is enabled and a TUI adapter is configured.
 
 **Prerequisites:** TUI testing requires `tmux` installed on the system and `tui-tester` configured.
 
@@ -202,8 +202,10 @@ When I select from dropdown "Theme" value "Dark"
 
 ### Fill Form
 
+The TUI form step is `I fill the TUI form:` (the UI step keeps `I fill the form:`).
+
 ```gherkin
-When I fill the form:
+When I fill the TUI form:
   | Field    | Value     |
   | Username | admin     |
   | Password | secret123 |
@@ -223,7 +225,6 @@ When I submit the form with ctrl+s
 ```gherkin
 Then I should see {string}
 Then I should see {string} in the terminal
-Then I should see text {string}
 Then the screen should contain {string}
 ```
 
@@ -234,6 +235,8 @@ Then I should see "Login successful" in the terminal
 Then the screen should contain "Press Enter to continue"
 ```
 
+Note: there is no TUI `I should see text {string}` step; that wording belongs to the UI steps.
+
 ### Assert Text Not Visible
 
 ```gherkin
@@ -417,7 +420,6 @@ When I force quit the application
 ## Complete TUI Example
 
 ```gherkin
-@tui
 Feature: CLI Application
 
   Background:
@@ -438,7 +440,7 @@ Feature: CLI Application
 
   Scenario: Fill login form
     When I wait for "Login"
-    When I fill the form:
+    When I fill the TUI form:
       | Field    | Value     |
       | Username | admin     |
       | Password | secret123 |

package/skills/katalyst-bdd-step-reference/references/ui-steps.md

@@ -1,6 +1,6 @@
 # UI Steps Reference
 
-Complete reference for UI steps. Available in `@ui` and `@hybrid` scenarios.
+Complete reference for UI steps. Steps are untagged and work in any scenario (including alongside API steps). UI tests need a browser: `npx playwright install chromium`.
 
 ## Navigation Steps
 
@@ -496,7 +496,6 @@ Then I zoom to "150" in the browser
 ## Complete UI Example
 
 ```gherkin
-@ui
 Feature: User Login
 
   Scenario: Successful login flow

package/skills/katalyst-bdd-troubleshooting/SKILL.md

@@ -11,8 +11,10 @@ This skill helps diagnose and fix common issues with the Katalyst BDD testing fr
 
 | Symptom | Likely Cause | Solution |
 |---------|--------------|----------|
-| "No tests found" | Forgot to generate | Run `npm run gen` |
-| Step is undefined | Wrong tag or typo | Check tag matches step availability |
+| "No tests found" | Forgot to generate | Run `npm run gen` (or just `npm test`) |
+| "Executable doesn't exist" | Browser not downloaded | Run `npx playwright install chromium` |
+| Step is undefined | Typo, renamed step, or not registered | Check exact wording in the step reference |
+| Scenario never runs | Feature outside a project's folder, `@Skip`, or old tag filter | See Issue 2b |
 | Auth fails (401/403) | Bad credentials | Check `.env` variables |
 | Element not found | Selector wrong or timing | Add waits or use debugging |
 | Cleanup not running | Not registered | Add `Given I register cleanup DELETE...` |
@@ -36,7 +38,7 @@ npm run gen
 npm test
 ```
 
-**Prevention:** Add to your workflow - always run `npm run gen` before `npm test`.
+**Prevention:** `npm test` already runs `bddgen && playwright test`. If you call `npx playwright test` directly, run `npm run gen` first.
 
 ## Issue 2: Step Not Defined
 
@@ -47,24 +49,11 @@ Step "When I click the button Submit" is not defined
 
 **Possible Causes:**
 
-### 1. Wrong Tag
-Steps are only available with the correct tag:
+### 1. Renamed or Removed Step (0.7.0)
+Steps are untagged and work in any scenario, so a tag is never the cause. Check for these 0.7.0 changes:
 
-| Step Type | Required Tag |
-|-----------|--------------|
-| API steps | `@api` or `@hybrid` |
-| UI steps | `@ui` or `@hybrid` |
-| TUI steps | `@tui` |
-| Shared steps | Any tag |
-
-**Fix:** Add the correct tag to your feature or scenario:
-```gherkin
-@ui  # <-- Required for UI steps
-Feature: Login Page
-
-  Scenario: Click button
-    When I click the button "Submit"
-```
+- TUI `When I fill the form:` is now `When I fill the TUI form:` (UI keeps `I fill the form:`).
+- TUI `Then I should see text {string}` was removed; use `Then I should see {string}` or `Then I should see {string} in the terminal`.
 
 ### 2. Typo in Step
 Steps must match exactly. Check:
@@ -99,6 +88,16 @@ registerAllSteps(test);  // Registers all step types
 export { test };
 ```
 
+## Issue 2b: Scenario Never Runs
+
+Untagged scenarios are not skipped. If a scenario is missing:
+
+1. Check the feature file is in the folder its project reads (e.g. `features/ui/**/*.feature` for the `ui` project).
+2. Check it isn't tagged `@Skip`/`@ignore`, and that `TEST_TAGS` isn't filtering it out.
+3. If `playwright.config.*` still has old filters like `tags: '@ui'` (pre-0.7), run `npx katalyst-xspec upgrade --migrate`.
+
+Old `@api`/`@ui` tags left in feature files are harmless.
+
 ## Issue 3: Authentication Failures
 
 ### API Auth Fails (401)
@@ -107,11 +106,11 @@ export { test };
 ```bash
 # Required for admin auth
 DEFAULT_ADMIN_USERNAME=admin@example.com
-DEFAULT_ADMIN_PASSWORD=admin123
+DEFAULT_ADMIN_PASSWORD=changeme
 
 # Required for user auth
 DEFAULT_USER_USERNAME=user@example.com
-DEFAULT_USER_PASSWORD=user123
+DEFAULT_USER_PASSWORD=changeme
 
 # Auth endpoint path
 API_AUTH_LOGIN_PATH=/auth/login
@@ -422,9 +421,9 @@ HEADLESS=true
 
 # Authentication (required -- no hardcoded defaults)
 DEFAULT_ADMIN_USERNAME=admin@example.com
-DEFAULT_ADMIN_PASSWORD=admin123
+DEFAULT_ADMIN_PASSWORD=changeme
 DEFAULT_USER_USERNAME=user@example.com
-DEFAULT_USER_PASSWORD=user123
+DEFAULT_USER_PASSWORD=changeme
 API_AUTH_LOGIN_PATH=/auth/login
 
 # UI Login Customization (optional)