@jskit-ai/agent-docs 0.1.242 → 0.1.244

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/`, `.vitepress/cache/`, `.vitepress/dist/`
+- Excludes: `.build/`, `.git/`, `.jscpd/`, `.jskit/`, `coverage/`, `dist/`, `docs/`, `node_modules/`, `test/`, `tests/`, `__tests__/`, `.vitepress/cache/`, `.vitepress/dist/`, `skills/jskit/references/patterns/`, `*.test.*`, `*.spec.*`, `*.vitest.*`
 
 ## 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/`, `.vitepress/cache/`, `.vitepress/dist/`
+- Excludes: `.build/`, `.git/`, `.jscpd/`, `.jskit/`, `coverage/`, `dist/`, `docs/`, `node_modules/`, `test/`, `tests/`, `__tests__/`, `.vitepress/cache/`, `.vitepress/dist/`, `skills/jskit/references/patterns/`, `*.test.*`, `*.spec.*`, `*.vitest.*`
 
 ## Sections
 
@@ -19,17 +19,17 @@ Exports
 - None
 Local functions
 - `parseInlineArg(name)`
-- `toSortedUniqueStrings(values)`
-- `fileExists(absolutePath)`
-- `collectPackageRoots(packagesRoot)`
-- `normalizeWorkspacePatterns(value)`
-- `createWorkspaceSegmentPattern(segment = "")`
-- `expandWorkspacePattern(repoRoot, workspacePattern = "")`
 - `collectReleasePackageVersions(repoRoot)`
-- `readJson(absolutePath)`
 - `buildCatalog({ repoRoot, packagesRoot, outputPath })`
 - `main()`
 
+### `scripts/framework-packages.mjs`
+Exports
+- `collectSingletonPackageIds(packageJsons)`
+- `discoverFrameworkPackages(packagesRoot)`
+Local functions
+- `fileExists(filePath)`
+
 ### `scripts/jskit.mjs`
 Exports
 - `isCliEntrypoint(argvPath = process.argv[1])`
@@ -102,7 +102,6 @@ Exports
 - `validateSingletonPeerDependencies(packages)`
 Local functions
 - `fileExists(filePath)`
-- `discoverFrameworkPackages()`
 - `requireStringArray(value, label)`
 - `requireArchitectureId(value, label)`
 - `validateCapabilityMap(value, label)`

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

@@ -8,7 +8,7 @@ Use this on demand; do not load the full index at startup.
 
 ## Scope
 - Source: `tooling/jskit-release/**/*{.js,.mjs,.cjs,.vue}`
-- Excludes: `test/`, `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, `*.vitest.*`, `node_modules/`, `dist/`, `coverage/`, `docs/`, `.vitepress/cache/`, `.vitepress/dist/`
+- Excludes: `.build/`, `.git/`, `.jscpd/`, `.jskit/`, `coverage/`, `dist/`, `docs/`, `node_modules/`, `test/`, `tests/`, `__tests__/`, `.vitepress/cache/`, `.vitepress/dist/`, `skills/jskit/references/patterns/`, `*.test.*`, `*.spec.*`, `*.vitest.*`
 
 ## Sections
 
@@ -44,7 +44,7 @@ Exports
 - `updatePatternPackageJsonContents(contents, versions)`
 - `validateReleaseState(records, repoRoot)`
 Local functions
-- `normalizeRegistryUrl(value = DEFAULT_REGISTRY)`
+- `normalizeRegistryUrl(value)`
 - `fileExists(absolutePath)`
 - `readJsonFile(absolutePath)`
 - `serializeJson(value)`
@@ -52,7 +52,6 @@ Local functions
 - `followVersion(declared, version)`
 - `expandWorkspacePattern(repoRoot, pattern)`
 - `releaseConfig(repoRoot)`
-- `hydrateLocalDependencies(records)`
 - `currentVersionMap(records)`
 - `prepareManifests(records, versions, repoRoot, config)`
 - `versionFilePaths(record)`
@@ -66,7 +65,7 @@ Local functions
 - `createNpmUserConfig(registry, directory, records = [])`
 - `git(repoRoot, args)`
 - `releaseCommitMessage(entries)`
-- `publishRelease(records, { cwd: repoRoot, dryRun, registry })`
+- `publishRelease(records, { cwd: repoRoot, registry })`
 - `publishCommand(options)`
 - `forgetPinnedLockEntries(repoRoot, names)`
 - `installReleasedPins(repoRoot, { attempts = 20, delayMs = Number(process.env.JSKIT_RELEASE_RETRY_DELAY_MS || 30_000) } = {})`

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/`, `.vitepress/cache/`, `.vitepress/dist/`
+- Excludes: `.build/`, `.git/`, `.jscpd/`, `.jskit/`, `coverage/`, `dist/`, `docs/`, `node_modules/`, `test/`, `tests/`, `__tests__/`, `.vitepress/cache/`, `.vitepress/dist/`, `skills/jskit/references/patterns/`, `*.test.*`, `*.spec.*`, `*.vitest.*`
 
 ## Sections
 
