@jskit-ai/agent-docs 0.1.3 → 0.1.5

package/reference/autogen/packages/uploads-runtime.md

@@ -8,7 +8,7 @@ Use this on demand; do not load the full index at startup.
 
 ## Scope
 - Source: `packages/uploads-runtime/**/*{.js,.mjs,.cjs,.vue}`
-- Excludes: `test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `*.vitest.*`, `node_modules/`, `dist/`, `coverage/`, `docs/`, `LEGACY/`
+- Excludes: `test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `*.vitest.*`, `node_modules/`, `dist/`, `coverage/`, `docs/`, `LEGACY/`, `.vitepress/cache/`, `.vitepress/dist/`
 
 ## Sections
 

package/reference/autogen/packages/users-core.md

@@ -8,7 +8,7 @@ Use this on demand; do not load the full index at startup.
 
 ## Scope
 - Source: `packages/users-core/**/*{.js,.mjs,.cjs,.vue}`
-- Excludes: `test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `*.vitest.*`, `node_modules/`, `dist/`, `coverage/`, `docs/`, `LEGACY/`
+- Excludes: `test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `*.vitest.*`, `node_modules/`, `dist/`, `coverage/`, `docs/`, `LEGACY/`, `.vitepress/cache/`, `.vitepress/dist/`
 
 ## Sections
 

package/reference/autogen/packages/users-web.md

@@ -8,7 +8,7 @@ Use this on demand; do not load the full index at startup.
 
 ## Scope
 - Source: `packages/users-web/**/*{.js,.mjs,.cjs,.vue}`
-- Excludes: `test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `*.vitest.*`, `node_modules/`, `dist/`, `coverage/`, `docs/`, `LEGACY/`
+- Excludes: `test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `*.vitest.*`, `node_modules/`, `dist/`, `coverage/`, `docs/`, `LEGACY/`, `.vitepress/cache/`, `.vitepress/dist/`
 
 ## Sections
 

package/reference/autogen/packages/workspaces-core.md

@@ -8,7 +8,7 @@ Use this on demand; do not load the full index at startup.
 
 ## Scope
 - Source: `packages/workspaces-core/**/*{.js,.mjs,.cjs,.vue}`
-- Excludes: `test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `*.vitest.*`, `node_modules/`, `dist/`, `coverage/`, `docs/`, `LEGACY/`
+- Excludes: `test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `*.vitest.*`, `node_modules/`, `dist/`, `coverage/`, `docs/`, `LEGACY/`, `.vitepress/cache/`, `.vitepress/dist/`
 
 ## Sections
 

package/reference/autogen/packages/workspaces-web.md

@@ -8,7 +8,7 @@ Use this on demand; do not load the full index at startup.
 
 ## Scope
 - Source: `packages/workspaces-web/**/*{.js,.mjs,.cjs,.vue}`
-- Excludes: `test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `*.vitest.*`, `node_modules/`, `dist/`, `coverage/`, `docs/`, `LEGACY/`
+- Excludes: `test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `*.vitest.*`, `node_modules/`, `dist/`, `coverage/`, `docs/`, `LEGACY/`, `.vitepress/cache/`, `.vitepress/dist/`
 
 ## Sections
 

package/reference/autogen/tooling/config-eslint.md

@@ -8,7 +8,7 @@ Use this on demand; do not load the full index at startup.
 
 ## Scope
 - Source: `tooling/config-eslint/**/*{.js,.mjs,.cjs,.vue}`
-- Excludes: `test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `*.vitest.*`, `node_modules/`, `dist/`, `coverage/`, `docs/`, `LEGACY/`
+- Excludes: `test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `*.vitest.*`, `node_modules/`, `dist/`, `coverage/`, `docs/`, `LEGACY/`, `.vitepress/cache/`, `.vitepress/dist/`
 
 ## Sections
 

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

@@ -8,7 +8,7 @@ Use this on demand; do not load the full index at startup.
 
 ## Scope
 - Source: `tooling/create-app/**/*{.js,.mjs,.cjs,.vue}`
