@jskit-ai/agent-docs 0.1.1 → 0.1.3

package/DISTR_AGENT.md

@@ -5,8 +5,9 @@ Read these in order:
 1. `workflow/app-state.md`
 2. `workflow/bootstrap.md` if the workspace is empty or no JSKIT app exists yet
 3. `workflow/scoping.md`
-4. `workflow/feature-delivery.md`
-5. `workflow/review.md`
+4. `workflow/workboard.md`
+5. `workflow/feature-delivery.md`
+6. `workflow/review.md`
 
 Use these references on demand:
 
@@ -15,11 +16,17 @@ Use these references on demand:
 - `guide/agent/index.md`
 - `guide/human/index.md` when compressed guidance is ambiguous or missing nuance
 - `templates/APP_BLUEPRINT.md`
+- `templates/WORKBOARD.md`
+- `skills/jskit-review/SKILL.md` for review passes when your Codex environment supports packaged skills
 
 Core rules:
 
 - Inspect the workspace before assuming a JSKIT app exists.
 - Reuse existing JSKIT helpers and runtime seams before adding new local helpers.
+- A freshly scaffolded JSKIT app can still be in Stage 1. If platform decisions are not settled yet, continue with the initialize workflow before adding runtime packages.
+- Do not treat a missing `config.tenancyMode` line or an untouched minimal scaffold as a final tenancy decision.
+- Do not install tenancy-sensitive packages until Stage 1 decisions are complete and the chosen tenancy is written into `config/public.js`.
 - Do not implement app features before the blueprint has the database, surfaces, ownership model, and route/screen plan written down.
+- For substantial or multi-chunk work, create or update `.jskit/WORKBOARD.md` as the per-request execution tracker.
 - Use the compressed guide first for speed; fall back to the human guide when a workflow trap, migration caveat, or architectural boundary needs exact wording.
 - Treat generated reference maps and guide copies as vendor reference. Do not edit them manually.

package/guide/agent/app-extras/assistant.md

@@ -1,4 +1,4 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/app-extras/assistant.md`. Do not edit manually. -->
+<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/guide/human/app-extras/assistant.md`. Do not edit manually. -->
 
 # Assistant
 

package/guide/agent/app-extras/realtime.md

@@ -1,4 +1,4 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/app-extras/realtime.md`. Do not edit manually. -->
+<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/guide/human/app-extras/realtime.md`. Do not edit manually. -->
 
 # Realtime
 

package/guide/agent/app-setup/a-more-interesting-shell.md

@@ -1,4 +1,4 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/app-setup/a-more-interesting-shell.md`. Do not edit manually. -->
+<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/guide/human/app-setup/a-more-interesting-shell.md`. Do not edit manually. -->
 
 # A more interesting shell
 

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

@@ -1,4 +1,4 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/app-setup/authentication.md`. Do not edit manually. -->
+<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/guide/human/app-setup/authentication.md`. Do not edit manually. -->
 
 # Authentication
 

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

@@ -1,4 +1,4 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/app-setup/console.md`. Do not edit manually. -->
+<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/guide/human/app-setup/console.md`. Do not edit manually. -->
 
 # Console
 

package/guide/agent/app-setup/database-layer.md

@@ -1,4 +1,4 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/app-setup/database-layer.md`. Do not edit manually. -->
+<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/guide/human/app-setup/database-layer.md`. Do not edit manually. -->
 
 # Database layer
 

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

@@ -1,4 +1,4 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/app-setup/initial-scaffolding.md`. Do not edit manually. -->
+<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/guide/human/app-setup/initial-scaffolding.md`. Do not edit manually. -->
 
 # Initial scaffolding
 
@@ -14,6 +14,16 @@ npm install
 
 The first command creates a new folder called `exampleapp` and fills it with JSKIT's base shell template. The `exampleapp` name is used in a few template replacements, such as the package name and the browser title. The `--tenancy-mode none` flag tells JSKIT to start with the smallest routing model. In this mode, the app is not workspace-aware (more of this later in the guide, when multihoming is introduced). That keeps the first scaffold easier to read because there is no workspace slug handling yet.
 
+If you are working with an AI agent and want the agent to explain the platform options after the scaffold exists, there is also a safe guided path:
+
+```bash
+npx @jskit-ai/create-app exampleapp
+cd exampleapp
+npm install
+```
+
+That produces the same minimal scaffold shape, but without writing an explicit `config.tenancyMode` line yet. The important rule is that this does **not** mean tenancy is already decided. Before installing tenancy-sensitive packages such as `workspaces-core` or `workspaces-web`, the agent still needs to finish the Stage 1 platform conversation and then write the chosen tenancy into `config/public.js`. If workspace packages are installed while the app is still effectively on `none`, you fall into the recovery path described later in the multi-homing chapter.
+
 After creating the scaffolding (which comes with a package.json file), you will need to run `npm install` to install dependencies.
 
 **Try Bash Completion!**
@@ -103,6 +113,7 @@ 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",
@@ -111,7 +122,9 @@ The most important parts look like this:
     "build:home": "VITE_SURFACE=home vite build",
     "test": "node --test",
     "test:client": "vitest run tests/client",
-    "verify": "npm run lint && npm run test && npm run test:client && npm run build && npx jskit doctor"
+    "verify": "jskit app verify && npm run --if-present verify:app",
+    "release": "jskit app release",
+    "jskit:update": "jskit app update-packages"
   },
   "dependencies": {
     "@local/main": "file:packages/main",
@@ -130,9 +143,13 @@ The most important parts look like this:
 }
 ```
 
-There are two details worth noticing immediately. The dependency on `@local/main` points at `file:packages/main`, which means your app already contains its own local JSKIT package. The `verify` script is also useful to notice early, because it shows the default quality gate the scaffold expects you to run later.
+There are two details worth noticing immediately. 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 now 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.
 
-The last command in that script, `npx jskit doctor`, is worth noticing specifically. Linting, tests, and builds check your source code and runtime behavior. `doctor` 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.
+`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.
 
 The surface-specific script names are also worth noticing early, even in this tiny app. `dev:home`, `server:home`, and `build:home` are the first concrete places where surface selection shows up in the scaffold. They work by setting `VITE_SURFACE=home` on the client side and `SERVER_SURFACE=home` on the server side. In this first chapter, where `home` is the only surface, those variants behave almost the same as the default commands. Later, once more surfaces exist, those scripts become the simplest way to run or build just one surface at a time.
 
@@ -699,7 +716,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 collects helper scripts for release, updating JSKIT packages, and linking a local JSKIT checkout during framework development.
+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 now much smaller than it used to be, because JSKIT maintenance helpers such as `verify`, `jskit:update`, `devlinks`, 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. `--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/multi-homing.md

@@ -1,4 +1,4 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/app-setup/multi-homing.md`. Do not edit manually. -->
+<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/guide/human/app-setup/multi-homing.md`. Do not edit manually. -->
 
 # Multi-homing
 

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

@@ -1,4 +1,4 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/app-setup/users.md`. Do not edit manually. -->
+<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/guide/human/app-setup/users.md`. Do not edit manually. -->
 
 # Users
 

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

@@ -1,4 +1,4 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/app-setup/working-with-the-jskit-cli.md`. Do not edit manually. -->
+<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/guide/human/app-setup/working-with-the-jskit-cli.md`. Do not edit manually. -->
 
 # Working with the JSKIT CLI
 
@@ -45,6 +45,56 @@ That lock file is the source of truth for installed JSKIT-managed package state.
 
 That is why commands such as `update`, `remove`, `position`, `migrations`, and `doctor` all care about `.jskit/lock.json`.
 
+## JSKIT-managed app maintenance scripts
+
+The scaffolded app also has a small set of `npm run` shortcuts that are really wrappers around JSKIT-owned maintenance behavior.
+
+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:
+
+```json
+{
+  "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"
+  }
+}
+```
+
+That is a deliberate design choice.
+
+The app keeps the handy `npm run` names, but the real maintenance policy now 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.
+
+This gives you a clean ownership split:
+
+- app-owned scripts still describe how *this app* runs, builds, and tests
+- 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`, that is now shorthand for "run the app's JSKIT baseline verification policy, then any app-specific extra verification hook".
+
+If your app uses a non-default npm registry for JSKIT packages, pass it to the maintained CLI command rather than hard-coding it in the scaffold. For example:
+
+```bash
+npm run jskit:update -- --registry https://registry.example.com
+npm run release -- --registry https://registry.example.com
+```
+
+For older apps that still carry copied maintenance scripts, the migration path is:
+
+```bash
+npx jskit app adopt-managed-scripts
+```
+
+That command rewrites known old scaffold values to the thin wrapper form above.
+
 ## Discover first, change second
 
 One of the best habits in JSKIT is to inspect the catalog before mutating the app.
@@ -59,6 +109,7 @@ npx jskit help
 
 That shows the available commands such as:
 
+- `app`
 - `list`
 - `show`
 - `add`
@@ -72,6 +123,7 @@ That shows the available commands such as:
 Every command in the CLI also has its own help page. For example:
 
 ```bash
+npx jskit help app
 npx jskit help add
 npx jskit help migrations
 ```
@@ -642,7 +694,7 @@ That is a different job from:
 
 Those commands can all pass while JSKIT-managed state is still inconsistent. `doctor` is the command that checks that JSKIT's own view of the app still makes sense.
 
-That is exactly why the starter scaffold already includes `npx jskit doctor` in `npm run verify`.
+That is exactly why the starter scaffold now routes `npm run verify` through `jskit app verify`.
 
 It belongs there because JSKIT apps are not only source trees. They also have:
 

package/guide/agent/generators/advanced-cruds.md

@@ -1,4 +1,4 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/generators/advanced-cruds.md`. Do not edit manually. -->
+<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/guide/human/generators/advanced-cruds.md`. Do not edit manually. -->
 
 # Advanced CRUDs
 

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

@@ -1,4 +1,4 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/generators/crud-generators.md`. Do not edit manually. -->
+<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/guide/human/generators/crud-generators.md`. Do not edit manually. -->
 
 # CRUD Generators
 

package/guide/agent/generators/intro.md

@@ -1,4 +1,4 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/generators/intro.md`. Do not edit manually. -->
+<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/guide/human/generators/intro.md`. Do not edit manually. -->
 
 # Generators
 

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

@@ -1,4 +1,4 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/generators/ui-generators.md`. Do not edit manually. -->
+<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/guide/human/generators/ui-generators.md`. Do not edit manually. -->
 
 # UI Generators
 

package/guide/agent/index.md

@@ -1,4 +1,4 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/index.md`. Do not edit manually. -->
+<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/guide/human/index.md`. Do not edit manually. -->
 
 # Guide
 

package/guide/human/app-extras/assistant.md

@@ -1,5 +1,3 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/app-extras/assistant.md`. Do not edit manually. -->
-
 # Assistant
 
 At the end of the previous chapter, the app could already host live transports, but it still had no assistant surface of its own.

package/guide/human/app-extras/realtime.md

@@ -1,5 +1,3 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/app-extras/realtime.md`. Do not edit manually. -->
-
 # Realtime
 
 At the end of the previous chapter, the app already had a real shell, authenticated users, operator tooling, and workspace-aware routing. What it still did not have was a live transport for pushing updates into that shell.

package/guide/human/app-setup/a-more-interesting-shell.md

@@ -1,5 +1,3 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/app-setup/a-more-interesting-shell.md`. Do not edit manually. -->
-
 # A more interesting shell
 
 In the first chapter, the app was intentionally plain. That was useful because it let us see the smallest possible JSKIT scaffold without too many moving parts. In this chapter, we install `shell-web`, which is the package that turns that bare starting point into a real shell: a layout, navigation outlets, a first settings area, and a proper app-level error host.

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

@@ -1,5 +1,3 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/app-setup/authentication.md`. Do not edit manually. -->
-
 # Authentication
 
 At the end of the previous chapter, the app had a real shell, but it still did not know how to sign users in. In this chapter, we connect the app to Supabase Auth, add the stock JSKIT login and sign-out routes, and inspect the files that make authentication visible in the shell.

package/guide/human/app-setup/console.md

@@ -1,5 +1,3 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/app-setup/console.md`. Do not edit manually. -->
-
 # Console
 
 This chapter adds a separate `console` surface and looks at how JSKIT keeps that operator slice separate from the normal account/user layer.

package/guide/human/app-setup/database-layer.md

@@ -1,5 +1,3 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/app-setup/database-layer.md`. Do not edit manually. -->
-
 # Database layer
 
 At the end of the previous chapter, the app could already authenticate real users through Supabase, but JSKIT was still using its no-database fallback for the app-side user mirror. In this chapter, we install the MySQL database runtime, add the migration tooling, and explain what that changes immediately and what it still does **not** change yet.

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

@@ -1,5 +1,3 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/app-setup/initial-scaffolding.md`. Do not edit manually. -->
-
 # Initial scaffolding
 
 In this first chapter, we are going to create the smallest useful JSKIT app, install its dependencies, run it locally, and read the scaffold it gives us. The goal of this chapter is to explain how to get started with JSKIT and to understand what the generator produced, which files matter, and why the project already has concepts like _surfaces_, a local runtime package, and a server even before we add any real features.
@@ -14,6 +12,16 @@ npm install
 
 The first command creates a new folder called `exampleapp` and fills it with JSKIT's base shell template. The `exampleapp` name is used in a few template replacements, such as the package name and the browser title. The `--tenancy-mode none` flag tells JSKIT to start with the smallest routing model. In this mode, the app is not workspace-aware (more of this later in the guide, when multihoming is introduced). That keeps the first scaffold easier to read because there is no workspace slug handling yet.
 
+If you are working with an AI agent and want the agent to explain the platform options after the scaffold exists, there is also a safe guided path:
+
+```bash
+npx @jskit-ai/create-app exampleapp
+cd exampleapp
+npm install
+```
+
+That produces the same minimal scaffold shape, but without writing an explicit `config.tenancyMode` line yet. The important rule is that this does **not** mean tenancy is already decided. Before installing tenancy-sensitive packages such as `workspaces-core` or `workspaces-web`, the agent still needs to finish the Stage 1 platform conversation and then write the chosen tenancy into `config/public.js`. If workspace packages are installed while the app is still effectively on `none`, you fall into the recovery path described later in the multi-homing chapter.
+
 After creating the scaffolding (which comes with a package.json file), you will need to run `npm install` to install dependencies.
 
 <DocsTerminalTip title="Try Bash Completion!">
@@ -120,6 +128,7 @@ 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",
@@ -128,7 +137,9 @@ The most important parts look like this:
     "build:home": "VITE_SURFACE=home vite build",
     "test": "node --test",
     "test:client": "vitest run tests/client",
-    "verify": "npm run lint && npm run test && npm run test:client && npm run build && npx jskit doctor"
+    "verify": "jskit app verify && npm run --if-present verify:app",
+    "release": "jskit app release",
+    "jskit:update": "jskit app update-packages"
   },
   "dependencies": {
     "@local/main": "file:packages/main",
@@ -147,9 +158,13 @@ The most important parts look like this:
 }
 ```
 
-There are two details worth noticing immediately. The dependency on `@local/main` points at `file:packages/main`, which means your app already contains its own local JSKIT package. The `verify` script is also useful to notice early, because it shows the default quality gate the scaffold expects you to run later.
+There are two details worth noticing immediately. 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 now 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.
 