@@ -22,33 +22,6 @@ Exports
 - `startViteFixture({ fixtureRoot, configFile = "vite.config.mjs", env = {}, port: requestedPort } = {})`
 - `stopProcess(runtime)`
 
-### `currentJskitWorkspaces.mjs`
-Exports
-- `CURRENT_JSKIT_WORKSPACE_NPM_ENV`
-- `restoreCurrentJskitDependencyVersions(appRoot, packages)`
-- `stageCurrentJskitWorkspaces(appRoot)`
-Local functions
-- `readJson(filePath)`
-- `collectCurrentJskitPackages()`
-
 ### `fakeFastify.mjs`
 Exports
 - `createFakeFastifyPolicyRuntime({ csrfHandler, autoRunPlugin = null } = {})`
-
-### `jskitPackage.mjs`
-Exports
-- `writeJskitConfig(packageRoot, jskitOrSource)`
-Local functions
-- `resolveJskitConfig(jskitOrSource)`
-
-### `patternApp.mjs`
-Exports
-- `copyFoundationPattern({ cwd, name, pattern = "shell-foundation" } = {})`
-
-### `runCli.js`
-Exports
-- `createCliRunner(cliPath)`
-
-### `tempDir.mjs`
-Exports
-- `withTempDir(run, { prefix = "jskit-test-" } = {})`

package/skills/jskit/SKILL.md

@@ -27,7 +27,7 @@ options, routing, package discovery, transport, or lifecycle behaviour before
 trying the documented API. Inspect implementation source only for a concrete
 failure or an API question the guide and example cannot answer. Name that
 failure or question first, inspect only its relevant owner, then return to
-implementation and verification. Do not tour a dependency tree for confidence.
+implementation and verification.
 
 Do not write or consult receipts, provenance, completion ledgers, or other
 durable bookkeeping for pattern or authoring-tool runs. Current source,
@@ -42,11 +42,13 @@ manifests, migrations, tests, and runtime behaviour are the evidence.
    own a second project brain or prescribe a particular agent orchestrator.
 4. Load only relevant references:
    - [port guide](references/existing-application-migration.md) for existing apps.
-   - [Workspace invitations](references/multi-homing.md).
+   - [heuristics index](references/heuristics/INDEX.md) for recurring traps.
+   - [multi-homing](references/multi-homing.md) for workspaces or invitations.
    - For creation, foundation patterns, or package selection, read
      [application operations](references/app-operations.md).
    - Before database, schema, CRUD, repository, or persistence work, read
-     [CRUD operations](references/crud-operations.md) completely.
+     [CRUD operations](references/crud-operations.md) completely; for custom
+     form actions, also [form actions](references/crud-form-actions.md).
    - For routes, placements, user-facing UI, or browser verification, read
      [UI operations](references/ui-operations.md).
    - For every Vue/Vuetify UI creation, modification, review, or deslop task,
@@ -75,9 +77,9 @@ example. Before inspecting an unfamiliar package, use `rg --files` on its
 observed directory and select the relevant files from that inventory; do not
 try guessed source directories. Import subpaths are `exports` aliases, not
 physical paths: resolve them through installed `package.json#exports` or
-`import.meta.resolve()` when following an import. This rule applies to every
-package and task, not only CRUDs. Use the documented option when the guide or
-pattern already explains the behaviour instead of inspecting internals.
+`import.meta.resolve()` when following an import. Use the documented option
+when the guide or pattern already explains the behaviour instead of inspecting
+internals.
 
 ## Implement a change
 

package/skills/jskit/references/app-operations.md

@@ -8,7 +8,7 @@ Adopt the foundation's accessible HTML skeleton, inline styles, Reload link and
 startup-error message; package updates do not rewrite existing app HTML. Follow
 its cold-browser proof at compact, medium and expanded widths: delay JavaScript,
 check loading feedback, then release it and check app mount, including production
-builds. Compression belongs to hosting, not Genesis.
+builds. Response compression belongs to hosting.
 
 ## Establish a new application
 

package/skills/jskit/references/crud-form-actions.md

@@ -0,0 +1,62 @@
+<!-- Generated from `packages/agent-docs/site/guide/framework/crud-form-actions.md` by `npm run agent-docs:build`. -->
+
+# Record form actions and validation
+
+`CrudAddEditScreen` provides an optional `actions` slot with Cancel and Save as
+its default content. The slot exposes `screen`, `mode`, `formRuntime`,
+`formState`, `addEdit`, `saveLabel`, the resolved
+`cancelTo` route target, and `submit`. Custom actions call `submit()` and bind
+their disabled state to `addEdit.isSubmitDisabled`. Keyboard submission uses
+the same runtime. `addEdit.isSaving` stays true through the request and
+asynchronous `onSaveSuccess` callback; duplicate
+submissions remain blocked during both.
+
+`useAddEdit()` and the `addEdit` runtime exposed by `useCrudAddEdit()` and
+`useCrudAddEditScreen()` provide:
+
+- `validationAttempted`: initially `false`; becomes `true` when a permitted
+  submission reaches local validation, including a valid attempt.
+- `validationErrors`: a field-to-message object, empty before an attempt or
+  after reset. After an attempt, it revalidates the current payload against the
+  configured input schema as reactive field values change. It contains only
+  local validation errors. `fieldErrors` holds the last submission's field
+  errors, including server errors, independently of live validation.
+- `resetValidation()`: clears the attempt flag and field-error bag. It does not
+  change the form model. Route changes also reset validation
+  unless `clearOnRouteChange: false` is configured.
+
+For guidance beside a custom button, set `addEditOptions.validationFeedback`
+to `false` on `useCrudAddEditScreen()` or `useCrudAddEdit()`. With `useAddEdit()`,
+pass `validationFeedback: false` directly. The default is `true`. Setting it to
+`false` suppresses only local validation feedback; invalid saves remain blocked.
+Permissions, network and server failures, and success feedback behave normally.
+
+Inside `CrudAddEditScreen`, alongside the existing `fields` slot:
+
+```vue
+<template #actions="{ addEdit, submit, saveLabel, cancelTo }">
+  <v-btn v-if="cancelTo" variant="outlined" :to="cancelTo">Cancel</v-btn>
+  <div>
+    <v-btn :disabled="addEdit.isSubmitDisabled" @click="submit">
+      {{ addEdit.isSaving ? "Saving…" : saveLabel }}
+    </v-btn>
+    <p v-if="addEdit.validationAttempted" aria-live="polite">
+      {{ Object.values(addEdit.validationErrors).join(" ") }}
+    </p>
+  </div>
+</template>
+```
+
+For Save and add another, keep the selected action in local application state
+and call the same `submit()`. Use `addEditOptions.onSaveSuccess(payload, context)`
+to clear the successfully saved model, call `screen.addEdit.resetValidation()`,
+and prepare the next entry. This callback replaces default success navigation
+and invalidation; perform those there when needed. Clear the model only in
+`onSaveSuccess`: `submit()` also resolves after invalid or failed submissions.
+Guard action selection with `isSubmitDisabled` and restore the default action
+after each attempt so keyboard submission uses normal Save. Track the clicked
+button separately to keep guidance beside it while fields are corrected.
+
+Payload builders used by live validation (`buildPayload` or `buildRawPayload`)
+must be safe to call repeatedly as reactive values change. Keep them free of
+requests, navigation, and other side effects.

package/skills/jskit/references/crud-operations.md

@@ -144,16 +144,15 @@ need cross-owner denial tests.
 `useCrudAddEditScreen()` accepts `saveSuccess` at the top level. After saving,
 the default behaviour invalidates `saveSuccess.invalidateQueryKey`, navigates
 to a configured record-view URL when one resolves, and otherwise falls back to
-the list URL. For a create-and-list app, use `navigateToView: false` and the
-configured `listUrlTemplate`, as in the public example above. The list URL may
-also come from `addEditOptions.listUrlTemplate`.
+the list URL. For a create-and-list app, use `navigateToView: false` and
+`saveSuccess.listUrlTemplate`, the only list URL save navigation reads, as in the
+public example above.
 
 To keep the saved form open, set both `saveSuccess.navigateToView` and
 `saveSuccess.navigateToList` to `false`. `addEditOptions.onSaveSuccess` replaces
 the default success handling, including query invalidation and navigation;
 reserve it for custom success behaviour. Returning to the list needs only the
-documented `saveSuccess` options, not a custom router callback or inspection of
-the shared form implementation.
+`saveSuccess` options, not a router callback.
 
 ## Browser routes and responsive lists
 
@@ -301,17 +300,18 @@ this raw test encoding into page code.
 Deletion requires an explicit shared `DELETE` operation and confirmation
 decision. Use `CrudDeleteAction` and `useCrudDeleteAction()` through the view
 actions slot; do not rebuild their confirmation, request, invalidation, and
-navigation flow.
+navigation flow. After a delete it returns to the list before invalidating the
+resource's queries, so the deleted record never refetches as "Record not found."
 
 The delete action resolves its HTTP client from the resource's `apiAccess`, just
 like the list, view and form helpers. For `apiAccess: "public"`, DELETE requests
 skip session CSRF discovery; no `/api/session` endpoint or page-local client
 wiring is required. Authenticated resources retain the configured client's CSRF
-behavior. An explicit `client` override is supported and receives the same
-resource-aware public request options. This does not change server authorization.
+behavior. An explicit `client` override receives the same request options.
+Server authorization is unchanged.
 
 For custom form actions, see
-[record form actions](https://mobily-enterprises.github.io/jskit-ai/guide/framework/crud-form-actions).
+[record form actions](./crud-form-actions.md).
 
 ## Strict temporal values
 

package/skills/jskit/references/existing-application-migration.md

@@ -292,13 +292,6 @@ ACL, and restrictive umask. Setup must fail if it cannot establish that
 contract. Do not make package installation, Git, agents, or preview startup run
 recursive ownership or mode repair afterward.
 
-For Vibe64-managed workspaces, the concrete contract is group `vibe64`,
-directory mode `2770`, access and inherited default group ACL `vibe64:rwx`, no
-access for other users, and process umask `0007`. The enabled human user and
-`v64d_<workspace>` identity both belong to the group. Other hosts may use
-different concrete identities, but they must provide the same creation-time
-guarantee.
-
 Do not conflate these identities:
 
 - The filesystem identity controls who may create and replace source files.

package/{patterns → skills/jskit/references/heuristics}/INDEX.md

@@ -1,60 +1,46 @@
-# JSKIT Patterns Index
+<!-- Generated from `packages/agent-docs/heuristics/INDEX.md` by `npm run agent-docs:build`. -->
 
-Use this index as the first stop for recurring JSKIT implementation heuristics and workflow traps.
+# JSKIT Heuristics Index
+
+Use this index for recurring JSKIT implementation heuristics and workflow traps.
+Source patterns with complete example trees are listed separately in the source
+pattern index.
 
 How to use it:
 
 - Match the user request against the keywords below.
-- Open only the relevant pattern files.
-- Use patterns as implementation guidance, not as permission to skip normal scoping or user clarification.
+- Open only the relevant heuristic files.
+- Use heuristics as implementation guidance, not as permission to skip normal scoping or user clarification.
 
 ## Keyword Map
 
 - tabs, menu items, icons, shell links, profile links, subpage tabs, placements
-  - `placements.md`
+  - [placements.md](./placements.md)
 - surfaces, app/admin/home/console, "which surface", route ownership, placement visibility
-  - `surfaces.md`
+  - [surfaces.md](./surfaces.md)
 - page, route page, placeholder page, screen stub, menu-linked page, placements
-  - `page-scaffolding.md`
+  - [page-scaffolding.md](./page-scaffolding.md)
 - child crud, nested crud, embedded list, subroute, separate page, parent/child layout
-  - `child-cruds.md`
+  - [child-cruds.md](./child-cruds.md)
 - crud, crud server, crud ui, resource contract, table creation, migrations, ownership, JSON API, standard screens
-  - `crud-authoring.md`
+  - [crud-authoring.md](./crud-authoring.md)
 - CRUD links, record placeholders, `paths.page()`, `resolveViewUrl`, `resolveEditUrl`, `resolveParams`
-  - `crud-links.md`
+  - [crud-links.md](./crud-links.md)
 - `definePage`, redirect, child redirect, settings landing, `redirectToChild`
-  - `page-redirects.md`
+  - [page-redirects.md](./page-redirects.md)
 - live actions, checkbox, toggle, patch button, delete confirmation, destructive action, inline action, `useCommand()`, `useCrudDeleteAction()`
-  - `live-actions.md`
+  - [live-actions.md](./live-actions.md)
 - ajax, fetch, API call, request, endpoint, HTTP client, `useCrudListScreen()`, `useCrudViewScreen()`, `useCrudAddEditScreen()`, `useList()`, `useView()`, `useAddEdit()`, `useEndpointResource()`, `httpWebClient`
-  - `client-requests.md`
+  - [client-requests.md](./client-requests.md)
 - playwright, browser test, e2e, ui verification, baseline test, authenticated ui test, test auth, dev login as, dev auth bypass
-  - `ui-testing.md`
+  - [ui-testing.md](./ui-testing.md)
 - UI contract, design contract, navigation roles, Back button, previous page, history, hardcoded destination, Deslop, density, placeholder copy, card shells, shared CRUD screens, row actions, synthetic rows, detail slots
-  - `ui-contract.md`
+  - [ui-contract.md](./ui-contract.md)
 - filter, filters, search facets, chips, date range, enum filter, lookup filter, `useCrudListFilters`, `createCrudListFilters`
-  - `filters.md`
+  - [filters.md](./filters.md)
 - `searchSchema`, `search: true`, `applyFilter`, server search, query validators, backend filters, internal JSON REST filters
-  - `server-search.md`
-- `actualField`, `storage.writeSerializer`, `storage.virtual`, computed field, virtual field, projection, `createCrudResourceRuntime`, `remainingBatchWeight`, datetime write serialization, temporalPrecision, json-rest-schema dates
-  - `crud-repository-mapping.md`
+  - [server-search.md](./server-search.md)
+- `actualField`, `storage.writeSerializer`, `storage.virtual`, computed field, virtual field, projection, `createCrudResourceRuntime`, datetime write serialization, temporalPrecision, json-rest-schema dates
+  - [crud-repository-mapping.md](./crud-repository-mapping.md)
 - row policy, permission filtering, visibility before pagination, recursive CTE, descendants, package cycle, `RowPolicyPlugin`
-  - `row-policies.md`
-
-## Current Patterns
-
-- [placements.md](./placements.md)
-- [surfaces.md](./surfaces.md)
-- [page-scaffolding.md](./page-scaffolding.md)
-- [child-cruds.md](./child-cruds.md)
-- [crud-authoring.md](./crud-authoring.md)
-- [crud-links.md](./crud-links.md)
-- [page-redirects.md](./page-redirects.md)
-- [live-actions.md](./live-actions.md)
-- [client-requests.md](./client-requests.md)
-- [ui-testing.md](./ui-testing.md)
-- [ui-contract.md](./ui-contract.md)
-- [filters.md](./filters.md)
-- [server-search.md](./server-search.md)
-- [crud-repository-mapping.md](./crud-repository-mapping.md)
-- [row-policies.md](./row-policies.md)
+  - [row-policies.md](./row-policies.md)

package/{patterns → skills/jskit/references/heuristics}/child-cruds.md

@@ -1,3 +1,5 @@
+<!-- Generated from `packages/agent-docs/heuristics/child-cruds.md` by `npm run agent-docs:build`. -->
+
 # Child CRUD Layout Patterns
 
 Use when:

package/{patterns → skills/jskit/references/heuristics}/client-requests.md

@@ -1,3 +1,5 @@
+<!-- Generated from `packages/agent-docs/heuristics/client-requests.md` by `npm run agent-docs:build`. -->
+
 # Client Request Patterns
 
 Use when:

package/{patterns → skills/jskit/references/heuristics}/crud-authoring.md

@@ -1,3 +1,5 @@
+<!-- Generated from `packages/agent-docs/heuristics/crud-authoring.md` by `npm run agent-docs:build`. -->
+
 # CRUD authoring
 
 Use this file for normal persisted entities, resource contracts, migrations,

package/{patterns → skills/jskit/references/heuristics}/crud-links.md

@@ -1,3 +1,5 @@
+<!-- Generated from `packages/agent-docs/heuristics/crud-links.md` by `npm run agent-docs:build`. -->
+
 # CRUD Link Resolution Patterns
 
 Use when:

package/{patterns → skills/jskit/references/heuristics}/crud-repository-mapping.md

@@ -1,9 +1,11 @@
+<!-- Generated from `packages/agent-docs/heuristics/crud-repository-mapping.md` by `npm run agent-docs:build`. -->
+
 # CRUD Repository Mapping
 
 Use when:
 - a CRUD resource needs explicit DB column mapping
 - a field should exist in API output but is not a real DB column
-- the user mentions computed fields, projections, or `remainingBatchWeight`
+- the user mentions computed fields or projections
 
 Default JSKIT pattern:
 1. Treat the schema as the API contract only.

package/{patterns → skills/jskit/references/heuristics}/filters.md

@@ -1,3 +1,5 @@
+<!-- Generated from `packages/agent-docs/heuristics/filters.md` by `npm run agent-docs:build`. -->
+
 # Structured Filters
 
 Use when:
@@ -6,7 +8,7 @@ Use when:
 - a screen mixes free-text search with structured facets
 
 Server-side note:
-- for the current CRUD server contract on the JSON REST path, see `server-search.md`
+- for the current CRUD server contract on the JSON REST path, see [server search](./server-search.md)
 - this file is about the shared structured-filter runtime used by CRUD list pages and explicit list-filter modules
 
 Ask first:

package/{patterns → skills/jskit/references/heuristics}/live-actions.md

@@ -1,3 +1,5 @@
+<!-- Generated from `packages/agent-docs/heuristics/live-actions.md` by `npm run agent-docs:build`. -->
+
 # Live Action Patterns
 
 Use when:

package/{patterns → skills/jskit/references/heuristics}/page-redirects.md

@@ -1,3 +1,5 @@
+<!-- Generated from `packages/agent-docs/heuristics/page-redirects.md` by `npm run agent-docs:build`. -->
+
 # Page Redirect Patterns
 
 Use when:

package/{patterns → skills/jskit/references/heuristics}/page-scaffolding.md

@@ -1,3 +1,5 @@
+<!-- Generated from `packages/agent-docs/heuristics/page-scaffolding.md` by `npm run agent-docs:build`. -->
+
 # Page Scaffolding Patterns
 
 Use when:
@@ -9,7 +11,7 @@ Use when:
 
 Check first:
 
-- the app blueprint route family and chosen surface
+- the project's product documentation, existing routes, and chosen surface
 - the page-and-placement source pattern
 - the current placement declarations and topology
 - the nearest existing routed host under `src/pages`
@@ -27,7 +29,7 @@ Rules:
   a semantic slot. Target concrete outlets only for deliberate infrastructure.
 - If the page sits under an existing routed host, reuse its `page.section-nav`
   ownership rather than creating a parallel navigation structure.
-- For a small placeholder route inside an existing route family, keep the change scoped unless the durable route or surface plan in the app blueprint changed.
+- For a small placeholder route inside an existing route family, keep the change scoped unless the project's documented route or surface plan changed.
 - Live pages must be usable screens, not instructional scaffolds. Do not ship copy such as "replace this", "use this area", or "this page is ready".
 - Never add a page header, title block, welcome heading, or standalone heading copy by default. Start with the useful content and actions; add a heading only when the user explicitly asks for one.
 - Prefer a direct `v-sheet` working region when the content needs a surface. Do not wrap every page in a generic `v-card`.
@@ -50,6 +52,6 @@ Avoid:
 
 - inventing a page and placement shape without checking the existing pattern and neighboring routes
 - adding a route-name heading, welcome heading, or other page title the user did not request
-- treating a small page stub as permission to rewrite marketing copy, route architecture, or app blueprint scope
+- treating a small page stub as permission to rewrite marketing copy, route architecture, or documented product scope
 - adding cards inside cards
 - treating Vuetify component defaults as the product architecture

package/{patterns → skills/jskit/references/heuristics}/placements.md

@@ -1,3 +1,5 @@
+<!-- Generated from `packages/agent-docs/heuristics/placements.md` by `npm run agent-docs:build`. -->
+
 # Placement Patterns
 
 Use when:

package/{patterns → skills/jskit/references/heuristics}/row-policies.md

@@ -1,3 +1,5 @@
+<!-- Generated from `packages/agent-docs/heuristics/row-policies.md` by `npm run agent-docs:build`. -->
+
 # Row Policies
 
 Use when:

package/{patterns → skills/jskit/references/heuristics}/server-search.md

@@ -1,3 +1,5 @@
+<!-- Generated from `packages/agent-docs/heuristics/server-search.md` by `npm run agent-docs:build`. -->
+
 # Server Search
 
 Use when:

package/{patterns → skills/jskit/references/heuristics}/surfaces.md

@@ -1,21 +1,23 @@
+<!-- Generated from `packages/agent-docs/heuristics/surfaces.md` by `npm run agent-docs:build`. -->
+
 # Surface Patterns
 
 Use when:
 
 - adding a new screen or feature
-- generating pages
+- adding pages
 - adding menu entries or widgets
 - deciding whether something belongs in `home`, `app`, `admin`, `console`, or another surface
 
 Check first:
 
-- the app blueprint surface plan
+- the project's product documentation and existing routes
 - existing route roots under `src/pages`
 - placement visibility by `surfaces`
 
 Rules:
 
-- Always ask which surface the feature belongs to before generating routes, placements, or related UI.
+- Always ask which surface the feature belongs to before adding routes, placements, or related UI.
 - Do not silently default new functionality to `app`.
 - Surface choice is architectural, not cosmetic. It controls routes, access, placement visibility, and often data ownership expectations.
 - When a link or widget should only appear on certain surfaces, use placement `surfaces` first and keep runtime `when` conditions for behavior-specific gating.

package/{patterns → skills/jskit/references/heuristics}/ui-contract.md

@@ -1,3 +1,5 @@
+<!-- Generated from `packages/agent-docs/heuristics/ui-contract.md` by `npm run agent-docs:build`. -->
+
 # JSKIT UI contract
 
 Use this contract when creating or reviewing JSKIT shell, page, CRUD, settings,
@@ -14,7 +16,7 @@ and action UI.
 - Check every page for Back to the previous page unless returning makes no
   product sense. Use the existing navigation owner; fixed destinations are
   deliberate, explicitly labelled exceptions. Follow the
-  [Back navigation contract](../guide/agent/framework/ui-operations.md#back-navigation)
+  [Back navigation contract](../ui-operations.md#back-navigation)
   for history, direct-entry fallback, retained context, and consistent placement.
 - Pages do not stack decorative cards inside structural cards.
 - Pages do not include a header, title block, welcome heading, or standalone

package/{patterns → skills/jskit/references/heuristics}/ui-testing.md

@@ -1,3 +1,5 @@
+<!-- Generated from `packages/agent-docs/heuristics/ui-testing.md` by `npm run agent-docs:build`. -->
+
 # UI Testing Pattern
 
 Use when: