@jskit-ai/agent-docs 0.1.84 → 0.1.87

package/guide/agent/app-setup/authentication.md

@@ -961,39 +961,40 @@ That explains why the login screen and auth guard runtime both care about `/api/
 
 It is also why the shell widget can react cleanly to auth state without storing raw session tokens in client state. The browser just asks the app for the current session view, and the app derives that from its cookies plus the selected provider.
 
-### Authenticated Playwright testing with the dev auth bypass
+### Authenticated Playwright testing
 
-JSKIT ships a development-only auth bootstrap path specifically so authenticated UI can be verified in Playwright without depending on a real live login flow through an external auth provider.
+JSKIT supports two intentionally separate authenticated-browser paths:
 
-This is the standard path the agent should use for authenticated browser tests:
+- a private localhost exchange for direct local Playwright runs
+- runner-provided Playwright storage state for managed previews
 
-- enable the dev auth bypass in development
-- create a session for an existing user through the local app
-- let the browser keep the resulting HTTP-only cookies
-- navigate to the protected page and verify the feature
-- record the Playwright run through `jskit app verify-ui` so `jskit doctor` can verify the receipt later
+Neither path drives a live external login provider. Both put the resulting HTTP-only cookies into the same Playwright browser context that runs the feature assertions.
 
-The feature is intentionally narrow.
+The generated `playwright.config.mjs` is a thin delegate to `@jskit-ai/jskit-cli/test/playwright`. The published helper owns the changing setup behavior:
 
-- It is development-only.
-- It must never be enabled in production.
-- JSKIT rejects boot if `AUTH_DEV_BYPASS_ENABLED=true` while `NODE_ENV=production`.
-- The route only looks up an existing user. It does not create one.
+- without `PLAYWRIGHT_BASE_URL`, it builds the app and starts the local server on `http://127.0.0.1:4173`
+- with `PLAYWRIGHT_BASE_URL`, it uses that managed preview and does not start another server
+- with `JSKIT_PLAYWRIGHT_STORAGE_STATE`, it loads the supplied authenticated state into Playwright contexts
 
-The environment variables are:
+Tests should therefore navigate with relative paths such as `page.goto("/w/acme/admin/contacts")`.
+
+#### Direct local dev-auth login
+
+The local dev auth bypass remains deliberately narrow:
+
+- it is available only outside production
+- the request must arrive locally
+- it selects an existing user and never creates one
+- it requires both CSRF protection and a private exchange secret
+
+Enable it for the Playwright process and the local server it starts:
 
 ```bash
 AUTH_DEV_BYPASS_ENABLED=true
 AUTH_DEV_BYPASS_SECRET=replace-this-with-a-local-dev-secret
 ```
 
-When enabled outside production, the app exposes:
-
-```text
-POST /api/dev-auth/login-as
-```
-
-The request body must contain either:
+When enabled, the app exposes `POST /api/dev-auth/login-as`. The body contains exactly one existing-user identity:
 
 ```json
 { "userId": "7" }
@@ -1005,70 +1006,45 @@ or:
 { "email": "ada@example.com" }
 ```
 
-The response is intentionally small:
+Do not call that route from `page.evaluate()`. The route requires the private `x-jskit-dev-auth-secret` header as well as the CSRF token. Putting the secret into browser JavaScript, client-visible environment, query parameters, or page globals would defeat the exchange boundary.
 
-```json
-{
-  "ok": true,
-  "userId": "7",
-  "username": "Ada Example",
-  "email": "ada@example.com"
-}
-```
+Use the published Node-side helper instead:
 
-Behind the scenes, JSKIT creates the same HTTP-only auth cookies that the normal login flow would create. That means Playwright should not try to read raw tokens. It should bootstrap the session in the browser context, then navigate normally.
+```ts
+import { expect, test } from "@playwright/test";
+import { loginAsExistingUser } from "@jskit-ai/auth-web/test/playwright";
 
-One subtle point matters here:
+test("authenticated contacts filters", async ({ page }) => {
+  await loginAsExistingUser(page, { email: "ada@example.com" });
 
-- `/api/dev-auth/login-as` is still an unsafe `POST`
-- JSKIT still expects a CSRF token
-- the browser can get that token from `/api/session`
+  await page.goto("/w/acme/admin/contacts");
+  await expect(page.getByRole("heading", { name: "Contacts" })).toBeVisible();
+});
+```
 
