@jskit-ai/agent-docs 0.1.6 → 0.1.7

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

@@ -613,6 +613,57 @@ The safe mental model is:
 - use command runtimes for actions
 - keep the server as the source of truth for derived state
 
+### Choosing the right client request seam
+
+When you need client-side HTTP work in JSKIT, do not start with raw `fetch(...)`.
+
+Choose the highest-level runtime that matches the interaction:
+
+```js
+// 1. Button/toggle/small mutation
+const command = useCommand({ ... });
+
+// 2. List endpoint
+const list = useList({ ... });
+
+// 3. Single-record endpoint
+const view = useView({ ... });
+
+// 4. Form save flow
+const form = useAddEdit({ ... });
+
+// 5. Truly custom endpoint
+const resource = useEndpointResource({ ... });
+```
+
+Use the CRUD wrappers when they fit:
+
+- `useCrudList()` for routed CRUD lists
+- `useCrudView()` for routed CRUD record loading
+- `useCrudAddEdit()` for routed CRUD forms
+
+Why this is the standard JSKIT shape:
+
+- `useCommand()` resolves the correct scoped API path for the current route and surface.
+- The higher-level list, view, add/edit, and command runtimes send requests through the standard HTTP runtime instead of ad hoc request code.
+- The default client runtime uses `usersWebHttpClient`, which already handles credentials and CSRF token behavior.
+- `useEndpointResource()` gives the shared endpoint primitive for loading, saving, and standard load/save error handling. Higher-level runtimes like `useCommand()` and `useAddEdit()` layer UI feedback and field-error behavior on top of that primitive.
+
+If you need a custom scoped endpoint path outside the higher-level runtimes, prefer `usePaths().api(...)` rather than hand-building scoped URLs:
+
+```js
+const paths = usePaths();
+const reportsApiPath = computed(() => paths.api("/reports"));
+```
+
+The safe mental model is:
+
+- do not raw `fetch(...)` for normal app work
+- do not invent ad hoc local AJAX helpers
+- use the operation/runtime composable that matches the UI interaction
+- drop to `usersWebHttpClient.request(...)` only for exceptional low-level cases
+- use `usePaths().api(...)` when you need a custom scoped API path and the higher-level runtime does not already resolve it for you
+
 ### `_components/CrudAddEditForm.vue`
 
 This is the shared rendering shell for the add/edit form.

package/package.json

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

package/patterns/INDEX.md

@@ -20,6 +20,8 @@ How to use it:
   - `crud-links.md`
 - live actions, checkbox, toggle, patch button, inline action, `useCommand()`
   - `live-actions.md`
+- ajax, fetch, API call, request, endpoint, HTTP client, `useList()`, `useView()`, `useAddEdit()`, `useEndpointResource()`, `usersWebHttpClient`
+  - `client-requests.md`
 - filter, filters, search facets, chips, date range, enum filter, lookup filter, `useCrudListFilters`, `createCrudListFilters`
   - `filters.md`
 
@@ -30,4 +32,5 @@ How to use it:
 - [child-cruds.md](./child-cruds.md)
 - [crud-links.md](./crud-links.md)
 - [live-actions.md](./live-actions.md)
+- [client-requests.md](./client-requests.md)
 - [filters.md](./filters.md)

package/patterns/client-requests.md