-The last command in that script, `npx jskit doctor`, is worth noticing specifically. Linting, tests, and builds check your source code and runtime behavior. `doctor` 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.
+`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.
 
 The surface-specific script names are also worth noticing early, even in this tiny app. `dev:home`, `server:home`, and `build:home` are the first concrete places where surface selection shows up in the scaffold. They work by setting `VITE_SURFACE=home` on the client side and `SERVER_SURFACE=home` on the server side. In this first chapter, where `home` is the only surface, those variants behave almost the same as the default commands. Later, once more surfaces exist, those scripts become the simplest way to run or build just one surface at a time.
 
@@ -721,7 +736,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 collects helper scripts for release, updating JSKIT packages, and linking a local JSKIT checkout during framework development.
+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 now much smaller than it used to be, because JSKIT maintenance helpers such as `verify`, `jskit:update`, `devlinks`, 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. `--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/human/app-setup/multi-homing.md

@@ -1,5 +1,3 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/app-setup/multi-homing.md`. Do not edit manually. -->
-
 # Multi-homing
 
 Up to this point, the app has had several surfaces, but none of them were workspace-dependent. `home`, `auth`, `account`, and `console` all live outside any workspace slug.

package/guide/human/app-setup/users.md

@@ -1,5 +1,3 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/app-setup/users.md`. Do not edit manually. -->
-
 # Users
 
 At the end of the previous chapter, the app had a real database runtime, but it still did not have JSKIT's own persistent users layer. Authentication worked, but the app-side profile mirror was still only the temporary fallback from the auth chapter.

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

@@ -1,5 +1,3 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/app-setup/working-with-the-jskit-cli.md`. Do not edit manually. -->
-
 # Working with the JSKIT CLI
 
 In the first chapter, we used the JSKIT CLI, but only in passing. We created the app, installed dependencies, and moved on.
@@ -59,6 +57,56 @@ That lock file is the source of truth for installed JSKIT-managed package state.
 
 That is why commands such as `update`, `remove`, `position`, `migrations`, and `doctor` all care about `.jskit/lock.json`.
 
+## JSKIT-managed app maintenance scripts
+
+The scaffolded app also has a small set of `npm run` shortcuts that are really wrappers around JSKIT-owned maintenance behavior.
+
+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:
+
+```json
+{
+  "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"
+  }
+}
+```
+
+That is a deliberate design choice.
+
+The app keeps the handy `npm run` names, but the real maintenance policy now 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.
+
+This gives you a clean ownership split:
+
+- app-owned scripts still describe how *this app* runs, builds, and tests
+- 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`, that is now shorthand for "run the app's JSKIT baseline verification policy, then any app-specific extra verification hook".
+
+If your app uses a non-default npm registry for JSKIT packages, pass it to the maintained CLI command rather than hard-coding it in the scaffold. For example:
+
+```bash
+npm run jskit:update -- --registry https://registry.example.com
+npm run release -- --registry https://registry.example.com
+```
+
+For older apps that still carry copied maintenance scripts, the migration path is:
+
+```bash
+npx jskit app adopt-managed-scripts
+```
+
+That command rewrites known old scaffold values to the thin wrapper form above.
+
 ## Discover first, change second
 
 One of the best habits in JSKIT is to inspect the catalog before mutating the app.
@@ -73,6 +121,7 @@ npx jskit help
 
 That shows the available commands such as:
 
+- `app`
 - `list`
 - `show`
 - `add`
@@ -86,6 +135,7 @@ That shows the available commands such as:
 Every command in the CLI also has its own help page. For example:
 
 ```bash
+npx jskit help app
 npx jskit help add
 npx jskit help migrations
 ```
@@ -656,7 +706,7 @@ That is a different job from:
 
 Those commands can all pass while JSKIT-managed state is still inconsistent. `doctor` is the command that checks that JSKIT's own view of the app still makes sense.
 
-That is exactly why the starter scaffold already includes `npx jskit doctor` in `npm run verify`.
+That is exactly why the starter scaffold now routes `npm run verify` through `jskit app verify`.
 
 It belongs there because JSKIT apps are not only source trees. They also have:
 

package/guide/human/generators/advanced-cruds.md

@@ -1,5 +1,3 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/generators/advanced-cruds.md`. Do not edit manually. -->
-
 # Advanced CRUDs
 
 The earlier CRUD chapter shows the workflow. This chapter shows the anatomy.

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

@@ -1,5 +1,3 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/generators/crud-generators.md`. Do not edit manually. -->
-
 # CRUD Generators
 
 CRUD generation in JSKIT is really one workflow split across two generator packages:

package/guide/human/generators/intro.md

@@ -1,5 +1,3 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/generators/intro.md`. Do not edit manually. -->
-
 # Generators
 
 By the end of the app-setup chapters, the guide app already has the main structural pieces in place:

package/guide/human/generators/ui-generators.md

@@ -1,5 +1,3 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/generators/ui-generators.md`. Do not edit manually. -->
-
 # UI Generators
 
 The earlier chapters already used `ui-generator` a little when we added:

package/guide/human/index.md

@@ -1,5 +1,3 @@
-<!-- Generated by `npm run agent-docs:build` from `docs/guide/index.md`. Do not edit manually. -->
-
 # Guide
 
 This guide is the main hands-on path through JSKIT.

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Distributed JSKIT agent workflows, guides, and generated reference maps.",
   "type": "module",
   "files": [
     "DISTR_AGENT.md",
     "guide",
     "reference",
+    "skills",
     "templates",
     "workflow"
   ],

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

@@ -41,6 +41,8 @@ Exports
 - `upsertEnvValue(content, key, value)`
 - `removeEnvValue(content, key, expectedValue, previous)`
 - `writeJsonFile`
+Local functions
+- `directoryLooksLikeJskitAppRoot(directoryPath)`
 
 ### `src/server/cliRuntime/capabilitySupport.js`
 Exports
@@ -341,6 +343,65 @@ Exports
 - `applyViteMutations(packageEntry, appRoot, viteMutations, options, managedVite, touchedFiles)`
 - `removeManagedViteProxyEntries({ appRoot, packageId, managedViteChanges = {}, touchedFiles = null } = {})`
 
+### `src/server/commandHandlers/app.js`
+Exports
+- `createAppCommands(ctx = {})`
+Local functions
+- `renderAppHelp(stream, definition = null)`
+
+### `src/server/commandHandlers/appCommandCatalog.js`
+Exports
+- `APP_SCRIPT_WRAPPERS`
+- `LEGACY_APP_SCRIPT_VALUES`
+- `LEGACY_APP_SCRIPT_FILES`
+- `APP_COMMAND_DEFINITIONS`
+- `listAppCommandDefinitions()`
+- `resolveAppCommandDefinition(rawName = "")`
+- `buildAppCommandOptionMeta(subcommandName = "")`
+
+### `src/server/commandHandlers/appCommands/adoptManagedScripts.js`
+Exports
+- `runAppAdoptManagedScriptsCommand(ctx = {}, { appRoot = "", options = {}, stdout })`
+Local functions
+- `shouldRewriteScript(currentValue = "", scriptName = "", force = false)`
+
+### `src/server/commandHandlers/appCommands/linkLocalPackages.js`
+Exports
+- `runAppLinkLocalPackagesCommand(ctx = {}, { appRoot = "", options = {}, stdout })`
+
+### `src/server/commandHandlers/appCommands/release.js`
+Exports
+- `runAppReleaseCommand(ctx = {}, { appRoot = "", options = {}, stdout, stderr })`
+
+### `src/server/commandHandlers/appCommands/shared.js`
+Exports
+- `fileExists(filePath = "")`
+- `normalizeText(value = "")`
+- `isTruthyFlag(rawValue = "")`
+- `runExternalCommand(command, args = [], { cwd = "", env = {}, stdout, stderr, quiet = false, createCliError } = {})`
+- `formatUtcReleaseTimestamp(date = new Date())`
+- `resolveLocalJskitBin(appRoot = "")`
+- `runLocalJskit(appRoot, args = [], { stdout, stderr, createCliError, quiet = false } = {})`
+- `resolveLocalRepoRoot({ appRoot = "", explicitRepoRoot = "" } = {})`
+- `discoverLocalPackageMap(repoRoot = "")`
+- `linkPackageBinEntries({ appRoot, packageDirName, sourceDir, stdout } = {})`
+- `resolveSymlinkType()`
+Local functions
+- `ensureCommandSucceeded(result, label, { createCliError, cwd = "", stdout, stderr, quiet = false } = {})`
+
+### `src/server/commandHandlers/appCommands/updatePackages.js`
+Exports
+- `runAppUpdatePackagesCommand(ctx = {}, { appRoot = "", options = {}, stdout, stderr })`
+Local functions
+- `collectJskitPackageNames(packageMap = {})`
+- `resolveMajorRangeFromVersion(packageName = "", rawVersion = "", createCliError)`
+- `resolveRegistryArgs(registryUrl = "")`
+- `resolveInstallSpecs(packageNames = [], resolveMajorRange)`
+
+### `src/server/commandHandlers/appCommands/verify.js`
+Exports
+- `runAppVerifyCommand(ctx = {}, { appRoot = "", options = {}, stdout, stderr })`
+
 ### `src/server/commandHandlers/completion.js`
 Exports
 - `createCompletionCommands(ctx = {})`

package/skills/jskit-review/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: jskit-review
+description: Review or deslop a JSKIT chunk or whole changeset. Use when the user asks to review, deslop, run a JSKIT best-practices audit, or verify a JSKIT feature, chunk, or whole changeset before sign-off.
+---
+
+# JSKIT Review
+
+Use this skill for independent review passes on JSKIT app work.
+
+Preferred execution mode:
+
+- Run this skill in a fresh review agent when the runtime supports delegation.
+- Use the current agent only when delegation is unavailable.
+- The same rule applies to chunk review and whole-changeset review.
+
+## Read first
+
+1. `../../workflow/review.md`
+2. `../../workflow/feature-delivery.md`
+
+Read these on demand:
+
+- `../../reference/autogen/KERNEL_MAP.md`
+- `../../reference/autogen/README.md`
+- `../../guide/agent/index.md`
+- `../../guide/human/index.md` when compressed guidance is ambiguous
+
+Inspect app-local files when they exist:
+
+- `.jskit/WORKBOARD.md`
+- `.jskit/APP_BLUEPRINT.md`
+
+## Review target
+
+Determine whether the target is:
+
+- the current chunk
+- or the whole changeset
+
+Use `.jskit/WORKBOARD.md` to determine the active chunk when available.
+
+## Required passes
+
+1. Deslop review
+2. JSKIT best-practices review
+3. Verification review
+
+## Deslop review
+
+Check for:
+
+- repeated functions or duplicated local helpers
+- local helpers that should reuse kernel/runtime seams
+- placeholder, fake-complete, or vague UI/copy/code
+- dead code, unused imports/props, TODO-shaped gaps, or accidental abstractions
+- missing loading, empty, error, permission, or ownership states
+- broken route wiring, missing migrations, or incomplete flows
+
+## JSKIT review
+
+Check for:
+
+- missed reuse of existing JSKIT helpers or runtime seams
+- hand code that should have been a package, generator, or scaffold step
+- surface, route, ownership, and migration choices that violate JSKIT conventions
+- metadata that no longer matches actual behavior
+
+## Verification review
+
+Check that verification is appropriate for the target:
+
+- focused verification for a chunk
+- broad regression for a whole changeset
+- Playwright for meaningful user-facing flows
+- explicit handling of login/test-auth strategy when auth is required
+
+## Output format
+
+- Present findings first, ordered by severity, with file references.
+- If there are no findings, say so explicitly.
+- Always finish with:
+  - files reviewed
+  - commands run
+  - anything still unverified

package/skills/jskit-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "JSKIT Review"
+  short_description: "Deslop, audit JSKIT fit, and verify a chunk or changeset"
+  default_prompt: "Use $jskit-review to run a deslop pass, JSKIT best-practices audit, and verification review on the current JSKIT chunk or whole changeset."

package/templates/APP_BLUEPRINT.md

@@ -51,7 +51,21 @@
 - Non-CRUD pages to scaffold:
 - Custom code areas:
 
+## Delivery Plan
+
+| Chunk | Goal | Type | Depends on | Done when |
+| --- | --- | --- | --- | --- |
+| | | | | |
+
+Chunk notes:
+
+- One CRUD is usually one chunk.
+- Platform/auth/shell work may be its own chunk.
+- Each chunk must be independently reviewable and testable.
+
 ## Verification
 
 - Commands to run:
+- Playwright coverage plan:
+- Test auth strategy:
 - Known open questions:

package/templates/WORKBOARD.md

@@ -0,0 +1,46 @@
+# Workboard
+
+## Request
+
+- Request summary:
+- Current stage:
+- Current status:
+
+## Scope Snapshot
+
+- Platform decisions:
+- Current blueprint path:
+- Current workboard owner:
+
+## Chunk Tracker
+
+| Chunk | Goal | Status | Deslop | JSKIT Review | Verification | Notes |
+| --- | --- | --- | --- | --- | --- | --- |
+| | | | | | | |
+
+Status guide:
+
+- `planned`
+- `active`
+- `implemented`
+- `reviewed`
+- `verified`
+- `done`
+- `blocked`
+
+## Current Focus
+
+- Active chunk:
+- Next action:
+- Blockers:
+
+## Verification Log
+
+- Commands run:
+- Playwright status:
+- Remaining unverified:
+
+## Notes
+
+- Decisions made:
+- Open questions:

package/templates/app/AGENTS.md

@@ -0,0 +1,46 @@
+# App Agent Instructions
+
+Use this file as the app-facing instruction entrypoint.
+
+Read these workflow files in order:
+
+1. `node_modules/@jskit-ai/agent-docs/workflow/app-state.md`
+2. `node_modules/@jskit-ai/agent-docs/workflow/bootstrap.md` if the workspace is empty or no JSKIT app exists yet
+3. `node_modules/@jskit-ai/agent-docs/workflow/scoping.md`
+4. `node_modules/@jskit-ai/agent-docs/workflow/workboard.md`
+5. `node_modules/@jskit-ai/agent-docs/workflow/feature-delivery.md`
+6. `node_modules/@jskit-ai/agent-docs/workflow/review.md`
+
+Use these references on demand:
+
+- `node_modules/@jskit-ai/agent-docs/reference/autogen/KERNEL_MAP.md`
+- `node_modules/@jskit-ai/agent-docs/reference/autogen/README.md`
+- `node_modules/@jskit-ai/agent-docs/guide/agent/index.md`
+- `node_modules/@jskit-ai/agent-docs/guide/human/index.md` when compressed guidance is ambiguous or missing nuance
+- `node_modules/@jskit-ai/agent-docs/templates/APP_BLUEPRINT.md`
+- `node_modules/@jskit-ai/agent-docs/templates/WORKBOARD.md`
+- `node_modules/@jskit-ai/agent-docs/skills/jskit-review/SKILL.md` for review passes when your Codex environment supports packaged skills
+
+Core rules:
+
+- Inspect the workspace before assuming a JSKIT app exists.
+- Reuse existing JSKIT helpers and runtime seams before adding new local helpers.
+- A freshly scaffolded JSKIT app can still be in Stage 1. If the app was just created and platform decisions are not settled yet, continue with the initialize workflow before adding runtime packages.
+- Do not treat a missing `config.tenancyMode` line or an untouched minimal scaffold as a final tenancy decision.
+- Do not install tenancy-sensitive packages until Stage 1 decisions are complete and the chosen tenancy is written into `config/public.js`.
+- Do not implement app features before the blueprint has the database, surfaces, ownership model, and route/screen plan written down.
+- For substantial or multi-chunk work, create or update `.jskit/WORKBOARD.md` as the per-request execution tracker.
+- Break planned work into reviewable chunks before implementing. One CRUD is usually one chunk, but auth/platform setup, shell work, and cross-cutting integrations can be their own chunks.
+- Do not move to the next chunk until the current chunk has passed implementation, deslop review, JSKIT best-practices review, and verification.
+- If a feature spans more than one chunk, run a final whole-changeset deslop pass, JSKIT pass, and verification pass after the last chunk.
+- Prefer a fresh review agent for chunk and whole-changeset review when the runtime supports delegation.
+- Have that fresh review agent use the packaged `jskit-review` skill when it is available to the runtime.
+- If delegation or skills are unavailable, follow `workflow/review.md` manually in the current agent.
+- Use the compressed guide first for speed; fall back to the human guide when a workflow trap, migration caveat, or architectural boundary needs exact wording.
+- Treat generated reference maps and guide copies as vendor reference. Do not edit them manually.
+
+If dependencies are not installed yet:
+
+- install dependencies so `node_modules/@jskit-ai/agent-docs/` exists
+- inspect the workspace before assuming a JSKIT app already exists
+- if the workspace is empty and the user wants a new app, start with the initialize workflow at a high level first

package/workflow/app-state.md

@@ -28,6 +28,7 @@ State handling:
   - Explain which scaffold markers are missing.
   - Recover or finish the scaffold instead of re-initializing from scratch.
 - `jskit_app`
-  - Continue with scoping or feature delivery.
+  - If this is a fresh minimal scaffold and Stage 1 platform decisions are not settled yet, continue with the initialize workflow first.
+  - Otherwise continue with scoping or feature delivery.
 
 This state gate is intentionally strict. The agent must inspect first and only then choose initialize, recover, or extend.

package/workflow/bootstrap.md

@@ -1,6 +1,26 @@
 # Initialize Workflow
 
-Use this only when the app state gate resolves to `empty`, or when the user explicitly wants a brand-new JSKIT app in a new directory.
+Use this when:
+
+- the app state gate resolves to `empty`
+- the user explicitly wants a brand-new JSKIT app in a new directory
+- or a fresh minimal JSKIT scaffold exists but Stage 1 platform decisions are not settled yet
+
+Safe bootstrap paths:
+
+1. Empty directory path
+   - Ask the Stage 1 platform questions first.
+   - Once the high-level shape is clear, run `create-app` with the chosen tenancy mode.
+2. Fresh scaffold path
+   - If the app was just created with `npx @jskit-ai/create-app <app-name>` and `npm install`, treat that scaffold as provisional.
+   - Ask the Stage 1 platform questions before adding tenancy-sensitive packages.
+   - If the chosen tenancy is `personal` or `workspaces`, write it into `config/public.js` before installing workspace packages.
+
+Important constraint:
+
+- Do not install tenancy-sensitive packages while tenancy is still provisional.
+- In practice, that means `workspaces-core` and `workspaces-web` must wait until the Stage 1 tenancy decision is complete.
+- A missing `config.tenancyMode` line behaves like `none` at runtime. Treat it as provisional only if no tenancy-sensitive package install has happened yet.
 
 Version 0 sketch:
 

package/workflow/feature-delivery.md

@@ -1,17 +1,29 @@
 # Feature Delivery Workflow
 
-For each feature, follow this order:
+Before implementation, break the planned work into chunks.
 
-1. Scope the feature inside the blueprint.
-2. Decide whether it is:
+Chunk rules:
+
+- One CRUD is usually one chunk.
+- Platform setup, shell/navigation, and cross-cutting integrations may be separate chunks.
+- A chunk must be independently reviewable and testable.
+- If a chunk is too broad to review confidently, split it before coding.
+
+For each chunk, follow this order:
+
+1. Scope the chunk inside the blueprint.
+2. Mark the chunk as active in `.jskit/WORKBOARD.md`.
+3. Decide whether it is:
    - package install
    - generator scaffolding
    - custom local code
    - or a combination
-3. Implement the smallest correct change.
-4. Review for implementation gaps.
-5. Review against JSKIT reuse and best practices.
-6. Verify with the relevant commands.
+4. Implement the smallest correct change.
+5. Deslop the chunk.
+6. Review the chunk against JSKIT reuse and best practices.
+7. Verify the chunk with the relevant commands, including Playwright for meaningful UI flows.
+8. Update `.jskit/WORKBOARD.md` with status, commands run, and anything still unverified.
+9. Only then move to the next chunk.
 
 During implementation:
 
@@ -19,3 +31,17 @@ During implementation:
 - Use generated CRUD/UI scaffolds only after the route and ownership model are decided.
 - Keep runtime, UI, and data concerns separated.
 - Avoid “while I’m here” scope creep unless it is required for correctness.
+
+After the last chunk:
+
+- If there was only one chunk, the chunk review is the final review.
+- If there was more than one chunk, run one more whole-changeset pass:
+  - deslop the whole changeset
+  - review the whole changeset against JSKIT best practices
+  - run the widest relevant verification, including Playwright
+  - update `.jskit/WORKBOARD.md` with the final result and any remaining gaps
+
+Playwright note:
+
+- When login is required, prefer a test-only impersonation or session bootstrap path over dependence on a live external auth provider.
+- If such a path does not exist yet, treat that as a testability gap and decide whether the chunk must add it before the feature is considered complete.

package/workflow/review.md

@@ -1,18 +1,32 @@
 # Review Workflow
 
-Before calling a feature done, review it in three passes:
+Preferred review mode:
 
-1. Implementation gap review
-   - missing states
-   - broken flows
-   - incomplete ownership handling
-   - missing migrations or route wiring
+- Prefer a fresh review agent for chunk and whole-changeset review when the runtime supports delegation.
+- Have that fresh review agent use the packaged `jskit-review` skill when it is available.
+- If delegation or skills are unavailable, follow this file manually in the current agent.
+
+Before calling a chunk or a whole changeset done, review it in three passes:
+
+1. Deslop review
+   - repeated functions or duplicated local helpers
+   - helpers reimplemented locally when a kernel/runtime seam already exists
+   - placeholder, fake-complete, or vague UI/copy/code structure
+   - dead code, unused props/imports, TODO-shaped gaps, or accidental abstractions
+   - missing loading, empty, error, permission, or ownership states
+   - broken flows, missing route wiring, or missing migrations
+   - surface or entity ownership mistakes: `public`, `user`, `workspace`, `workspace_user`
 2. JSKIT review
    - existing helper/runtime seam available?
    - duplicate local code that should reuse kernel/runtime support?
+   - should this have been a package install, generator step, or scaffold extension instead of hand code?
+   - are surface, route, ownership, and migration choices aligned with JSKIT conventions?
    - package metadata and actual behavior still aligned?
 3. Verification review
-   - run the smallest relevant verification commands
+   - run the smallest relevant verification commands for a chunk
+   - run the widest relevant verification commands for a whole changeset
+   - include Playwright for meaningful user-facing flows
+   - if login is required, verify the chosen test-auth path or explicitly record that the lack of one is an open gap
    - note anything left unverified
 
 Minimum expectation:
@@ -20,3 +34,8 @@ Minimum expectation:
 - list the files changed
 - list the commands run
 - list anything still unverified
+- update `.jskit/WORKBOARD.md` with the review outcome
+
+Whole-changeset rule:
+
+- If the work was split into more than one chunk, repeat all three passes over the whole changeset after the final chunk is complete.

package/workflow/scoping.md

@@ -1,6 +1,13 @@
 # Scoping Workflow
 
-Before implementing any feature or batch of features, write or update `templates/APP_BLUEPRINT.md` as the working app blueprint.
+Before implementing any feature or batch of features, create or update an app-local working blueprint using `templates/APP_BLUEPRINT.md` as the template.
+
+Recommended location:
+
+- `.jskit/APP_BLUEPRINT.md`
+- `.jskit/WORKBOARD.md` for per-request progress tracking
+
+Do not edit the vendor template in `node_modules/` directly.
 
 The blueprint must capture at least:
 
@@ -15,12 +22,17 @@ The blueprint must capture at least:
 - package install plan
 - generator plan
 - custom-code areas
+- delivery plan broken into chunks
 
 Scoping rules:
 
 - Use `guide/agent/index.md` for fast navigation and `guide/human/index.md` for exact details.
 - Inspect packages and generators before choosing them.
 - Decide ownership early; do not treat it as a UI-only detail.
+- If Stage 1 platform choices are still provisional, finish them before installing tenancy-sensitive runtime packages.
+- Create or refresh `.jskit/WORKBOARD.md` for substantial or multi-chunk work so the request has an explicit execution tracker.
+- Break delivery into chunks that can be independently reviewed and tested.
+- One CRUD is usually one chunk. Platform setup, shell work, and cross-cutting integrations may also be separate chunks.
 - If the package/runtime choice is unclear, stop and resolve it before writing implementation code.
 
-No feature implementation should start until the blueprint covers database, screens, and functional boundaries well enough that the implementation path is obvious.
+No feature implementation should start until the blueprint covers database, screens, functional boundaries, and chunk plan well enough that the implementation path is obvious.

package/workflow/workboard.md

@@ -0,0 +1,29 @@
+# Workboard Workflow
+
+Use a workboard for any substantial request, especially:
+
+- new app builds
+- multi-chunk feature work
+- requests that need scoping before coding
+- requests where verification spans several steps
+
+Recommended location:
+
+- `.jskit/WORKBOARD.md`
+
+Use `templates/WORKBOARD.md` as the starting template.
+
+Purpose:
+
+- track the current request
+- record the current stage and current chunk
+- track chunk status across implementation, deslop, JSKIT review, and verification
+- record blockers, open questions, and remaining gaps
+
+Workboard rules:
+
+- The workboard is the execution tracker for the current request.
+- The blueprint remains the durable product and architecture record.
+- Keep the workboard concise and current.
+- Update it when stage, chunk, blockers, or verification state changes.
+- When the request finishes, either reset it for the next request or leave a short final state that makes completion obvious.