-So the normal Playwright shape is:
+`loginAsExistingUser()` runs from the Playwright Node process. It uses the request client attached to `page.context()`, reads `csrfToken` from `GET /api/session`, sends that token plus `x-jskit-dev-auth-secret` to the login route, and leaves the response cookies in the same browser context. It reads `AUTH_DEV_BYPASS_SECRET` from the Node process by default and refuses to send it to a non-local URL.
 
-1. open a same-origin page first
-2. call `/api/session` to read `csrfToken`
-3. call `/api/dev-auth/login-as` with `credentials: "include"` and the `csrf-token` header
-4. navigate to the protected route and run the assertions
+That last restriction is important. A managed preview URL is not a direct localhost app connection, even when its backend eventually runs on the same infrastructure. Project code must not receive the managed host's private exchange authority.
 
-For example:
+#### Managed preview authentication
 
-```ts
-await page.goto("/");
+A managed host authenticates outside the project browser context. It performs its trusted identity exchange, writes the resulting cookies and origins to a temporary Playwright storage-state file, and starts the project test with:
 
-await page.evaluate(async ({ email }) => {
-  const sessionResponse = await fetch("/api/session", {
-    credentials: "include"
-  });
-  if (!sessionResponse.ok) {
-    throw new Error(`Session bootstrap failed: ${sessionResponse.status}`);
-  }
+```bash
+PLAYWRIGHT_BASE_URL=https://managed-preview.example.test \
+JSKIT_PLAYWRIGHT_STORAGE_STATE=/secure/temp/playwright-state.json \
+playwright test tests/e2e/contacts.spec.ts
+```
 
-  const sessionPayload = await sessionResponse.json();
-  const csrfToken = String(sessionPayload?.csrfToken || "");
-  if (!csrfToken) {
-    throw new Error("Missing csrfToken from /api/session.");
-  }
+JSKIT only consumes that runner-neutral contract. It does not detect a particular host, call host-specific commands, proxy private headers, or install a browser.
 
-  const loginResponse = await fetch("/api/dev-auth/login-as", {
-    method: "POST",
-    credentials: "include",
-    headers: {
-      "content-type": "application/json",
-      "csrf-token": csrfToken
-    },
-    body: JSON.stringify({ email })
-  });
+The storage-state file is a secret because it can contain authenticated cookies. The managed runner must create it with appropriately restricted access, must not print or commit it, and must delete it after the run.
 
-  if (!loginResponse.ok) {
-    throw new Error(`Dev login failed: ${loginResponse.status} ${await loginResponse.text()}`);
-  }
-}, { email: "ada@example.com" });
+Tests using managed state do not call `loginAsExistingUser()`. They begin with the runner-provided identity already present and navigate using relative paths. An ordinary browser or proxy request to `/api/dev-auth/login-as` without the private header must continue to fail with `403 Dev auth exchange is not authorized.`
 
-await page.goto("/w/acme/admin/contacts");
-```
+#### Recording the result
 
-In practice, the preferred wrapper is:
+After the actual Playwright flow succeeds, record it through JSKIT:
 
 ```bash
 npx jskit app verify-ui \
@@ -1077,20 +1053,17 @@ npx jskit app verify-ui \
   --auth-mode dev-auth-login-as
 ```
 
-For local pre-merge review, the next step after recording that Playwright run is usually:
+Use `--auth-mode session-bootstrap` when a managed runner supplied authenticated storage state.
+
+`jskit app verify-ui` executes the command and records the command, auth-mode label, feature, and changed UI files. The `--auth-mode` value describes how the Playwright command was authenticated. It does not create a session, inject a secret, or alter the browser context.
+
+For local pre-merge review, follow the recorded run with:
 
 ```bash
 npx jskit doctor --against origin/main
 ```
 
-Advanced CI pipelines can use the same `--against` contract too, but JSKIT does not scaffold hosted auth/database/browser verification by default.
-
-That flow is preferable to driving the real sign-in form in feature tests because it keeps the test focused on the UI feature being added, not on an external auth dependency. If a chunk changes user-facing UI and the flow requires login, the expected JSKIT review standard is:
-
-- use Playwright
-- record the run with `jskit app verify-ui`
-- use the local dev auth bypass or another local session bootstrap path
-- exercise the actual changed behavior, not only page load
+This keeps feature tests focused on the changed UI while preserving the security boundary around session creation.
 
 ## When you later switch to Supabase
 

package/guide/agent/app-setup/initial-scaffolding.md

@@ -162,7 +162,6 @@ The most important parts look like this:
     "server": "node ./bin/server.js",
     "server:all": "node ./bin/server.js",
     "server:home": "SERVER_SURFACE=home node ./bin/server.js",
-    "devlinks": "jskit app link-local-packages",
     "dev": "vite",
     "dev:all": "vite",
     "dev:home": "VITE_SURFACE=home vite",
@@ -206,9 +205,11 @@ The most important parts look like this:
 
 Published JSKIT libraries and tooling support Node.js 22 from 22.12.0 onward, Node.js 24, and Node.js 26. Newly generated applications deliberately require Node 26: their app-level `engines` contract, `.nvmrc`, and JSKIT-managed verification workflow all name that runtime. The app-level contract is the runtime boundary for the app and its installed JSKIT runtime packages, while independently consumed JSKIT CLI and tooling packages retain the wider supported range. The dependency on `@local/main` points at `file:packages/main`, which means your app already contains its own local JSKIT package. The maintenance scripts are also useful to notice early, because they show an important ownership boundary in JSKIT.
 
-`verify`, `jskit:update`, `devlinks`, and `release` are intentionally thin wrappers. They stay in `package.json` because they are convenient app-local shortcuts, but the real implementation lives in `jskit app ...`, not in copied scaffold scripts.
+`verify`, `jskit:update`, and `release` are intentionally thin wrappers. They stay in `package.json` because they are convenient app-local shortcuts, but the real implementation lives in `jskit app ...`, not in copied scaffold scripts.
 
-That matters because JSKIT maintenance policy changes over time. If the scaffold copied a large shell script into every app, existing apps would freeze the old behavior forever. By delegating to `jskit app verify`, `jskit app update-packages`, `jskit app link-local-packages`, and `jskit app release`, the app keeps the nice `npm run` shortcuts while the maintained behavior stays in the installed CLI package.
+That matters because JSKIT maintenance policy changes over time. If the scaffold copied a large shell script into every app, existing apps would freeze the old behavior forever. By delegating to `jskit app verify`, `jskit app update-packages`, and `jskit app release`, the app keeps the nice `npm run` shortcuts while the maintained behavior stays in the installed CLI package.
+
+The Playwright scaffold follows the same rule. `playwright.config.mjs` delegates to `@jskit-ai/jskit-cli/test/playwright`, and the starter browser specs delegate their shared responsive checks to published JSKIT helpers. The generated files stay small while later JSKIT package updates can change local server startup, managed `PLAYWRIGHT_BASE_URL` handling, and `JSKIT_PLAYWRIGHT_STORAGE_STATE` support without copying that logic into each new app.
 
 `jskit app verify` is worth noticing specifically. Linting, tests, and builds check your source code and runtime behavior. The JSKIT part of that flow runs `doctor`, which checks JSKIT-managed app state: installed package visibility, lock-file-backed managed files, and other JSKIT-specific health rules. It is there because a JSKIT app is not only code. It is also a descriptor-driven managed project.
 
@@ -817,7 +818,7 @@ That is why you saw `@jskit-ai/kernel` and `@jskit-ai/http-runtime` earlier in `
 
 ### Other files and options
 
-The remaining files are easier to understand once you know the core pieces above. `vite.config.mjs` configures the frontend build and the `/api` proxy used during development. `index.html` is the HTML shell Vite uses to mount Vue. `tests/` contains basic smoke tests so the app has a verification path from day one. The `scripts/` directory is intentionally small because JSKIT maintenance helpers such as `verify`, `jskit:update`, `devlinks`, and `release` are package-owned CLI commands rather than copied app scripts.
+The remaining files are easier to understand once you know the core pieces above. `vite.config.mjs` configures the frontend build and the `/api` proxy used during development. `index.html` is the HTML shell Vite uses to mount Vue. `tests/` contains basic smoke tests so the app has a verification path from day one. The `scripts/` directory is intentionally small because JSKIT maintenance helpers such as `verify`, `jskit:update`, and `release` are package-owned CLI commands rather than copied app scripts.
 
 The `create-app` command also accepts a few other flags that are useful without changing the basic meaning of this chapter's setup. `--title <text>` lets you replace the browser title and other template text with a friendlier app name. `--target <path>` lets you choose a different output directory instead of the default `./exampleapp`. `--tenancy-mode <mode>` can seed `none`, `personal`, or `workspaces`; for this chapter we intentionally use `none` so the first scaffold stays small and non-workspace. `--minimal` selects the bare `minimal-shell` template instead of the default shell-web app template. `--force` allows writing into a non-empty target directory when you know that is what you want. `--dry-run` prints the planned file writes without touching the filesystem, which is useful when you want to inspect what the generator would do. `-h` or `--help` prints the command help.
 

package/guide/agent/app-setup/working-with-the-jskit-cli.md

@@ -53,7 +53,6 @@ The important examples are:
 
 - `npm run verify`
 - `npm run jskit:update`
-- `npm run devlinks`
 - `npm run release`
 
 In the current scaffold, those scripts are intentionally thin:
@@ -63,7 +62,6 @@ In the current scaffold, those scripts are intentionally thin:
   "scripts": {
     "verify": "jskit app verify && npm run --if-present verify:app",
     "jskit:update": "jskit app update-packages",
-    "devlinks": "jskit app link-local-packages",
     "release": "jskit app release"
   }
 }
@@ -71,12 +69,11 @@ In the current scaffold, those scripts are intentionally thin:
 
 That is a deliberate design choice.
 
-The app keeps the handy `npm run` names, but the real maintenance policy lives in the installed CLI package instead of copied shell scripts inside the app. That means if JSKIT later changes how package updates, local linking, or baseline verification should work, apps can pick up the new behavior by updating `@jskit-ai/jskit-cli` instead of hand-editing frozen scaffold files.
+The app keeps the handy `npm run` names, but the real maintenance policy lives in the installed CLI package instead of copied shell scripts inside the app. That means if JSKIT later changes how package updates or baseline verification should work, apps can pick up the new behavior by updating `@jskit-ai/jskit-cli` instead of hand-editing frozen scaffold files.
 
 This gives you a clean ownership split:
 
 - app-owned scripts still describe how *this app* runs, builds, and tests
-- `npm run devlinks` re-applies local checkout links after `npm install` when you are testing an app against this monorepo
 - JSKIT-owned wrapper scripts delegate framework maintenance to `jskit app ...`
 
 That split is worth keeping in mind through the rest of the guide. When you see `npm run verify`, read it as "run the app's JSKIT baseline verification policy, then any app-specific extra verification hook".
@@ -116,14 +113,9 @@ npm run jskit:update
 
 After it succeeds, npm dependencies and descriptor-managed app state are current together. If a managed app-owned file is missing, a required saved option can no longer be resolved, or another package update cannot be applied safely, the app-wide update fails instead of leaving that package silently stale. `--dry-run` reports which installed packages would be reapplied without invoking their update lifecycle.
 
-There is one unavoidable bootstrap detail for apps whose installed CLI predates managed package reapplication: a CLI process that is already running cannot adopt code npm installs underneath it. Upgrade the CLI once, then run the app-wide update with the new process:
+At the start of a real update, JSKIT resolves and installs the latest `@jskit-ai/jskit-cli`, then hands the rest of the operation to that app-local CLI process. This keeps the one-command contract even when the updater itself has changed: the current code, not the already-running older process, owns package reapplication, migrations, workspace refreshes, and CI synchronization.
 
-```bash
-npm install --save-dev --save-exact @jskit-ai/jskit-cli@latest
-npm run jskit:update
-```
-
-After that bootstrap, normal future upgrades use only `npm run jskit:update`. Do not work around the first upgrade by editing `.jskit/lock.json`; the new updater must reapply the descriptor contract and write managed state itself.
+Do not pre-install the CLI separately and do not edit `.jskit/lock.json`. Run `npm run jskit:update`; the updater owns its bootstrap and writes managed state through the normal package lifecycle.
 
 The update reports elapsed progress for registry and install work. It also refreshes JSKIT-managed migrations and CI after root package changes. Preview the complete operation without changing manifests, descriptors, the lockfile, migrations, or CI with:
 
@@ -571,12 +563,6 @@ npm install
 
 `jskit add` changes the app. `npm install` downloads the dependencies that the changed app requires.
 
-If the app is being tested against a local JSKIT checkout with linked packages, run the local-link wrapper again after every `npm install`:
-
-```bash
-npm run devlinks
-```
-
 ### `add bundle`
 
 Bundles are a convenience layer for catalog shortcuts. Prefer package commands in setup docs and normal app work, especially for auth, because provider ownership is clearer when the selected provider package is installed explicitly.
@@ -818,6 +804,8 @@ That command does two things:
 - runs the targeted Playwright command you give it
 - writes a receipt describing the verified feature, auth mode, and current dirty UI file set
 
+The auth mode is receipt metadata, not an authentication implementation. `jskit app verify-ui` does not log a user in, inject a secret, or rewrite the Playwright context. A direct local run uses `loginAsExistingUser()` from `@jskit-ai/auth-web/test/playwright`; a managed runner supplies authenticated state through `JSKIT_PLAYWRIGHT_STORAGE_STATE`. The generated `playwright.config.mjs` consumes that state and honors `PLAYWRIGHT_BASE_URL` without starting a second server.
+
 `doctor` then compares the current changed UI files to that receipt. If you edit the UI again afterwards, the receipt is stale and `doctor` tells you to rerun `jskit app verify-ui`.
 
 For local pre-merge review, use `--against <base-ref>` so JSKIT compares against the branch delta instead of only the current dirty worktree. The common shape is:

package/guide/agent/generators/crud-generators.md

@@ -314,12 +314,6 @@ So before you build or run the app again, install that new local package:
 npm install
 ```
 
-If you are verifying the guide against a local JSKIT checkout and have already been using local package links, rerun:
-
-```bash
-npm run devlinks
-```
-
 The same rule applies after later server scaffolds such as `addresses` and `comments`. The UI generator can still read the generated resource file directly, but the app runtime needs the local package install boundary to be completed before the CRUD can boot normally.
 
 For standard CRUDs, that file is intentionally compact. It uses `defineCrudResource(...)` from `@jskit-ai/resource-crud-core`, authors the canonical `schema` / `searchSchema` / `defaultSort` / `autofilter` shape once, and lets JSKIT derive the standard CRUD operation contracts from it.
@@ -435,12 +429,6 @@ Then install the generated local package:
 npm install
 ```
 
-If you are developing against a local JSKIT checkout, relink your app to the local packages before you run the UI:
-
-```bash
-npm run devlinks
-```
-
 ### Step 3: refine the generated lookup metadata by hand
 
 Open `packages/addresses/src/shared/addressResource.js` and add `labelKey: "fullName"` to the generated `contactId` relation:
@@ -617,12 +605,6 @@ Then install the generated local package:
 npm install
 ```
 
-If you are developing against a local JSKIT checkout, relink the app before you run the UI:
-
-```bash
-npm run devlinks
-```
-
 ### Step 3: refine the generated lookup metadata by hand
 
 Open `packages/comments/src/shared/commentResource.js` and add `labelKey: "fullName"` to the generated `contactId` relation:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.84",
+  "version": "0.1.87",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/patterns/ui-testing.md

@@ -11,80 +11,88 @@ Rules:
 
 - Any chunk that adds or changes user-facing UI must include a Playwright flow that exercises the changed behavior before the chunk is done.
 - Generator or package template UI changes must be checked at compact phone, tablet-ish medium, and expanded desktop widths.
-- For generated UI, the browser checks should cover horizontal overflow, clipped text, invisible text, duplicate navigation, broken route placement, and tap targets under 48 px.
-- Apps with `shell-web` installed should start from the generated `tests/e2e/adaptive-shell.spec.ts` smoke and extend it for feature-specific assertions.
-- Record that Playwright run with `jskit app verify-ui --command "<playwright command>" --feature "<label>" --auth-mode <mode>`.
-- `jskit doctor` expects `.jskit/verification/ui.json` to match the current dirty UI file set when UI files are changed.
-- For local pre-merge review, follow the recorded Playwright run with `jskit doctor --against <base-ref>` so `doctor` compares against the branch delta instead of only the local dirty worktree.
-- Advanced CI setups may also use `--against <base-ref>`, but JSKIT does not scaffold hosted browser/auth/database verification by default.
-- Do not rely on a live external auth provider for Playwright verification of normal app features.
-- For authenticated UI in the standard JSKIT auth stack, use the development-only dev auth bypass route instead.
-- The standard route is `POST /api/dev-auth/login-as`.
-- The request body must include either `{ userId }` or `{ email }`.
-- The route is available only when `AUTH_DEV_BYPASS_ENABLED=true` and `AUTH_DEV_BYPASS_SECRET` is set outside production.
-- This route must never be enabled in production.
-- Because the route is an unsafe POST, fetch `csrfToken` from `/api/session` first and send it back as the `csrf-token` header.
-- Make the bootstrap request from the same browser context that will run the assertions so the auth cookies land in the page session.
-- Use stable seeded users or fixtures for Playwright. Do not depend on whatever account happens to exist in a developer's browser or external auth provider.
-
-Recommended flow:
+- For generated UI, check horizontal overflow, clipped or invisible text, duplicate navigation, broken route placement, and tap targets under 48 px.
+- Apps with `shell-web` installed should start from `tests/e2e/adaptive-shell.spec.ts` and extend it with feature-specific assertions.
+- Generated `playwright.config.mjs` delegates to `@jskit-ai/jskit-cli/test/playwright`. Do not copy base-URL, web-server, or storage-state logic into app tests.
+- Use relative paths such as `page.goto("/home")`. The shared config owns the browser base URL.
+- A managed runner supplies `PLAYWRIGHT_BASE_URL`. When it is set, JSKIT does not start another app server.
+- A managed runner supplies an authenticated context through `JSKIT_PLAYWRIGHT_STORAGE_STATE`. Treat that file as a temporary secret: do not commit it, print it, or retain it after the run.
+- Do not install a browser when the environment provides a managed browser runner.
+
+## Direct local authentication
+
+Use the development-only dev auth bypass when Playwright is talking directly to an app running on localhost.
+
+The app must start with:
 
 ```bash
-npx jskit app verify-ui \
-  --command "npx playwright test tests/e2e/contacts.spec.ts -g filters" \
-  --feature "contacts filters" \
-  --auth-mode dev-auth-login-as
+AUTH_DEV_BYPASS_ENABLED=true
+AUTH_DEV_BYPASS_SECRET=replace-this-with-a-local-dev-secret
+```
+
+The test uses the published Node-side helper:
+
+```ts
+import { expect, test } from "@playwright/test";
+import { loginAsExistingUser } from "@jskit-ai/auth-web/test/playwright";
+
+test("authenticated feature", async ({ page }) => {
+  await loginAsExistingUser(page, { email: "ada@example.com" });
+  await page.goto("/w/acme/admin/contacts");
+  await expect(page.getByRole("heading", { name: "Contacts" })).toBeVisible();
+});
 ```
 
-Local pre-merge follow-up:
+`loginAsExistingUser()`:
+
+- uses the request client belonging to the same Playwright browser context
+- fetches the CSRF token from `GET /api/session`
+- sends the CSRF token and private `x-jskit-dev-auth-secret` header to `POST /api/dev-auth/login-as`
+- leaves the resulting HTTP-only cookies in that browser context
+- refuses to send the secret to a non-local URL
+
+The helper reads `AUTH_DEV_BYPASS_SECRET` from the Playwright Node process by default. Never pass that secret through `page.evaluate()`, browser globals, query parameters, or client-visible environment variables.
+
+The route only selects an existing user. Seed a stable user or fixture before the test. The bypass must never be enabled in production.
+
+## Managed-host authentication
+
+A managed preview must not expose `AUTH_DEV_BYPASS_SECRET` to project code or forward an ordinary browser request to the private login exchange. The host performs its trusted identity exchange outside the application browser context, writes a temporary Playwright storage-state file, and launches the test with:
 
 ```bash
-npx jskit doctor --against origin/main
+PLAYWRIGHT_BASE_URL=https://managed-preview.example.test \
+JSKIT_PLAYWRIGHT_STORAGE_STATE=/secure/temp/playwright-state.json \
+playwright test tests/e2e/contacts.spec.ts
 ```
 
-The Playwright command itself should follow this setup shape when login is needed:
+The generated config applies that state to Playwright contexts and omits its local `webServer`. Tests then navigate with relative paths and begin with the runner-provided identity already authenticated.
 
