@jskit-ai/agent-docs 0.1.2 → 0.1.4

package/DISTR_AGENT.md

@@ -5,21 +5,38 @@ 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:
 
 - `reference/autogen/KERNEL_MAP.md`
 - `reference/autogen/README.md`
 - `guide/agent/index.md`
-- `guide/human/index.md` when compressed guidance is ambiguous or missing nuance
+- `site/guide/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.
+- Before non-trivial edits, print a short visible checkpoint using this format:
+  - `Problem: ...`
+  - `Fix: ...`
+  - `Why this sticks: ...`
+  - `Not doing: ...`
+- Keep that checkpoint compact. Do not expand it into a long preamble unless the developer asks for detail.
 - 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`.
+- Treat standard JSKIT package-owned workflows as the default baseline once the relevant package stack is chosen. Do not ask the developer to redesign those flows unless they want overrides, restrictions, or custom additions.
+- Example: if the app is workspace-capable and uses `workspaces-core` plus `workspaces-web`, assume the standard workspace invite flow is part of the baseline package behavior.
+- For baseline package setup, ask plainly for the exact local development values needed for the next install step, but only for the modules or packages that are actually selected.
+- Use the real env var names or option names instead of vague requests for "credentials". Values such as `DB_NAME`, `DB_USER`, `DB_PASSWORD`, `AUTH_SUPABASE_URL`, `AUTH_SUPABASE_PUBLISHABLE_KEY`, and `APP_PUBLIC_URL` are routine setup inputs when the relevant package stack needs them.
 - 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/site/guide/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/site/guide/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/site/guide/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/site/guide/app-setup/authentication.md`. Do not edit manually. -->
 
 # Authentication
 
@@ -44,6 +44,14 @@ JSKIT uses the project URL as `AUTH_SUPABASE_URL`, the publishable key as `AUTH_
 
 Use the **publishable** key here, not the secret key and not a service-role key. If you later run the app on a different host or port, update both Supabase's URL settings and `APP_PUBLIC_URL` to match the real browser URL exactly.
 
+If you are guiding someone interactively, ask plainly for these exact values:
+
+- `AUTH_SUPABASE_URL`
+- `AUTH_SUPABASE_PUBLISHABLE_KEY`
+- whether `APP_PUBLIC_URL` should stay `http://localhost:5173`
+
+Do not hide behind vague language like "send the auth credentials later." In this local guide flow, those are routine setup values for the Supabase auth install step.
+
 ## Installing the auth layer
 
 From inside `exampleapp`, run:

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/site/guide/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/site/guide/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/site/guide/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/site/guide/app-setup/multi-homing.md`. Do not edit manually. -->
 
 # Multi-homing
 
@@ -33,6 +33,8 @@ This chapter teaches `personal`, not `workspaces`.
 
 That is deliberate. `personal` gives the guide a much better first-run experience because the first workspace is auto-provisioned for the user. The app still becomes multi-homing-capable, because invitations and memberships can still put one user in several workspaces at once. The `personal` part only changes how the first workspace is provisioned and how its slug policy works.
 
+Once `workspaces-core` and `workspaces-web` are installed, the baseline workspace invitation flow is already part of the package stack. Treat that as the default behavior unless the app explicitly needs custom invite rules or custom UI beyond what the packages already provide.
+
 ## Installing the workspace packages
 
 If your app is already on `tenancyMode = "personal"`, run:

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/site/guide/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/site/guide/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/site/guide/generators/advanced-cruds.md`. Do not edit manually. -->
 
 # Advanced CRUDs
 
@@ -451,6 +451,168 @@ They usually:
 
 These files are mostly containers. That is deliberate.
 
+### CRUD link resolution
+
+This deserves an explicit warning, because it was implemented incorrectly in a real app.
+
+When you customize generated CRUD pages, use the CRUD runtime that owns the current route scope to resolve CRUD-bound links.
+
+Use `paths.page()` for **surface-aware** navigation:
+
+- `/account`
+- `/assistant`
+- `/lists`
+- other links that only need normal surface params such as `workspaceSlug`
+
+Do **not** use `paths.page()` with CRUD record placeholders inside the relative path or URL template, such as:
+
+- `:contactId`
+- `:addressId`
+- `:todoListId`
+- `:todoItemId`
+
+For CRUD-bound links, use the runtime-provided resolvers instead:
+
+- list pages:
+  - `records.resolveViewUrl(record)`
+  - `records.resolveEditUrl(record)`
+  - `records.resolveParams(template, extraParams)`
+- view pages:
+  - `view.listUrl`
+  - `view.editUrl`
+  - `view.resolveParams(template, extraParams)`
+- add/edit pages:
+  - `formRuntime.addEdit.resolveParams(template, extraParams)`
+
+Why this matters:
+
+- `paths.page()` only knows about the current surface route params
+- CRUD runtimes also know about the current CRUD route shape, current record id, parent record ids, and nested child route context
+- once a page is CRUD-bound, those runtime resolvers are the safe way to build record-scoped links
+
+Scope rule:
+
+- use the runtime anchored to the record that owns the action
+- on a parent record view page with nested child routes, parent actions should still resolve from the parent `view` runtime even while a child route like `/items/new` is active
+- child-item actions should resolve from the child/item runtime only when the current route is actually child-scoped
+
+Examples:
+
+- good: `view.resolveParams("./items/new")`
+- good: `view.resolveParams("./items/:todoItemId/edit", { todoItemId: item.id })`
+- good: `formRuntime.addEdit.resolveParams("../../..")`
+- bad: `paths.page("/lists/:todoListId/items/new")`
+- bad: `paths.page("/lists/:todoListId/edit")`
+
+The safe mental model is:
+
+- use `paths.page()` to get to the right surface
+- use CRUD runtime resolvers to move around inside the CRUD
+
+### Live actions and `useCommand()`
+
+There is one more client-side pattern worth naming explicitly:
+
+Use `useCommand()` for live actions such as:
+
+- checkboxes that toggle a record field
+- archive / publish / reopen buttons
+- delete buttons
+- small one-click PATCH / POST / DELETE actions that are not full forms
+
+This is the pattern the `todo` app uses for "mark item done".
+
+The page renders a checkbox like this:
+
+```vue
+<v-checkbox-btn
+  :model-value="item.done"
+  :disabled="!canUpdateItem || isItemBusy(item.id)"
+  @update:model-value="toggleItem(item, $event)"
+/>
+```
+
+Then the page wires a command:
+
+```js
+const itemPatchModel = reactive({
+  id: "",
+  patch: {}
+});
+
+const updateItemCommand = useCommand({
+  model: itemPatchModel,
+  apiSuffix: ({ model }) => `/todo-items/${model?.id || ""}`,
+  writeMethod: "PATCH",
+  runPermissions: ["crud.todo_items.update"],
+  suppressSuccessMessage: true,
+  fallbackRunError: "Unable to update item.",
+  buildRawPayload(model) {
+    return model.patch;
+  },
+  async onRunSuccess(_payload, context = {}) {
+    if (context.queryClient) {
+      await context.queryClient.invalidateQueries({
+        queryKey: ["ui-generator", "todo_items"]
+      });
+    }
+  }
+});
+
+async function toggleItem(item = {}, nextValue = false) {
+  itemPatchModel.id = String(item.id || "");
+  itemPatchModel.patch = {
+    done: Boolean(nextValue)
+  };
+
+  await updateItemCommand.run();
+}
+```
+
+That gives you a clean action pipeline:
+
+1. the UI captures the click
+2. the page writes a tiny action model
+3. `useCommand()` resolves the correct scoped API path for the current route/surface
+4. it sends the request through the standard HTTP runtime
+5. on success, it invalidates the relevant query keys so the list/view refreshes
+
+So yes: for this class of interaction, `useCommand()` is the right helper.
+
+Use this rule of thumb:
+
+- `useCommand()`
+  - for live actions
+  - button clicks
+  - toggles
+  - small PATCH/POST/DELETE interactions
+- `useAddEdit()` / `useCrudAddEdit()`
+  - for real forms
+  - create/edit screens
+  - save/cancel flows
+- `useCrudList()` / `useCrudView()`
+  - for routed list/view loading and CRUD URL resolution
+
+Best practices for live CRUD actions:
+
+- keep the payload narrow
+  - send the field change you mean, not a whole copied record
+- disable the control while the command for that record is running
+  - `todo` does this with `isItemBusy(item.id)`
+- invalidate the relevant list/view query keys on success
+  - do not hand-maintain parallel local record copies unless you really need optimistic UI
+- suppress success toasts for high-frequency actions when they would become noisy
+  - a checkbox toggle usually does not need "Saved." every time
+- keep business rules on the server
+  - in `todo`, the client sends `{ done: true|false }`
+  - the server service decides how `completedAt` should be set or cleared
+
+The safe mental model is:
+
+- use form runtimes for forms
+- use command runtimes for actions
+- keep the server as the source of truth for derived state
+
 ### `_components/CrudAddEditForm.vue`
 
 This is the shared rendering shell for the add/edit form.

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/site/guide/generators/crud-generators.md`. Do not edit manually. -->
 
 # CRUD Generators
 
@@ -238,6 +238,7 @@ The exact fields will vary by app. What matters for the generator is:
 - the table already exists
 - the ownership columns match the ownership filter you are going to choose
 - the column names are stable enough to become part of your app's resource contract
+- if you are using `crud-server-generator`, do **not** hand-write a separate CRUD migration for this table; the server generator installs the CRUD migration scaffold itself
 
 In this table, `workspace_id` is the important ownership clue. That is why the next step uses:
 
@@ -261,6 +262,13 @@ npx jskit generate crud-server-generator scaffold \
 
 This creates an app-local package under `packages/contacts/`.
 
+Before generating anything, decide these with the developer:
+
+- which operations are allowed for this CRUD
+- which fields belong in the list view if a list exists
+- what the view form should look like
+- what the edit/new form should look like
+
 The most important file from the UI point of view is:
 
 ```text
@@ -505,6 +513,27 @@ The host page then renders the comment list directly, usually with lower-level C
 - `useCrudAddEdit()`
 - `useCrudView()` when needed
 
+There is one more runtime worth knowing about early:
+
+- `useCommand()`
+
+Use it for live actions that are **not** full forms, such as:
+
+- checkbox toggles
+- archive / reopen buttons
+- quick PATCH / POST / DELETE actions on one record
+
+So the practical split is:
+
+- `useCrudList()` / `useCrudView()`
+  - routed list/view loading
+- `useCrudAddEdit()`
+  - real create/edit forms
+- `useCommand()`
+  - live actions inside the page
+
+The `todo` app uses that last pattern for "mark item done" checkboxes. The deeper best-practices explanation is in [Advanced CRUDs](/guide/generators/advanced-cruds).
+
 That is the same general pattern already used in the real app for embedded child records like pet notes: the record list lives inside the main view page, while routed child pages handle the operations that still deserve their own URLs.
 
 This pattern is useful when the child records are supporting detail rather than a destination in their own right.

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/site/guide/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/site/guide/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/site/guide/index.md`. Do not edit manually. -->
 
 # Guide
 

package/package.json

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

package/reference/autogen/packages/agent-docs.md

@@ -11,3 +11,21 @@ Use this on demand; do not load the full index at startup.
 - Excludes: `test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `*.vitest.*`, `node_modules/`, `dist/`, `coverage/`, `docs/`, `LEGACY/`
 
 ## Sections
+
+### site
+
+### `site/.vitepress/config.mjs`
+Exports
+- None
+
+### `site/.vitepress/theme/components/DocsInDepth.vue`
+Exports
+- None
+
+### `site/.vitepress/theme/components/DocsTerminalTip.vue`
+Exports
+- None
+
+### `site/.vitepress/theme/index.js`
+Exports
+- `default`

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 = {})`