@esimplicitylabs/katalyst-xspec 0.6.0 → 0.7.0

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)