@esimplicitylabs/katalyst-xspec 0.7.0 → 0.8.0

package/skills/katalyst-bdd-architecture/references/adapters.md

@@ -28,7 +28,7 @@ const test = createBddTest({
 ### Environment Variables
 
 ```bash
-API_BASE_URL=http://localhost:3000
+API_BASE_URL=http://localhost:3000   # optional: defaults to FRONTEND_URL (older alias TARGET_BASE_URL)
 ```
 
 ### Features
@@ -62,8 +62,7 @@ const test = createBddTest({
 ### Environment Variables
 
 ```bash
-FRONTEND_URL=http://localhost:3000
-BASE_URL=http://localhost:3000
+FRONTEND_URL=http://localhost:3000   # older alias BASE_URL
 HEADLESS=true
 ```
 
@@ -73,6 +72,7 @@ HEADLESS=true
 - Automatic waiting for elements
 - Multiple click modes (normal, force, dispatch)
 - Screenshot and debugging support
+- Login helpers used by `UniversalAuthAdapter` (optional on `UiPort`): `fillField(name, value, { timeoutMs })` (label, placeholder or `name`), `waitForUrl(predicate, timeoutMs)`, `waitForText(text, timeoutMs)`, `saveSession()`, `restoreSession(state)`
 
 ## TuiTesterAdapter
 
@@ -146,9 +146,12 @@ Implements `AuthPort` for both API and UI authentication.
 ### Constructor
 
 ```typescript
-class UniversalAuthAdapter implements AuthPort {
-  constructor(private readonly deps: { api: ApiPort; ui: UiPort }) {}
-}
+new UniversalAuthAdapter({
+  api,                 // ApiPort
+  ui,                  // UiPort
+  roles?,              // { pm: { username, password } } - overrides AUTH_<ROLE>_* env vars
+  env?,                // settings source, default process.env
+})
 ```
 
 ### Configuration
@@ -164,32 +167,48 @@ const test = createBddTest({
 ### Environment Variables
 
 ```bash
-# Admin credentials
-DEFAULT_ADMIN_USERNAME=admin@example.com
-DEFAULT_ADMIN_PASSWORD=admin123
-
-# User credentials
-DEFAULT_USER_USERNAME=user@example.com
-DEFAULT_USER_PASSWORD=user123
-
-# Auth endpoint
+# Credentials per role (any role name; "project manager" -> AUTH_PROJECT_MANAGER_*)
+AUTH_ADMIN_USERNAME=admin@example.com
+AUTH_ADMIN_PASSWORD=changeme
+AUTH_PM_USERNAME=pm@example.com
+AUTH_PM_PASSWORD=secret
+# admin/user also accept the older DEFAULT_ADMIN_*, DEFAULT_USER_*, NON_ADMIN_*
+
+# API login (defaults)
 API_AUTH_LOGIN_PATH=/auth/login
+API_AUTH_BODY=form            # or json
+API_AUTH_USERNAME_FIELD=username
+API_AUTH_PASSWORD_FIELD=password
+# API_AUTH_TOKEN_PATH=data.jwt  # default tries access_token, token, accessToken, data.*
+
+# UI login (defaults)
+UI_LOGIN_PATH=/login
+UI_USERNAME_FIELD=Username    # label, placeholder or name
+UI_PASSWORD_FIELD=Password
+UI_LOGIN_BUTTON=Login
+# UI_LOGIN_SUCCESS_URL / UI_LOGIN_SUCCESS_TEXT / UI_LOGIN_TIMEOUT=10000 / UI_SESSION_REUSE=true
 ```
 
 ### Behavior
 
-**API Authentication:**
-1. POSTs to `API_AUTH_LOGIN_PATH`
-2. Stores token in `world.headers['Authorization']`
-3. If credentials not set, skips silently with `console.warn`
+**API login (`apiLoginAs(world, role)`):**
+1. POSTs the role's credentials to `API_AUTH_LOGIN_PATH` (form or JSON)
+2. Reads the token and sets `world.headers.Authorization = Bearer <token>`; with no token but a `Set-Cookie`, keeps the cookie session
+3. Fails with status, response body and the settings to check on error. Never starts a browser.
+
+**UI login (`uiLoginAs(world, role, { reuseSession })`):**
+1. Navigates to `UI_LOGIN_PATH`
+2. Fills username/password fields matched by label, placeholder or `name`
+3. Clicks `UI_LOGIN_BUTTON` and waits to leave the login page (or for `UI_LOGIN_SUCCESS_URL` / `UI_LOGIN_SUCCESS_TEXT`); fails if it doesn't
+4. With `reuseSession` (used by `Given I am logged in as`), saves cookies + localStorage per role per worker and restores them later
+
+**Missing credentials fail** with `MissingCredentialsError` naming the variables to set (no hardcoded defaults, no silent skip).
+
+`apiLoginAsAdmin` / `apiLoginAsUser` / `uiLoginAsAdmin` / `uiLoginAsUser` are the roles `admin` / `user`. `credentialsFor(role)` returns resolved credentials; `clearUiSessions()` forgets saved sessions.
 
-**UI Authentication:**
-1. Navigates to `UI_LOGIN_PATH` (default: `/login`)
-2. Fills fields by placeholder (configurable via `UI_USERNAME_FIELD`, `UI_PASSWORD_FIELD`)
-3. Clicks login button (configurable via `UI_LOGIN_BUTTON`)
-4. If credentials not set, skips silently with `console.warn`
+### Extending
 
-> **Note:** No hardcoded default credentials are used. All credentials must be set via env vars.
+Subclass and override `protected apiLogin(world, role, creds)` or `protected uiLogin(world, role, creds)` (e.g. SSO or a multi-step form). `this.api`, `this.ui`, `this.roles`, `this.env` are available. Role lookup, steps and session reuse keep working.
 
 ## DefaultCleanupAdapter
 

package/skills/katalyst-bdd-architecture/references/ports.md

@@ -118,6 +118,14 @@ interface UiPort {
   
   // Utilities
   zoomTo(scale: number): Promise<void>;
+
+  // Optional: used by UniversalAuthAdapter for UI login. Custom UiPorts may omit
+  // them; login then uses fillPlaceholder and skips the success check and session reuse.
+  fillField?(name: string, value: string, options?: { timeoutMs?: number }): Promise<boolean>;
+  waitForUrl?(predicate: (url: string) => boolean, timeoutMs: number): Promise<boolean>;
+  waitForText?(text: string, timeoutMs: number): Promise<boolean>;
+  saveSession?(): Promise<UiSessionState>;            // cookies + localStorage
+  restoreSession?(state: UiSessionState): Promise<void>;
 }
 
 type UiClickMode = 'click' | 'dispatch click' | 'force click' | 'force dispatch click';
@@ -216,14 +224,20 @@ interface AuthPort {
   
   uiLoginAsAdmin(world: World): Promise<void>;
   uiLoginAsUser(world: World): Promise<void>;
+
+  // Optional (0.8+): any named role. Steps fall back to the admin/user methods if absent.
+  apiLoginAs?(world: World, role: string): Promise<void>;
+  uiLoginAs?(world: World, role: string, options?: { reuseSession?: boolean }): Promise<void>;
 }
 ```
 
 ### Implementation Notes
 
 The default `UniversalAuthAdapter`:
-- API login: POSTs to `API_AUTH_LOGIN_PATH` with username/password from env
-- UI login: Fills form at `/login` with username/password
+- Credentials: `roles` option, then `AUTH_<ROLE>_USERNAME` / `AUTH_<ROLE>_PASSWORD` (older `DEFAULT_ADMIN_*` / `DEFAULT_USER_*` for admin/user). Missing ones throw, naming the variables.
+- API login: POSTs to `API_AUTH_LOGIN_PATH` (form or JSON per `API_AUTH_BODY`), reads the token (`API_AUTH_TOKEN_PATH`) or keeps the session cookie
+- UI login: fills the form at `UI_LOGIN_PATH` (fields by label, placeholder or `name`), checks the page left the login page, optionally reuses the session
+- Extend by subclassing and overriding `protected apiLogin` / `uiLogin`
 
 ## CleanupPort
 

package/skills/katalyst-bdd-create-test/SKILL.md

@@ -68,7 +68,7 @@ Feature: [Resource] API
 
 ```gherkin
 Background:
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
 ```
 
 ### Step 3: Write Scenarios
@@ -164,7 +164,17 @@ Scenario: Submit [form name]
   Then I should see text "Success"
 ```
 
-**Pattern: Login Flow**
+**Pattern: Log in as a role** (preferred when the login isn't what you're testing)
+```gherkin
+Scenario: Project manager sees projects
+  Given I am logged in as "pm"
+  When I navigate to "/projects"
+  Then I should see text "Projects"
+```
+
+`Given I am logged in as "<role>"` fills the app's login form with `AUTH_<ROLE>_USERNAME` / `AUTH_<ROLE>_PASSWORD` once per worker and reuses the session afterwards. Use `When I log in as "<role>" in UI` to always submit the form. For API calls use `Given I am authenticated as "<role>" via API`. Any role name works; tell the user which `AUTH_<ROLE>_*` variables to add to `.env`. Login paths and field names are configured with `API_AUTH_*` / `UI_*` (see docs/guides/authentication.md).
+
+**Pattern: Login Flow (testing the form itself)**
 ```gherkin
 Scenario: User login
   Given I navigate to "/login"
@@ -244,7 +254,7 @@ Feature: [Workflow Name]
 ```gherkin
 Scenario: [Workflow description]
   # --- API SETUP PHASE ---
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   [API steps to create test data]
   
   # --- UI VERIFICATION PHASE ---
@@ -256,7 +266,7 @@ Scenario: [Workflow description]
 ```gherkin
 Scenario: Create user via API, verify in admin panel
   # API: Create user
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   Given I generate a UUID and store as "testId"
   When I POST "/admin/users" with JSON body:
     """
@@ -306,7 +316,7 @@ Given I register cleanup DELETE "/users/{userId}"  # Important!
 
 ```gherkin
 Background:
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   Given I generate a UUID and store as "runId"
 
 Scenario: Test 1

package/skills/katalyst-bdd-create-test/references/api-patterns.md

@@ -8,7 +8,7 @@ Common patterns for API testing with the Katalyst BDD framework.
 
 ```gherkin
 Scenario: List all [resources]
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   When I GET "/[endpoint]"
   Then the response status should be 200
   And the response should be a JSON array
@@ -18,7 +18,7 @@ Scenario: List all [resources]
 
 ```gherkin
 Scenario: Get [resource] by ID
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   When I GET "/[endpoint]/1"
   Then the response status should be 200
   And the response should be a JSON object
@@ -29,7 +29,7 @@ Scenario: Get [resource] by ID
 
 ```gherkin
 Scenario: Create [resource]
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   Given I generate a UUID and store as "runId"
   When I POST "/[endpoint]" with JSON body:
     """
@@ -48,7 +48,7 @@ Scenario: Create [resource]
 
 ```gherkin
 Scenario: Update [resource] with PUT
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   # First create the resource
   When I POST "/[endpoint]" with JSON body:
     """
@@ -72,7 +72,7 @@ Scenario: Update [resource] with PUT
 
 ```gherkin
 Scenario: Partial update with PATCH
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   When I PATCH "/[endpoint]/{resourceId}" with JSON body:
     """
     { "status": "active" }
@@ -85,7 +85,7 @@ Scenario: Partial update with PATCH
 
 ```gherkin
 Scenario: Delete [resource]
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   # Create resource to delete
   When I POST "/[endpoint]" with JSON body:
     """
@@ -105,18 +105,27 @@ Scenario: Delete [resource]
 
 ## Authentication Patterns
 
+### Any Role
+
+```gherkin
+Background:
+  Given I am authenticated as "pm" via API
+```
+
+Reads `AUTH_PM_USERNAME` / `AUTH_PM_PASSWORD` from `.env`. Missing credentials fail the step with a message naming the variables.
+
 ### Admin Authentication
 
 ```gherkin
 Background:
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
 ```
 
 ### User Authentication
 
 ```gherkin
 Background:
-  Given I am authenticated as a user via API
+  Given I am authenticated as "user" via API
 ```
 
 ### Custom Token Authentication
@@ -150,7 +159,7 @@ Scenario: Login and use token
 
 ```gherkin
 Scenario: Resource not found
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   When I GET "/[endpoint]/99999"
   Then the response status should be 404
 ```
@@ -159,7 +168,7 @@ Scenario: Resource not found
 
 ```gherkin
 Scenario: Invalid data returns 400
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   When I POST "/[endpoint]" with JSON body:
     """
     { "email": "not-valid-email" }
@@ -181,7 +190,7 @@ Scenario: Unauthorized access
 
 ```gherkin
 Scenario: User cannot access admin endpoint
-  Given I am authenticated as a user via API
+  Given I am authenticated as "user" via API
   When I GET "/admin/settings"
   Then the response status should be 403
 ```
@@ -237,7 +246,7 @@ Then the value at "created_at" should match "^\d{4}-\d{2}-\d{2}"
 
 ```gherkin
 Scenario: Paginated list
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   When I GET "/[endpoint]?page=1&limit=10"
   Then the response status should be 200
   And the response should be a JSON object
@@ -250,7 +259,7 @@ Scenario: Paginated list
 
 ```gherkin
 Scenario: Filter by status
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   When I GET "/[endpoint]?status=active"
   Then the response status should be 200
   And the response should be a JSON array
@@ -260,7 +269,7 @@ Scenario: Filter by status
 
 ```gherkin
 Scenario: Bulk create
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   When I POST "/[endpoint]/bulk" with JSON body:
     """
     {
@@ -279,7 +288,7 @@ Scenario: Bulk create
 
 ```gherkin
 Scenario: Upload file
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   Given I set header "Content-Type" to "multipart/form-data"
   # Note: Actual file upload requires custom step implementation
 ```
@@ -293,7 +302,7 @@ Feature: User Management API
   So that I can control system access
 
   Background:
-    Given I am authenticated as an admin via API
+    Given I am authenticated as "admin" via API
     Given I generate a UUID and store as "runId"
 
   Scenario: Create new user

package/skills/katalyst-bdd-create-test/references/hybrid-patterns.md

@@ -16,7 +16,7 @@ Hybrid tests are scenarios that mix API and UI steps. No tag is needed — every
 ```gherkin
 Scenario: Create user via API, verify in admin panel
   # API: Create test data
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   Given I generate a UUID and store as "testId"
   When I POST "/admin/users" with JSON body:
     """
@@ -40,7 +40,7 @@ Scenario: Create user via API, verify in admin panel
 ```gherkin
 Scenario: Test order workflow with pre-created product
   # API: Create product
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   Given I generate a UUID and store as "productId"
   When I POST "/admin/products" with JSON body:
     """
@@ -67,7 +67,7 @@ Scenario: Test order workflow with pre-created product
 ```gherkin
 Scenario: API update reflects in UI
   # API: Create and update
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   When I POST "/users" with JSON body:
     """
     { "name": "Original Name" }
@@ -95,7 +95,7 @@ Scenario: API update reflects in UI
 ```gherkin
 Scenario: Use API-created ID in UI navigation
   # API: Create resource
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   When I POST "/projects" with JSON body:
     """
     { "name": "Test Project" }
@@ -120,7 +120,7 @@ Scenario: Verify API data in UI
   Given I set variable "testName" to "Hybrid User {runId}"
   
   # API: Create with variables
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   When I POST "/users" with JSON body:
     """
     {
@@ -140,12 +140,29 @@ Scenario: Verify API data in UI
 
 ## Authentication Patterns
 
+### Same Role in API and UI
+
+```gherkin
+Scenario: PM creates via API, sees it in UI
+  Given I am authenticated as "pm" via API
+  When I POST "/api/projects" with JSON body:
+    """
+    { "name": "Apollo" }
+    """
+  Then the response status should be 201
+  Given I am logged in as "pm"
+  Given I navigate to "/projects"
+  Then I should see text "Apollo"
+```
+
+Both steps read `AUTH_PM_USERNAME` / `AUTH_PM_PASSWORD`. Relative API paths go to `API_BASE_URL`, or to `FRONTEND_URL` when it isn't set, so a same-origin app needs only `FRONTEND_URL`.
+
 ### Separate API and UI Auth
 
 ```gherkin
 Scenario: Different auth for API vs UI
   # API: Admin creates data
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   When I POST "/admin/announcements" with JSON body:
     """
     { "message": "Test announcement", "audience": "all" }
@@ -185,7 +202,7 @@ Scenario: Get token from API, use in UI
 ```gherkin
 Scenario: Complete order processing workflow
   # API: Setup - Create customer and product
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   Given I generate a UUID and store as "runId"
   
   When I POST "/customers" with JSON body:
@@ -221,7 +238,7 @@ Scenario: Complete order processing workflow
 
 ```gherkin
 Scenario: Real-time sync between API and UI
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   Given I generate a UUID and store as "runId"
   
   # API: Create initial data
@@ -258,7 +275,7 @@ Scenario: Real-time sync between API and UI
 Feature: User Settings
   
   Background:
-    Given I am authenticated as an admin via API
+    Given I am authenticated as "admin" via API
     Given I generate a UUID and store as "testId"
     
     # Create fresh user for each test
@@ -292,7 +309,7 @@ Feature: User Settings
 
 ```gherkin
 Scenario: Dashboard with multiple data types
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   Given I generate a UUID and store as "runId"
   
   # Create multiple related resources
@@ -330,7 +347,7 @@ Scenario: Dashboard with multiple data types
 ```gherkin
 Scenario: UI shows error when API resource deleted
   # API: Create and immediately delete
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   When I POST "/items" with JSON body:
     """
     { "name": "Temporary Item" }
@@ -360,7 +377,7 @@ Feature: User Onboarding
     Given I set variable "userName" to "New User {testId}"
     
     # Step 1: Admin creates user invitation via API
-    Given I am authenticated as an admin via API
+    Given I am authenticated as "admin" via API
     When I POST "/admin/invitations" with JSON body:
       """
       {
@@ -386,7 +403,7 @@ Feature: User Onboarding
     And the URL should contain "/dashboard"
     
     # Step 3: Verify user created via API
-    Given I am authenticated as an admin via API
+    Given I am authenticated as "admin" via API
     When I GET "/admin/users?email={userEmail}"
     Then the response status should be 200
     And the value at "[0].name" should equal "{userName}"

package/skills/katalyst-bdd-create-test/references/ui-patterns.md

@@ -35,6 +35,17 @@ Scenario: Go back to previous page
 
 ## Login Patterns
 
+### Log in as a Role (real login form, session reused)
+
+```gherkin
+Scenario: Project manager dashboard
+  Given I am logged in as "pm"
+  Given I navigate to "/dashboard"
+  Then I should see text "Projects"
+```
+
+Uses `AUTH_PM_USERNAME` / `AUTH_PM_PASSWORD` and the `UI_LOGIN_*` settings. Use `When I log in as "pm" in UI` when testing the login itself (always submits the form).
+
 ### Simple Login Form
 
 ```gherkin

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

@@ -97,21 +97,23 @@ cp .env.example .env
 Edit `.env` with your settings:
 
 ```bash
-# API Configuration
-API_BASE_URL=http://localhost:3000
-
-# Authentication (required -- no hardcoded defaults)
-DEFAULT_ADMIN_USERNAME=admin@example.com
-DEFAULT_ADMIN_PASSWORD=changeme
-DEFAULT_USER_USERNAME=user@example.com
-DEFAULT_USER_PASSWORD=changeme
-API_AUTH_LOGIN_PATH=/auth/login
-
-# UI Configuration
+# Where to test
 FRONTEND_URL=http://localhost:3000
-BASE_URL=http://localhost:3000
+# API_BASE_URL=http://localhost:4000   # only if the API is on another origin
 HEADLESS=true
 
+# Who logs in: AUTH_<ROLE>_USERNAME / AUTH_<ROLE>_PASSWORD, any role name
+AUTH_ADMIN_USERNAME=admin@example.com
+AUTH_ADMIN_PASSWORD=changeme
+# AUTH_PM_USERNAME=pm@example.com      # for Given I am logged in as "pm"
+# AUTH_PM_PASSWORD=changeme
+
+# Login settings (defaults shown; change only if your app differs)
+# API_AUTH_LOGIN_PATH=/auth/login
+# API_AUTH_BODY=form                    # or json
+# UI_LOGIN_PATH=/login
+# UI_USERNAME_FIELD=Username            # label, placeholder or name
+
 # Cleanup Rules (required -- no built-in rules)
 # CLEANUP_RULES='[{"varMatch":"user","path":"/api/users/{id}"}]'
 ```
@@ -122,10 +124,12 @@ Then use relative paths in features, e.g. `Given I navigate to "/login"`, `When
 
 | Steps used | Required Variables |
 |-----------|-------------------|
-| API steps with relative paths | `API_BASE_URL` |
-| UI steps with relative paths | `FRONTEND_URL` or `BASE_URL` |
-| Both in one scenario | Both API and UI variables |
-| Auth steps | `DEFAULT_*_USERNAME`, `DEFAULT_*_PASSWORD` |
+| UI steps with relative paths | `FRONTEND_URL` (older alias `BASE_URL`) |
+| API steps with relative paths | `API_BASE_URL`, or nothing extra if the API is on the `FRONTEND_URL` origin |
+| Both in one scenario | `FRONTEND_URL` (+ `API_BASE_URL` if the API is elsewhere) |
+| Login steps (`Given I am authenticated as "pm" via API`, `Given I am logged in as "pm"`) | `AUTH_PM_USERNAME`, `AUTH_PM_PASSWORD` (one pair per role) |
+
+Missing credentials fail the login step with a message naming the variables. Each run prints `katalyst-xspec targets: UI … | API …` showing where tests point. Login settings: docs/guides/authentication.md.
 
 ## Step 4: Write Your First Test
 
@@ -161,7 +165,7 @@ Any scenario can mix API and UI steps — no tag or separate project needed. Put
 Feature: User Workflow
 
   Scenario: Create via API, verify in UI
-    Given I am authenticated as an admin via API
+    Given I am authenticated as "admin" via API
     When I POST "/users" with JSON body:
       """
       { "name": "Test User" }

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

@@ -40,8 +40,9 @@ When I GET "/users/{userId}"  # Becomes /users/123
 | `Then the response should be a JSON object` | Asserts response is an object |
 | `Then the value at {string} should equal {string}` | `Then the value at "name" should equal "John"` |
 | `And I store the value at {string} as {string}` | `And I store the value at "id" as "userId"` |
-| `Given I am authenticated as an admin via API` | Admin API authentication |
-| `Given I am authenticated as a user via API` | User API authentication |
+| `Given I am authenticated as {string} via API` | `Given I am authenticated as "pm" via API` (reads `AUTH_PM_*`) |
+| `Given I am authenticated as an admin via API` | Shorthand for role `"admin"` |
+| `Given I am authenticated as a user via API` | Shorthand for role `"user"` |
 | `Given I set header {string} to {string}` | `Given I set header "X-Custom" to "value"` |
 
 ### UI Steps
@@ -49,6 +50,8 @@ When I GET "/users/{userId}"  # Becomes /users/123
 | Step | Example |
 |------|---------|
 | `Given I navigate to {string}` | `Given I navigate to "/login"` |
+| `Given I am logged in as {string}` | `Given I am logged in as "pm"` (UI login, session reused) |
+| `When I log in as {string} in UI` | `When I log in as "pm" in UI` (always submits the form) |
 | `When I click the button {string}` | `When I click the button "Submit"` |
 | `When I click the link {string}` | `When I click the link "Sign Up"` |
 | `When I fill the field {string} with {string}` | `When I fill the field "Email" with "test@example.com"` |
@@ -106,7 +109,7 @@ For complete step definitions with all parameters and examples:
 
 ```gherkin
 Scenario: Create and fetch user
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   When I POST "/users" with JSON body:
     """
     { "email": "test@example.com", "name": "Test" }
@@ -132,7 +135,7 @@ Scenario: User login
 
 ```gherkin
 Scenario: Create via API, verify in UI
-  Given I am authenticated as an admin via API
+  Given I am authenticated as "admin" via API
   When I POST "/users" with JSON body:
     """
     { "email": "new@example.com" }

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

@@ -88,21 +88,29 @@ When I DELETE "/users/{userId}"
 
 ## Authentication Steps
 
-### Admin Authentication
+### Log in as a role
 
 ```gherkin
-Given I am authenticated as an admin via API
+Given I am authenticated as {string} via API
 ```
 
-Uses `DEFAULT_ADMIN_USERNAME` and `DEFAULT_ADMIN_PASSWORD` env variables.
+**Example:**
+```gherkin
+Given I am authenticated as "pm" via API
+```
 
-### User Authentication
+Reads `AUTH_<ROLE>_USERNAME` / `AUTH_<ROLE>_PASSWORD` (role upper-cased, spaces/dashes become `_`), POSTs them to `API_AUTH_LOGIN_PATH` (default `/auth/login`), and sends the returned token as `Authorization: Bearer ...` on later API steps. Cookie sessions work too. Login settings: `API_AUTH_BODY` (`form`|`json`), `API_AUTH_USERNAME_FIELD`, `API_AUTH_PASSWORD_FIELD`, `API_AUTH_TOKEN_PATH`.
+
+If credentials are missing, the step fails with a message naming the variables to set.
+
+### Admin / user shorthand
 
 ```gherkin
+Given I am authenticated as an admin via API
 Given I am authenticated as a user via API
 ```
 
-Uses `DEFAULT_USER_USERNAME` and `DEFAULT_USER_PASSWORD` env variables.
+Same as the roles `"admin"` and `"user"` (`AUTH_ADMIN_*`, `AUTH_USER_*`; older `DEFAULT_ADMIN_*`, `DEFAULT_USER_*`, `NON_ADMIN_*` also work).
 
 ### Set Bearer Token
 
@@ -210,7 +218,7 @@ And I store the value at "items[0].id" as "firstItemId"
 Feature: User Management API
 
   Background:
-    Given I am authenticated as an admin via API
+    Given I am authenticated as "admin" via API
 
   Scenario: Full CRUD lifecycle
     # Create

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

@@ -250,7 +250,7 @@ type World = {
 Feature: User Management
 
   Background:
-    Given I am authenticated as an admin via API
+    Given I am authenticated as "admin" via API
     Given I generate a UUID and store as "runId"
 
   Scenario: Create user with cleanup
@@ -298,7 +298,7 @@ Feature: User Onboarding
     Given I set variable "userName" to "Test User {testId}"
     
     # API: Create user
-    Given I am authenticated as an admin via API
+    Given I am authenticated as "admin" via API
     When I POST "/admin/users" with JSON body:
       """
       {