@@ -0,0 +1,56 @@
+# Client Request Patterns
+
+Use when:
+
+- deciding which JSKIT client function to use for HTTP work
+- custom endpoint reads or writes
+- AJAX questions
+- replacing raw `fetch(...)` calls
+- choosing between `useCommand()`, `useList()`, `useView()`, `useAddEdit()`, and `useEndpointResource()`
+
+Rules:
+
+- Prefer the highest-level JSKIT runtime that matches the UI interaction.
+- Do not hand-roll local AJAX helpers when an existing JSKIT runtime already fits.
+- Do not use raw `fetch(...)` for normal app work.
+- Use `usePaths().api(...)` for custom scoped API paths instead of concatenating route params into URLs by hand.
+- Drop to `usersWebHttpClient.request(...)` only for exceptional low-level cases.
+
+Choose the function like this:
+
+```js
+// 1. Button/toggle/small mutation
+const command = useCommand({ ... });
+
+// 2. List endpoint
+const list = useList({ ... });
+
+// 3. Single-record endpoint
+const view = useView({ ... });
+
+// 4. Form save flow
+const form = useAddEdit({ ... });
+
+// 5. Truly custom endpoint
+const resource = useEndpointResource({ ... });
+```
+
+Use the CRUD wrappers when they fit:
+
+- `useCrudList()` for routed CRUD lists
+- `useCrudView()` for routed CRUD record loading
+- `useCrudAddEdit()` for routed CRUD forms
+
+Why this is the standard JSKIT shape:
+
+- `useCommand()` resolves the scoped API path for the current route and surface.
+- The higher-level list, view, add/edit, and command runtimes send requests through the shared HTTP runtime.
+- `usersWebHttpClient` already handles credentials and CSRF behavior.
+- `useEndpointResource()` is the shared endpoint primitive for loading, saving, and standard load/save error handling. Higher-level runtimes add UI feedback and field-error handling on top.
+
+Avoid:
+
+- raw `fetch(...)` for standard page or component work
+- page-local HTTP helpers that duplicate JSKIT runtime seams
+- manually concatenating scoped route params into API URLs
+- using a lower-level seam when a higher-level routed CRUD or command runtime already fits

package/templates/app/AGENTS.md

@@ -22,6 +22,36 @@ Use these references on demand:
 - `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
 
+## Mandatory Start Gate
+
+Before any non-trivial change:
+
+1. Read this file and the workflow files above in the current turn. Do not rely on memory alone.
+2. If the task involves JSKIT UI, routing, surfaces, CRUDs, filters, placements, live actions, or similar implementation details, scan `node_modules/@jskit-ai/agent-docs/patterns/INDEX.md` and read the relevant pattern files before editing.
+3. For substantial or multi-chunk work, create or update `.jskit/WORKBOARD.md` before editing.
+4. Before editing, print a compact read receipt with:
+   - `Read receipt: ...`
+   - `Active chunk: ...`
+   - `Generator decision: ...`
+   - `Relevant patterns: ...`
+   - `Active rules from docs: ...`
+5. When files need to be created, prefer `jskit generate ...` over creating them from scratch, even if the generated output will need follow-up adaptation. If not using a generator, say why.
+6. Do not edit code until the read receipt is printed and the workboard step is complete when it applies.
+
+## Mandatory Done Gate
+
+Before calling a chunk done, report:
+
+- `Deslop review: ...`
+- `JSKIT review: ...`
+- `Material/Vuetify review: ...`
+- `Verification: ...`
+- `Files changed: ...`
+- `Commands run: ...`
+- `Remaining unverified: ...`
+
+If a feature spans more than one chunk, repeat those passes on the whole changeset after the final chunk.
+
 Core rules:
 
 - Inspect the workspace before assuming a JSKIT app exists.
@@ -31,7 +61,6 @@ Core rules:
   - `Why this sticks: ...`
   - `Not doing: ...`
 - Keep that checkpoint compact. Do not expand it into a long preamble unless the developer asks for detail.
-- When a request involves JSKIT UI, routing, surfaces, CRUDs, filters, placements, live actions, or similar implementation details, scan `node_modules/@jskit-ai/agent-docs/patterns/INDEX.md` for matching keywords and read only the relevant pattern files.
 - 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.
@@ -43,7 +72,6 @@ Core rules:
 - For CRUD chunks, ask the developer which operations are allowed, which fields belong in the list view if one exists, and the intended look of the view and edit/new forms before generating code.
 - Every user-facing screen must pass a Material Design and Vuetify quality review before the chunk is considered done.
 - 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, Material Design/Vuetify review, and verification.
 - If a feature spans more than one chunk, run a final whole-changeset deslop pass, JSKIT pass, Material Design/Vuetify pass, and verification pass after the last chunk.