workos 0.8.2 → 0.9.0

package/skills/workos-authkit-tanstack-start/SKILL.md

@@ -24,7 +24,7 @@ description: Integrate WorkOS AuthKit with TanStack Start applications. Full-sta
 
 **STOP - Do not proceed until complete.**
 
-WebFetch: `https://github.com/workos/authkit-tanstack-start/blob/main/README.md`
+WebFetch: `https://raw.githubusercontent.com/workos/authkit-tanstack-start/main/README.md`
 
 From README, extract:
 
@@ -110,13 +110,7 @@ export const startInstance = createStart(() => ({
 1. **Named export `startInstance`** — the build plugin generates `import type { startInstance }` from this file. A `default` export will cause a build error.
 2. **`createStart` takes a function** returning the options object, not the options directly. `createStart({ ... })` will fail.
 
-### Verification Checklist
-
-- [ ] `authkitMiddleware` imported from `@workos/authkit-tanstack-react-start`
-- [ ] Middleware in `requestMiddleware` array (not `middleware`)
-- [ ] Named export: `export const startInstance = createStart(...)` (not `export default`)
-
-Verify: `grep -r "authkitMiddleware" src/ app/ 2>/dev/null`
+**WARNING: Do NOT add middleware to `createRouter()` in `router.tsx` or `app.tsx`. That is TanStack Router (client-side only). Server middleware belongs in `start.ts` using `requestMiddleware`.**
 
 ## Callback Route (CRITICAL)
 
@@ -245,6 +239,26 @@ Do not skip this step. If the build fails, fix the errors before finishing. Comm
 - Missing Vite types → re-run step 2
 - Wrong import paths → check package name is `@workos/authkit-tanstack-react-start`
 
+## Verification Checklist (ALL MUST PASS)
+
+Run these commands to confirm integration. **Do not mark complete until all pass:**
+
+```bash
+# 1. Check authkitMiddleware is configured
+grep -r "authkitMiddleware" src/ app/ 2>/dev/null || echo "FAIL: Middleware not configured"
+
+# 2. Check callback route exists
+find src/routes app/routes -name "*callback*" 2>/dev/null
+
+# 3. Check environment variables
+grep -c "WORKOS_" .env 2>/dev/null || echo "FAIL: No env vars found"
+
+# 4. Build succeeds
+pnpm build
+```
+
+**If check #1 fails:** authkitMiddleware must be in src/start.ts (or app/start.ts for legacy) requestMiddleware array. Auth will fail silently without it.
+
 ## Error Recovery
 
 ### "AuthKit middleware is not configured"

package/skills/workos-authkit-vanilla-js/SKILL.md

@@ -9,7 +9,7 @@ description: Integrate WorkOS AuthKit with vanilla JavaScript applications. No f
 
 ### Step 1: Fetch README (BLOCKING)
 
-WebFetch: `https://github.com/workos/authkit-js/blob/main/README.md`
+WebFetch: `https://raw.githubusercontent.com/workos/authkit-js/main/README.md`
 
 **README is source of truth.** If this skill conflicts, follow README.
 
@@ -43,16 +43,25 @@ Follow README examples for:
 const authkit = await createClient(clientId);
 ```
 
-## Verification Checklist
+## Verification Checklist (ALL MUST PASS)
 
-- [ ] README fetched and read before writing code
-- [ ] Project type detected (bundled vs CDN)
-- [ ] SDK installed/script added
-- [ ] `createClient()` called with `await`
-- [ ] Client ID provided (env var or hardcoded)
-- [ ] Sign in called from user gesture (click handler)
-- [ ] No console errors on page load
-- [ ] Auth UI updates on sign in/out
+Run these commands to confirm integration. **Do not mark complete until all pass:**
+
+```bash
+# 1. Check SDK is available (bundled or CDN)
+grep -r "createClient\|WorkOS" src/ *.html 2>/dev/null || echo "FAIL: SDK not found"
+
+# 2. Check createClient uses await
+grep -rn "await createClient" src/ *.js *.html 2>/dev/null || echo "FAIL: createClient must be awaited"
+
+# 3. Check sign-in is on user gesture (click handler)
+grep -rn "signIn\|sign_in" src/ *.js *.html 2>/dev/null
+
+# 4. Build succeeds (bundled projects only)
+pnpm build 2>/dev/null || echo "CDN project — verify manually in browser"
+```
+
+**If check #2 fails:** createClient() is async and must be awaited. Using it without await returns a Promise, not a client.
 
 ## Environment Variables
 

package/skills/workos-elixir/SKILL.md

@@ -37,6 +37,43 @@ Check `.env.local` for:
 - `WORKOS_API_KEY` - starts with `sk_`
 - `WORKOS_CLIENT_ID` - starts with `client_`
 
+## Step 2b: Partial Install Recovery
+
+Before creating new files, check if a previous AuthKit attempt exists:
+
+1. Check if `:workos` is already in `mix.exs` dependencies
+2. Check for incomplete auth code — AuthController exists but has TODO stubs, 501 responses, or missing callback/sign_out functions
+3. If partial install detected:
+   - Do NOT re-add the SDK dependency (it's already there)
+   - Do NOT re-run `mix deps.get` if deps are already fetched
+   - Read existing auth files to understand what's done vs missing
+   - Complete the integration by filling gaps (controller methods, routes)
+   - Preserve any working code — only fix what's broken
+   - Check for missing `/auth/callback` route (most common gap)
+
+## Step 2c: Existing Auth System Detection
+
+Check for existing authentication before integrating:
+
+```
+mix.exs has ':ueberauth'?                          → Ueberauth auth
+mix.exs has ':pow'?                                → Pow auth
+mix.exs has ':guardian'?                           → Guardian JWT auth
+mix.exs has ':phx_gen_auth'?                       → Phoenix generated auth
+config/*.exs has 'Ueberauth' config?               → Ueberauth configured
+router.ex has '/:provider' wildcard auth routes?   → Ueberauth routes
+```
+
+If existing auth detected:
+
+- Do NOT remove or disable it
+- Add WorkOS AuthKit alongside the existing system
+- If Ueberauth is configured, be careful of `/:provider` wildcard routes — use a specific scope like `/auth/workos` to avoid conflicts
+- Reuse existing session infrastructure if compatible
+- Create separate route paths for WorkOS auth
+- Ensure existing auth routes continue to work unchanged
+- Document in code comments how to migrate fully to WorkOS later
+
 ## Step 3: Install SDK
 
 Add the `workos` package to `mix.exs` dependencies:

package/skills/workos-go/SKILL.md

@@ -9,7 +9,7 @@ description: Integrate WorkOS AuthKit with Go applications. Supports Gin and std
 
 **STOP. Do not proceed until complete.**
 
-WebFetch: `https://github.com/workos/workos-go/blob/main/README.md`
+WebFetch: `https://raw.githubusercontent.com/workos/workos-go/main/README.md`
 
 The README is the source of truth for SDK API usage. If this skill conflicts with README, follow README.
 
@@ -40,6 +40,41 @@ go.mod contains github.com/gin-gonic/gin?
   +-- No  --> Use stdlib net/http patterns
 ```
 
+## Step 2b: Partial Install Recovery
+
+Before creating new files, check if a previous AuthKit attempt exists:
+
+1. Check if `github.com/workos/workos-go` is already in `go.mod`
+2. Check for incomplete auth code — files that import WorkOS packages but have non-functional handlers (TODO comments, 501 responses, empty handler bodies)
+3. If partial install detected:
+   - Do NOT re-run `go get` (the module is already there)
+   - Read existing auth files to understand what's done vs missing
+   - Complete the integration by filling gaps rather than starting fresh
+   - Preserve any working code — only fix what's broken
+   - If `usermanagement.SetAPIKey()` is already called in `init()`, don't call it again
+   - Always run `go mod tidy` after changes to keep `go.sum` consistent
+
+## Step 2c: Existing Auth System Detection
+
+Check for existing authentication before integrating:
+
+```
+*.go files have 'jwt' or 'JWT'?             → Custom JWT auth
+*.go files have 'oauth2'?                   → OAuth2 middleware
+*.go files have 'authMiddleware'?            → Custom auth middleware
+go.mod has 'golang.org/x/oauth2'?           → OAuth2 package
+go.mod has 'github.com/coreos/go-oidc'?     → OIDC auth
+```
+
+If existing auth detected:
+
+- Do NOT remove or disable it
+- Add WorkOS AuthKit alongside the existing system
+- Create separate route paths for WorkOS auth (e.g., `/auth/workos/login` if `/auth/login` is taken)
+- Match handler signatures to the detected framework (Gin `*gin.Context` vs stdlib `http.ResponseWriter, *http.Request`)
+- Ensure existing auth middleware continues to work on its routes
+- Document in code comments how to migrate fully to WorkOS later
+
 ## Step 3: Install SDK
 
 Run:

package/skills/workos-kotlin/SKILL.md

@@ -37,6 +37,40 @@ Check `application.properties` or `application.yml` for:
 - `workos.api-key` or `WORKOS_API_KEY`
 - `workos.client-id` or `WORKOS_CLIENT_ID`
 
+## Step 2b: Partial Install Recovery
+
+Before creating new files, check if a previous AuthKit attempt exists:
+
+1. Check if `workos-kotlin` is already in `build.gradle.kts` dependencies
+2. Check for incomplete auth code — WorkOS imported/instantiated but no controller with login/callback endpoints
+3. If partial install detected:
+   - Do NOT re-add the SDK dependency (it's already there)
+   - Read existing source files to understand what's done vs missing
+   - Complete the integration by filling gaps (controller, config bean, routes)
+   - Preserve any working code — only fix what's broken
+   - Check for a missing `/auth/callback` endpoint (most common gap)
+
+## Step 2c: Existing Auth System Detection
+
+Check for existing authentication before integrating:
+
+```
+build.gradle.kts has 'spring-boot-starter-security'?  → Spring Security
+*.kt files have 'SecurityFilterChain'?                → Security filter config
+*.kt files have 'formLogin'?                          → Form-based auth
+*.kt files have 'oauth2Login'?                        → OAuth2 auth
+*.kt files have 'httpBasic'?                          → Basic auth
+```
+
+If existing auth detected:
+
+- Do NOT remove or disable it
+- Add WorkOS AuthKit alongside the existing system
+- If Spring Security is configured, ensure WorkOS auth routes are permitted through the security filter chain (add `.requestMatchers("/auth/workos/**").permitAll()`)
+- Create separate route paths for WorkOS auth (e.g., `/auth/workos/login` if `/login` is taken)
+- Ensure existing auth routes continue to work unchanged
+- Document in code comments how to migrate fully to WorkOS later
+
 ## Step 3: Install SDK
 
 Add the WorkOS Kotlin SDK dependency to `build.gradle.kts`:

package/skills/workos-management/SKILL.md

@@ -5,7 +5,7 @@ description: Manage WorkOS resources (orgs, users, roles, SSO, directories, webh
 
 # WorkOS Management Commands
 
-Use these commands to manage WorkOS resources directly from the terminal. The CLI must be authenticated via `workos login` or `WORKOS_API_KEY` env var.
+Use these commands to manage WorkOS resources directly from the terminal. The CLI must be authenticated via `workos auth login` or `WORKOS_API_KEY` env var.
 
 All commands support `--json` for structured output. Use `--json` when you need to parse output (e.g., extract an ID).
 

package/skills/workos-node/SKILL.md

@@ -36,6 +36,39 @@ Detect package manager: `pnpm-lock.yaml` → `yarn.lock` → `bun.lockb` → npm
 
 **Adapt all subsequent steps to the detected framework and module system.**
 
+## Step 2b: Partial Install Recovery
+
+Before creating new files, check if a previous AuthKit attempt exists:
+
+1. Check if `@workos-inc/node` is already in `package.json`
+2. Check for incomplete auth files — routes/handlers that import `@workos-inc/node` but are non-functional (TODO comments, 501 responses, empty handlers)
+3. If partial install detected:
+   - Do NOT reinstall the SDK (it's already there)
+   - Read existing auth files to understand what's done vs missing
+   - Complete the integration by filling gaps rather than starting fresh
+   - Preserve any working code — only fix what's broken
+   - Check for a missing `/callback` route (most common gap)
+
+## Step 2c: Existing Auth System Detection
+
+Check for existing authentication before integrating:
+
+```
+package.json has 'passport'?                → Passport.js auth
+package.json has 'express-openid-connect'?  → Auth0 / OIDC
+package.json has 'express-session'?         → Session-based auth may exist
+*.js/*.ts files have 'jsonwebtoken'?        → JWT-based auth
+```
+
+If existing auth detected:
+
+- Do NOT remove or disable it
+- Add WorkOS AuthKit alongside the existing system
+- If `express-session` is already configured, reuse it for WorkOS session storage (don't create a second session middleware)
+- Create separate route paths for WorkOS auth (e.g., `/auth/workos/login` if `/login` is taken)
+- Ensure existing auth routes continue to work unchanged
+- Document in code comments how to migrate fully to WorkOS later
+
 ## Step 3: Install SDK
 
 ```

package/skills/workos-php/SKILL.md

@@ -9,7 +9,7 @@ description: Integrate WorkOS AuthKit with generic PHP applications. Uses the wo
 
 **STOP. Do not proceed until complete.**
 
-WebFetch: `https://github.com/workos/workos-php/blob/main/README.md`
+WebFetch: `https://raw.githubusercontent.com/workos/workos-php/main/README.md`
 
 The README is the source of truth. If this skill conflicts with README, follow README.
 
@@ -30,6 +30,39 @@ Check for `.env` file with:
 
 If `.env` doesn't exist, create it with the required variables.
 
+## Step 2b: Partial Install Recovery
+
+Before creating new files, check if a previous AuthKit attempt exists:
+
+1. Check if `workos/workos-php` is already in `composer.json`
+2. Check for incomplete auth files — `login.php` or `callback.php` that import WorkOS but are non-functional (TODO comments, 501 responses, empty handlers)
+3. If partial install detected:
+   - Do NOT reinstall the SDK (it's already there)
+   - Read existing auth files to understand what's done vs missing
+   - Complete the integration by filling gaps rather than starting fresh
+   - Preserve any working code — only fix what's broken
+   - Check for a missing `callback.php` (most common gap)
+
+## Step 2c: Existing Auth System Detection
+
+Check for existing authentication before integrating:
+
+```
+*.php files have 'session_start()' + '$_SESSION'?  → Native PHP session auth
+*.php files have 'password_verify'?                 → Password-based auth
+*.php files have form POST to '/login'?             → Form-based auth
+composer.json has auth libraries?                   → Third-party auth
+```
+
+If existing auth detected:
+
+- Do NOT remove or disable it
+- Add WorkOS AuthKit alongside the existing system
+- If `session_start()` is already used, reuse the session for WorkOS (don't create a second session mechanism)
+- Create separate file paths for WorkOS auth (e.g., `workos-login.php` if `login.php` is taken)
+- Ensure existing auth routes continue to work unchanged
+- Document in code comments how to migrate fully to WorkOS later
+
 ## Step 3: Install SDK
 
 ```bash

package/skills/workos-php-laravel/SKILL.md

@@ -9,7 +9,7 @@ description: Integrate WorkOS AuthKit with Laravel applications. Uses the dedica
 
 **STOP. Do not proceed until complete.**
 
-WebFetch: `https://github.com/workos/workos-php-laravel/blob/main/README.md`
+WebFetch: `https://raw.githubusercontent.com/workos/workos-php-laravel/main/README.md`
 
 The README is the source of truth. If this skill conflicts with README, follow README.
 
@@ -31,6 +31,41 @@ Check `.env` for:
 
 If `.env` exists but is missing these variables, append them. If `.env` doesn't exist, copy `.env.example` and add them.
 
+## Step 2b: Partial Install Recovery
+
+Before creating new files, check if a previous AuthKit attempt exists:
+
+1. Check if `workos/workos-php-laravel` is already in `composer.json`
+2. Check if `config/workos.php` exists but no auth controller or routes are wired
+3. If partial install detected:
+   - Do NOT reinstall the SDK (it's already there)
+   - Do NOT re-publish config if `config/workos.php` already exists
+   - Read existing files to understand what's done vs missing
+   - Complete the integration by filling gaps (controller, routes, middleware)
+   - Preserve any working code — only fix what's broken
+   - Check for missing auth controller or routes (most common gap)
+
+## Step 2c: Existing Auth System Detection
+
+Check for existing authentication before integrating:
+
+```
+composer.json has 'laravel/breeze'?               → Breeze auth scaffolding
+composer.json has 'laravel/jetstream'?            → Jetstream auth
+composer.json has 'laravel/fortify'?              → Fortify auth backend
+app/Http/Controllers/Auth/ exists?                → Auth controllers present
+routes/auth.php exists?                           → Auth routes file
+```
+
+If existing auth detected:
+
+- Do NOT remove or disable it
+- Add WorkOS AuthKit alongside the existing system
+- If Laravel session is already configured, reuse it for WorkOS
+- Create separate route paths for WorkOS auth (e.g., `/auth/workos/login` if `/login` is taken)
+- Ensure existing auth routes continue to work unchanged
+- Document in code comments how to migrate fully to WorkOS later
+
 ## Step 3: Install SDK
 
 ```bash

package/skills/workos-python/SKILL.md

@@ -35,6 +35,40 @@ None of the above?                       → Vanilla Python (use Flask quickstar
 
 **Adapt all subsequent steps to the detected framework.** Do not force one framework onto another.
 
+## Step 2b: Partial Install Recovery
+
+Before creating new files, check if a previous AuthKit attempt exists:
+
+1. Check if `workos` is already in `requirements.txt` or `pyproject.toml`
+2. Check for incomplete auth files — files that import `workos` but have non-functional routes (TODO comments, commented-out code, empty handlers)
+3. If partial install detected:
+   - Do NOT reinstall the SDK (it's already there)
+   - Read existing auth files to understand what's done vs missing
+   - Complete the integration by filling gaps rather than starting fresh
+   - Preserve any working code — only fix what's broken
+   - Check for a missing `/callback` route (most common gap)
+
+## Step 2c: Existing Auth System Detection
+
+Check for existing authentication before integrating:
+
+```
+requirements.txt has 'flask-login'?         → Flask-Login auth
+requirements.txt has 'authlib'?             → OAuth/OIDC auth (e.g., Auth0)
+requirements.txt has 'django-allauth'?      → Django allauth
+manage.py exists + 'django.contrib.auth'?   → Django built-in auth
+*.py files have 'flask_login'?              → Flask-Login in use
+```
+
+If existing auth detected:
+
+- Do NOT remove or disable it
+- Add WorkOS AuthKit alongside the existing system
+- If `flask-login` is present, use Flask-Login's session infrastructure (`login_user()`) for WorkOS auth too, rather than raw session management
+- Create separate route paths for WorkOS auth (e.g., `/auth/workos/login` if `/login` is taken)
+- Ensure existing auth routes continue to work unchanged
+- Document in code comments how to migrate fully to WorkOS later
+
 ## Step 3: Pre-Flight Validation
 
 ### Package Manager Detection

package/skills/workos-ruby/SKILL.md

@@ -32,6 +32,41 @@ None of the above?                       → Vanilla Ruby (use Sinatra quickstar
 
 **Adapt all subsequent steps to the detected framework.** Do not force Rails on a Sinatra project or vice versa.
 
+## Step 2b: Partial Install Recovery
+
+Before creating new files, check if a previous AuthKit attempt exists:
+
+1. Check if `workos` is already in `Gemfile`
+2. Check for incomplete auth files — files that `require "workos"` but have non-functional routes (TODO comments, 501 responses, empty handlers)
+3. If partial install detected:
+   - Do NOT reinstall the gem (it's already there)
+   - Read existing auth files to understand what's done vs missing
+   - Complete the integration by filling gaps rather than starting fresh
+   - Preserve any working code — only fix what's broken
+   - Run `bundle install` (not `bundle update`) to avoid unexpected gem upgrades
+
+## Step 2c: Existing Auth System Detection
+
+Check for existing authentication before integrating:
+
+```
+Gemfile has 'devise'?                       → Devise auth (uses Warden)
+Gemfile has 'warden'?                       → Warden auth
+Gemfile has 'omniauth'?                     → OmniAuth (OAuth/OIDC)
+*.rb files have 'Warden'?                   → Warden middleware in use
+config/initializers has devise.rb?          → Devise configured
+```
+
+If existing auth detected:
+
+- Do NOT remove or disable it
+- Add WorkOS AuthKit alongside the existing system
+- If Devise is present, Devise uses Warden under the hood — integrate WorkOS at the Warden strategy level if possible
+- Create separate route paths for WorkOS auth (e.g., `/auth/workos/login` if `/login` is taken)
+- Ensure Rack middleware ordering is correct (WorkOS session middleware must not conflict)
+- Ensure existing auth routes continue to work unchanged
+- Document in code comments how to migrate fully to WorkOS later
+
 ## Step 3: Install WorkOS Gem
 
 ```bash