-```ts
-await page.goto("/");
-
-await page.evaluate(async ({ email }) => {
-  const sessionResponse = await fetch("/api/session", {
-    credentials: "include"
-  });
-  if (!sessionResponse.ok) {
-    throw new Error(`Session bootstrap failed: ${sessionResponse.status}`);
-  }
-
-  const sessionPayload = await sessionResponse.json();
-  const csrfToken = String(sessionPayload?.csrfToken || "");
-  if (!csrfToken) {
-    throw new Error("Missing csrfToken from /api/session.");
-  }
-
-  const loginResponse = await fetch("/api/dev-auth/login-as", {
-    method: "POST",
-    credentials: "include",
-    headers: {
-      "content-type": "application/json",
-      "csrf-token": csrfToken
-    },
-    body: JSON.stringify({ email })
-  });
-
-  if (!loginResponse.ok) {
-    throw new Error(`Dev login failed: ${loginResponse.status} ${await loginResponse.text()}`);
-  }
-}, { email: "ada@example.com" });
+Do not call `loginAsExistingUser()` against a managed preview. It is deliberately localhost-only. An ordinary request to `/api/dev-auth/login-as` without the private exchange header must return `403`.
+
+## Recording verification
+
+After the Playwright command succeeds, record it with:
+
+```bash
+npx jskit app verify-ui \
+  --command "npx playwright test tests/e2e/contacts.spec.ts -g filters" \
+  --feature "contacts filters" \
+  --auth-mode dev-auth-login-as
 ```
 
-After that bootstrap:
+Use `--auth-mode session-bootstrap` when a managed runner supplied authenticated storage state.
+
+`jskit app verify-ui` runs the command and records its command, auth-mode label, feature, and changed UI files in `.jskit/verification/ui.json`. The auth-mode option describes how the command was authenticated; it does not create a session or modify the Playwright context.
+
+For local pre-merge review, follow the recorded run with:
 
-- navigate to the protected page
-- exercise the new UI behavior
-- assert the actual outcome the chunk introduced
+```bash
+npx jskit doctor --against origin/main
+```
 
 Do not mark the chunk done if:
 
 - the feature changed user-facing UI but no Playwright flow ran
 - the Playwright flow skipped the changed behavior itself
-- authenticated UI work was left untested because no local auth bootstrap path was available and that gap was not called out
+- a managed environment was bypassed by installing another browser
+- an authenticated flow was left untested without clearly reporting the missing session-bootstrap seam

package/reference/autogen/tooling/create-app.md

@@ -116,6 +116,10 @@ Exports
 Exports
 - None
 
+### `templates/base-shell/playwright.config.mjs`
+Exports
+- None
+
 ### `templates/base-shell/server.js`
 Exports
 - `createServer()`
@@ -266,6 +270,10 @@ Exports
 Exports
 - None
 
+### `templates/minimal-shell/playwright.config.mjs`
+Exports
+- None
+
 ### `templates/minimal-shell/server.js`
 Exports
 - `createServer()`

package/reference/autogen/tooling/jskit-cli.md

@@ -512,15 +512,6 @@ Exports
 Local functions
 - `shouldRewriteScript(currentValue = "", scriptName = "", force = false)`
 
-### `src/server/commandHandlers/appCommands/linkLocalPackages.js`
-Exports
-- `runAppLinkLocalPackagesCommand(ctx = {}, { appRoot = "", options = {}, stdout })`
-Local functions
-- `collectDeclaredPackageNames(packageJson = {})`
-- `verifySymlinkTarget(targetPath = "", sourceDir = "", { packageName = "" } = {})`
-- `replaceWithSymlink(targetPath = "", sourceDir = "", { packageName = "" } = {})`
-- `maybeLinkCompanionPackages({ appRoot = "", repoRoot = "", stdout, createCliError })`
-
 ### `src/server/commandHandlers/appCommands/migrateSourceMutations.js`
 Exports
 - `buildCrudFormFieldPushMigration(sourceText = "")`
@@ -558,11 +549,7 @@ Exports
 - `formatUtcReleaseTimestamp(date = new Date())`
 - `resolveLocalJskitBin(appRoot = "")`
 - `runLocalJskit(appRoot, args = [], { stdout, stderr, createCliError, quiet = false } = {})`
-- `runLocalJskitAsync(appRoot, args = [], { stdout, stderr, createCliError, quiet = false } = {})`
-- `resolveLocalRepoRoot({ appRoot = "", explicitRepoRoot = "" } = {})`
-- `discoverLocalPackageMap(repoRoot = "")`
-- `linkPackageBinEntries({ appRoot, packageDirName, sourceDir, stdout } = {})`
-- `resolveSymlinkType()`
+- `runLocalJskitAsync(appRoot, args = [], { env = {}, stdout, stderr, createCliError, quiet = false } = {})`
 Local functions
 - `ensureCommandSucceeded(result, label, { createCliError, cwd = "", stdout, stderr, quiet = false } = {})`
 
@@ -752,11 +739,11 @@ Local functions
 - `collectPlacementComponentTokensFromManagedRecords(installedPackageRecords = [])`
 - `renderWrappedShellCommand(binaryName, args = [], { maxWidth = 100, continuationIndent = " " } = {})`
 - `runLocalProjectBinary(binaryName, args = [], { appRoot, io, pathModule = path, createCliError, explanation = "", dryRun = false } = {})`
-- `installAppDependenciesForHook({ appRoot, appPackageJson, io, pathModule = path, createCliError, dryRun = false, runDevlinks = false } = {})`
+- `installAppDependenciesForHook({ appRoot, io, pathModule = path, createCliError, dryRun = false } = {})`
 - `resolvePackageOptionInputForInstall({ packageEntry, existingInstall, packageInlineOptions, appRoot, readFileBufferIfExists })`
 - `validateHookResult(result = {}, { packageId = "", hookLabel = "" } = {})`
 - `loadInstallHook({ packageEntry, appRoot, hookSpec, hookLabel = "" } = {})`
-- `createInstallHookHelpers({ ctx, appRoot, io, appPackageJson, commandOptions = {} } = {})`
+- `createInstallHookHelpers({ ctx, appRoot, io, appPackageJson } = {})`
 - `invokeInstallHook({ packageEntry, appRoot, hookSpec, hookLabel, hookContext, createCliError } = {})`
 
 ### `src/server/commandHandlers/packageCommands/create.js`