fix: require AuthKit sign-out and initiate-login setup

[nicknisi]

Summary

Addresses AUTH-6794.

The integration could build and sign users in while sign-out and externally started login were still broken. This PR makes their configuration and verification required setup steps.

• Add a shared application-URL checklist, linked from the router and every AuthKit framework guide. Distinguish callback, default Sign-out URI, and Initiate login URI.
• Require a separate SDK-backed /sign-in route in Next.js. Never use the callback as the initiate-login endpoint.
• Require explicit environment targeting, preservation of existing URLs/defaults, validation before replacement writes, and read-back afterward. Correct CLI authentication, discovery, command, and JSON examples.
• Report missing access or untested flows as unfinished work. Explain that claiming an environment or signing into the app does not authenticate the CLI, and document the misleading app-homepage-url-not-found sign-out error.

No SDK, CLI implementation, or version bumps are included here. The companion installer changes ship separately in workos/cli.

Verification

Automated checks

• pnpm test: 202 tests passed.
• pnpm lint and pnpm build.
• pnpm eval -- --dry-run: 69 cases loaded.
• Formatting check on all changed files and git diff --check.
• pnpm pack: shared setup reference is included in the package.
• Environment-targeting review feedback addressed and covered by a regression test.

Repository-wide formatting has pre-existing failures outside this diff; those files are unchanged.

Runtime and live verification

Check	Evidence
Fresh installer run and rerun	Isolated Next.js app using these skills and the local companion CLI changes; separate sign-in route created, missing dashboard access reported as pending.
Sign-in route	HTTP 307 to WorkOS with a separate callback URL and an HttpOnly PKCE cookie matching the authorization state.
Saved application settings	Matched the real app client ID to its claimed sandbox. Found sign-out and initiate-login settings missing, configured them through the native helper after CLI authentication, and verified them by API read-back. Existing callback preserved.
Normal sign-in	Confirmed by the user in the test app.
Sign-out	Initially reproduced app-homepage-url-not-found; user confirmed it worked after the default Sign-out URI was configured.
Externally started login	Confirmed by the user after the email-link test instructions.

The live test required finishing the pending configuration after CLI login. It was not proof that claiming an environment alone, or the currently published installer, performs the complete setup automatically. These runtime results include companion CLI changes, not this skills diff alone. Other framework guides received the shared requirement but were not browser-tested.

Eval limits

Four focused model scenarios were run during development. Transcript review caught unsafe replacement advice that the keyword/order scorer missed, including a case scoring two points lower despite safer guidance. Those scores are not a final acceptance gate. Full regression gates and the router JSON scenarios were not run; runtime verification above is the stronger evidence for the tested Next.js flow.

Release order

1. Merge this PR and release @workos/skills.
2. Review and ship the separate CLI changes for prompt injection, native configuration, route validation, and truthful completion reporting. Update its skills dependency to the release containing this reference, then rebuild the embedded assets.
3. Repeat the fresh-install smoke test with the released CLI.

Do not ship the companion CLI prompt loader with the old skills package: it requires workos-authkit-setup.md. Publishing this skills PR alone does not distribute the native installer fixes.

[linear-code]

AUTH-6794

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; no actionable new defect or outstanding previous finding remains.

Summary

This PR strengthens AuthKit installation guidance so application URL configuration and end-to-end authentication flows are required before setup is considered complete.

• Adds a shared reference for safely configuring and verifying callback, Sign-out, and Initiate login URIs.
• Adds a separate SDK-backed Next.js initiate-login route and clarifies safe sign-out behavior.
• Corrects CLI authentication, environment targeting, replacement-write, read-back, and JSON-output guidance.
• Adds evaluation scenarios and regression tests for the new setup requirements and recovery guidance.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  E[Confirm target environment and application] --> C[Configure exact callback URI]
  C --> I[Configure SDK-backed Initiate login URI]
  I --> S[Configure default Sign-out URI]
  S --> R[Read settings back]
  R --> N[Test normal sign-in and callback]
  N --> X[Test externally initiated sign-in]
  X --> O[Test sign-out and protected-content denial]
  O --> B[Run framework build and integration checks]

Loading

_{Reviews (4) · Last reviewed commit: "fix: clarify CLI authentication and sign..."}

[nicknisi]

Follow-up from real installer testing: f352128 adds an explicit SDK-backed /sign-in route to the Next.js reference, separates it from handleAuth()/the callback, and explains the installer permission boundary. The CLI follow-up now injects the shared reference, performs scoped native configuration outside the agent, validates the required route, and preserves incomplete configuration in the final report. Those CLI changes are local and depend on releasing this PR. Verification: 201 skills tests pass; the local CLI passes 2,806 tests plus build/typecheck/lint. A real isolated fresh install and rerun created the separate route and reported dashboard configuration as pending without a session. An HTTP smoke check returned 307 to the WorkOS authorization endpoint with the separate callback and matching HttpOnly PKCE cookie. Live dashboard writes and full authenticated browser flows remain unverified.