workos 0.8.1 → 0.9.0

package/skills/workos-authkit-sveltekit/SKILL.md

@@ -9,7 +9,7 @@ description: Integrate WorkOS AuthKit with SvelteKit. Server-side authentication
 
 **STOP. Do not proceed until complete.**
 
-WebFetch: `https://github.com/workos/authkit-sveltekit/blob/main/README.md`
+WebFetch: `https://raw.githubusercontent.com/workos/authkit-sveltekit/main/README.md`
 
 The README is the source of truth. If this skill conflicts with README, follow README.
 
@@ -32,15 +32,63 @@ Check `.env` or `.env.local` for:
 
 SvelteKit uses `$env/static/private` and `$env/dynamic/private` natively. The agent should write env vars to `.env` (SvelteKit's default) or `.env.local`.
 
+## Step 2b: Partial Install Recovery
+
+Before installing the SDK, check if a previous AuthKit attempt already exists:
+
+1. Check if `@workos/authkit-sveltekit` is already in `package.json`
+2. Check for incomplete setup signals:
+   - `src/hooks.server.ts` has commented-out `authkitHandle` import or exports a passthrough handle
+   - `src/routes/+layout.server.ts` has TODO comments about loading the session
+   - No callback `+server.ts` route exists in `src/routes/`
+   - No `WORKOS_COOKIE_PASSWORD` in `.env`
+3. If partial install detected:
+   - Do NOT reinstall the SDK (it's already there)
+   - Read existing files to understand what's done vs missing
+   - Complete the integration by filling gaps rather than starting fresh
+   - The most common gap is the missing callback route — create it
+   - Wire up `authkitHandle` in hooks.server.ts properly (use `sequence()` if other hooks exist)
+   - Complete the layout load function
+   - Ensure `WORKOS_COOKIE_PASSWORD` is set in `.env`
+
+## Step 2c: Existing Auth System Detection
+
+Check for existing authentication before integrating:
+
+```
+package.json has 'lucia'?              → Lucia v3 session auth
+package.json has '@auth0/auth0-spa-js'? → Auth0 SPA auth
+package.json has '@auth/sveltekit'?    → Auth.js SvelteKit
+src/hooks.server.ts handles cookies?   → Custom session middleware
+```
+
+If existing auth detected (Lucia is most common in SvelteKit):
+
+- Do NOT remove or disable the existing auth system
+- Use `sequence()` from `@sveltejs/kit/hooks` to compose handles:
+
+  ```typescript
+  import { sequence } from '@sveltejs/kit/hooks';
+  import { authkitHandle } from '@workos/authkit-sveltekit';
+
+  // Keep existing handle, compose with AuthKit
+  export const handle = sequence(authkitHandle, existingHandle);
+  ```
+
+- AuthKit handle should come FIRST in `sequence()` so it runs before other middleware
+- Create separate WorkOS routes if `/login` or `/callback` are already taken (e.g., use `/auth/callback`)
+- Ensure existing auth routes, form actions, and session cookies continue to work unchanged
+- Document in code comments how to migrate fully to WorkOS AuthKit later
+
 ## Step 3: Install SDK
 
 Detect package manager, install SDK package from README.
 
 ```
-pnpm-lock.yaml? → pnpm add @workos-inc/authkit-sveltekit
-yarn.lock? → yarn add @workos-inc/authkit-sveltekit
-bun.lockb? → bun add @workos-inc/authkit-sveltekit
-else → npm install @workos-inc/authkit-sveltekit
+pnpm-lock.yaml? → pnpm add @workos/authkit-sveltekit
+yarn.lock? → yarn add @workos/authkit-sveltekit
+bun.lockb? → bun add @workos/authkit-sveltekit
+else → npm install @workos/authkit-sveltekit
 ```
 
 **Verify:** SDK package exists in node_modules before continuing.
@@ -57,7 +105,7 @@ If `src/hooks.server.ts` already exists with custom logic, use SvelteKit's `sequ
 
 ```typescript
 import { sequence } from '@sveltejs/kit/hooks';
-import { authkitHandle } from '@workos-inc/authkit-sveltekit'; // Check README for exact export
+import { authkitHandle } from '@workos/authkit-sveltekit'; // Check README for exact export
 
 export const handle = sequence(authkitHandle, yourExistingHandle);
 ```
@@ -126,7 +174,7 @@ pnpm build || npm run build
 
 ## Error Recovery
 
-### "Cannot find module '@workos-inc/authkit-sveltekit'"
+### "Cannot find module '@workos/authkit-sveltekit'"
 
 - Check: SDK installed before writing imports
 - Check: SDK package directory exists in node_modules

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:
 
@@ -86,34 +86,31 @@ Default redirect URI: `http://localhost:3000/api/auth/callback`
 
 **authkitMiddleware MUST be configured or auth will fail silently.**
 
-Create or update `src/start.ts` (or `app/start.ts` for legacy):
+**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`.**
 
-```typescript
-import { authkitMiddleware } from '@workos/authkit-tanstack-react-start';
+### If `start.ts` already exists
 
-export default {
-  requestMiddleware: [authkitMiddleware()],
-};
-```
+Read the existing file first. Add `authkitMiddleware` to the existing `requestMiddleware` array (or create the array if missing). Preserve the existing export style. Do not rewrite the file from scratch.
+
+### If `start.ts` does not exist
 
-Alternative pattern with createStart:
+Create `src/start.ts` (or `app/start.ts` for legacy) using `createStart`:
 
 ```typescript
 import { createStart } from '@tanstack/react-start';
 import { authkitMiddleware } from '@workos/authkit-tanstack-react-start';
 
-export default createStart({
+export const startInstance = createStart(() => ({
   requestMiddleware: [authkitMiddleware()],
-});
+}));
 ```
 
-### Verification Checklist
+**Two things matter here:**
 
-- [ ] `authkitMiddleware` imported from `@workos/authkit-tanstack-react-start`
-- [ ] Middleware in `requestMiddleware` array
-- [ ] File exports the config (default export or named `startInstance`)
+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.
 
-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)
 
@@ -208,6 +205,60 @@ function Profile() {
 
 **Note:** Server-side `getAuth()` is preferred for most use cases.
 
+## Finalize (REQUIRED before declaring success)
+
+After creating/editing all files, run these steps in order. Skipping them is the most common cause of build failures.
+
+### 1. Regenerate the route tree
+
+Adding new route files (callback, signout, etc.) makes the existing `routeTree.gen.ts` stale. The build will fail with type errors about missing routes until it is regenerated.
+
+```bash
+pnpm build 2>/dev/null || npx tsr generate
+```
+
+The build itself triggers route tree regeneration. If it fails for other reasons, use `tsr generate` directly.
+
+### 2. Ensure Vite type declarations exist
+
+TanStack Start projects import CSS with `import styles from './styles.css?url'`. Without Vite's type declarations, TypeScript will error on these imports. Check if `src/vite-env.d.ts` (or `app/vite-env.d.ts`) exists — if not, create it now (before attempting the build):
+
+```typescript
+/// <reference types="vite/client" />
+```
+
+### 3. Verify the build
+
+```bash
+pnpm build
+```
+
+Do not skip this step. If the build fails, fix the errors before finishing. Common causes:
+
+- Stale route tree → re-run step 1
+- 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