-- Excludes: `test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `*.vitest.*`, `node_modules/`, `dist/`, `coverage/`, `docs/`, `LEGACY/`
+- Excludes: `test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `*.vitest.*`, `node_modules/`, `dist/`, `coverage/`, `docs/`, `LEGACY/`, `.vitepress/cache/`, `.vitepress/dist/`
 
 ## Sections
 

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

@@ -8,7 +8,7 @@ Use this on demand; do not load the full index at startup.
 
 ## Scope
 - Source: `tooling/jskit-catalog/**/*{.js,.mjs,.cjs,.vue}`
-- Excludes: `test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `*.vitest.*`, `node_modules/`, `dist/`, `coverage/`, `docs/`, `LEGACY/`
+- Excludes: `test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `*.vitest.*`, `node_modules/`, `dist/`, `coverage/`, `docs/`, `LEGACY/`, `.vitepress/cache/`, `.vitepress/dist/`
 
 ## Sections
 

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

@@ -8,7 +8,7 @@ Use this on demand; do not load the full index at startup.
 
 ## Scope
 - Source: `tooling/jskit-cli/**/*{.js,.mjs,.cjs,.vue}`
-- Excludes: `test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `*.vitest.*`, `node_modules/`, `dist/`, `coverage/`, `docs/`, `LEGACY/`
+- Excludes: `test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `*.vitest.*`, `node_modules/`, `dist/`, `coverage/`, `docs/`, `LEGACY/`, `.vitepress/cache/`, `.vitepress/dist/`
 
 ## Sections
 

package/reference/autogen/tooling/test-support.md

@@ -8,7 +8,7 @@ Use this on demand; do not load the full index at startup.
 
 ## Scope
 - Source: `tooling/test-support/**/*{.js,.mjs,.cjs,.vue}`
-- Excludes: `test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `*.vitest.*`, `node_modules/`, `dist/`, `coverage/`, `docs/`, `LEGACY/`
+- Excludes: `test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `*.vitest.*`, `node_modules/`, `dist/`, `coverage/`, `docs/`, `LEGACY/`, `.vitepress/cache/`, `.vitepress/dist/`
 
 ## Sections
 

package/reference/autogen/tooling/testUtils.md

@@ -8,7 +8,7 @@ Use this on demand; do not load the full index at startup.
 
 ## Scope
 - Source: `tooling/testUtils/**/*{.js,.mjs,.cjs,.vue}`
-- Excludes: `test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `*.vitest.*`, `node_modules/`, `dist/`, `coverage/`, `docs/`, `LEGACY/`
+- Excludes: `test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `*.vitest.*`, `node_modules/`, `dist/`, `coverage/`, `docs/`, `LEGACY/`, `.vitepress/cache/`, `.vitepress/dist/`
 
 ## Sections
 

package/skills/jskit-review/SKILL.md

@@ -23,7 +23,7 @@ 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
+- `../../site/guide/index.md` when compressed guidance is ambiguous
 
 Inspect app-local files when they exist:
 
@@ -43,7 +43,8 @@ Use `.jskit/WORKBOARD.md` to determine the active chunk when available.
 
 1. Deslop review
 2. JSKIT best-practices review
-3. Verification review
+3. Material Design and Vuetify review
+4. Verification review
 
 ## Deslop review
 
@@ -65,6 +66,15 @@ Check for:
 - surface, route, ownership, and migration choices that violate JSKIT conventions
 - metadata that no longer matches actual behavior
 
+## Material Design and Vuetify review
+
+Check that user-facing screens:
+
+- follow Material Design and Vuetify best practices
+- use clear layout hierarchy, spacing, actions, and empty/error states
+- use coherent list, table, and form patterns
+- improve weak screens before sign-off rather than only recording the problem
+
 ## Verification review
 
 Check that verification is appropriate for the target:

package/templates/APP_BLUEPRINT.md

@@ -44,6 +44,8 @@
 - Baseline runtime packages:
 - Optional runtime packages:
 - Generator packages to use:
+- Package-owned workflows to accept as baseline:
+- Package-owned workflows to override or extend:
 
 ## Implementation Notes
 
@@ -51,6 +53,12 @@
 - Non-CRUD pages to scaffold:
 - Custom code areas:
 
+## CRUD Planning
+
+| CRUD | Operations | List Fields | View Form Shape | Edit/New Form Shape | Notes |
+| --- | --- | --- | --- | --- | --- |
+| | | | | | |
+
 ## Delivery Plan
 
 | Chunk | Goal | Type | Depends on | Done when |
@@ -68,4 +76,5 @@ Chunk notes:
 - Commands to run:
 - Playwright coverage plan:
 - Test auth strategy:
+- UI review expectations:
 - Known open questions:

package/templates/WORKBOARD.md

@@ -14,9 +14,9 @@
 
 ## Chunk Tracker
 
-| Chunk | Goal | Status | Deslop | JSKIT Review | Verification | Notes |
-| --- | --- | --- | --- | --- | --- | --- |
-| | | | | | | |
+| Chunk | Goal | Status | Deslop | JSKIT Review | UI Review | Verification | Notes |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| | | | | | | | |
 
 Status guide:
 

package/templates/app/AGENTS.md

@@ -16,7 +16,7 @@ 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/site/guide/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
@@ -24,15 +24,27 @@ Use these references on demand:
 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 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`.
+- 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.
+- 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, 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.
+- 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.
 - 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.

package/workflow/bootstrap.md

@@ -15,6 +15,7 @@ Safe bootstrap paths:
    - 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.
+   - Once a baseline package stack is chosen, assume its standard package-owned workflows unless the developer asks for overrides.
 
 Important constraint:
 
@@ -31,7 +32,20 @@ Version 0 sketch:
    - database engine: MySQL or Postgres
    - auth provider, with Supabase as the default documented path
    - whether the first baseline should include workspaces, realtime, or assistant
-3. Once those high-level choices are clear, continue into deeper scoping questions later.
+3. Treat Stage 1 as a package-stack decision, not a blank-slate workflow design exercise.
+4. Once those high-level choices are clear, continue into deeper scoping questions later.
+
+Ask setup values plainly:
+
+- Only ask for setup values that correspond to the modules or packages already chosen for the baseline.
+- When the next package install needs concrete local development values, ask for them directly using the exact env var names or option names.
+- Do not hide behind vague requests for "credentials" or "values after that boundary".
+- In this workflow, these are routine setup inputs:
+  - If the MySQL runtime is selected: `DB_NAME`, `DB_USER`, `DB_PASSWORD`
+  - If the MySQL host or port differs from the local default `127.0.0.1:3306`: `DB_HOST`, `DB_PORT`
+  - If Supabase auth is selected: `AUTH_SUPABASE_URL`, `AUTH_SUPABASE_PUBLISHABLE_KEY`
+  - If browser-facing auth callbacks are relevant: confirm whether `APP_PUBLIC_URL` should stay `http://localhost:5173`
+- Ask in plain language and continue once the developer provides the values.
 
 Baseline expectations after initialization:
 
@@ -39,6 +53,7 @@ Baseline expectations after initialization:
 - install the baseline runtime packages in the documented order
 - install dependencies
 - run database migrations when the chosen package set requires them
+- use the standard packaged workflows that come with those packages unless the blueprint records an override
 - leave the app in a reproducible, verified baseline state
 
-Do not improvise package order. Use the distributed guide chapters under `guide/agent/app-setup/` or `guide/human/app-setup/`.
+Do not improvise package order. Use the distributed guide chapters under `guide/agent/app-setup/` or `site/guide/app-setup/`.

package/workflow/feature-delivery.md

@@ -21,13 +21,28 @@ For each chunk, follow this order:
 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.
+7. Review user-facing screens against Material Design and Vuetify best practices, and improve any screens that do not meet that bar.
+8. Verify the chunk with the relevant commands, including Playwright for meaningful UI flows.
+9. Update `.jskit/WORKBOARD.md` with status, commands run, and anything still unverified.
+10. Only then move to the next chunk.
+
+For CRUD chunks:
+
+1. Decide the table shape first.
+2. If `crud-server-generator` is going to own the CRUD schema, do not hand-write a separate migration for that CRUD table.
+3. Scaffold the server side first with `crud-server-generator`.
+4. Only after the shared resource file exists, scaffold the client side against that resource.
+5. Do not guess CRUD operations or screen shape. Ask the developer:
+   - which operations are allowed
+   - which fields belong in the list view if one exists
+   - what the view form should look like
+   - what the edit/new form should look like
 
 During implementation:
 
 - Prefer existing JSKIT helpers over local helper duplication.
+- If a selected JSKIT package already ships the required baseline workflow, install and verify that workflow before inventing custom code around it.
+- Ask only about overrides, restrictions, or app-specific additions to packaged baseline workflows.
 - 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.
@@ -38,6 +53,7 @@ After the last chunk:
 - 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
+  - review the whole changeset against Material Design and Vuetify best practices
   - run the widest relevant verification, including Playwright
   - update `.jskit/WORKBOARD.md` with the final result and any remaining gaps
 

package/workflow/review.md

@@ -6,7 +6,7 @@ Preferred review mode:
 - 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:
+Before calling a chunk or a whole changeset done, review it in four passes:
 
 1. Deslop review
    - repeated functions or duplicated local helpers
@@ -22,7 +22,13 @@ Before calling a chunk or a whole changeset done, review it in three passes:
    - 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
+3. UI standards review
+   - every user-facing screen follows Material Design and Vuetify best practices
+   - list screens use clear hierarchy, actions, density, empty states, and table/list patterns
+   - view and edit/new screens use clear form grouping, labels, helper text, validation, spacing, and action placement
+   - responsive layout, loading, disabled, success, and error states are coherent
+   - improve weak screens before sign-off; do not just note the problem and move on
+4. Verification review
    - 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
@@ -38,4 +44,4 @@ Minimum expectation:
 
 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.
+- If the work was split into more than one chunk, repeat all four passes over the whole changeset after the final chunk is complete.

package/workflow/scoping.md

@@ -22,17 +22,26 @@ The blueprint must capture at least:
 - package install plan
 - generator plan
 - custom-code areas
+- baseline package-owned workflows and any intended overrides
 - delivery plan broken into chunks
+- CRUD-specific operation and screen decisions where relevant
 
 Scoping rules:
 
-- Use `guide/agent/index.md` for fast navigation and `guide/human/index.md` for exact details.
+- Use `guide/agent/index.md` for fast navigation and `site/guide/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.
+- Record which selected JSKIT package-owned workflows are accepted as baseline and which, if any, need custom behavior.
+- Do not ask the developer to redesign package-owned baseline workflows from scratch. Ask only whether the default behavior is accepted or whether the app needs overrides, restrictions, or extensions.
 - 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.
+- For each CRUD chunk, decide these before implementation:
+  - which operations exist: `list`, `view`, `new`, `edit`, `delete`, or a narrower set
+  - which fields appear in the list view if a list exists
+  - the intended structure and visual hierarchy of the view form
+  - the intended structure and visual hierarchy of the edit/new form
 - 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, functional boundaries, and chunk plan well enough that the implementation path is obvious.

package/workflow/workboard.md

@@ -17,7 +17,7 @@ Purpose:
 
 - track the current request
 - record the current stage and current chunk
-- track chunk status across implementation, deslop, JSKIT review, and verification
+- track chunk status across implementation, deslop, JSKIT review, UI review, and verification
 - record blockers, open questions, and remaining gaps
 
 Workboard rules: