@json-layout/core 2.8.2 → 2.9.1

package/src/webmcp/resolve.js

@@ -2,6 +2,20 @@
  * @file Node resolution for webmcp tools
  */
 
+/**
+ * In "menu" and "dialog" list edit modes the activated item is duplicated at the end
+ * of the children, the first occurrence being a read-only summary. Tools should always
+ * work on the editable occurrence.
+ * @param {import('../state/types.js').StateNode[]} children
+ * @param {string | number} key
+ * @returns {import('../state/types.js').StateNode|undefined}
+ */
+function findChild (children, key) {
+  const matches = children.filter((c) => c.key === key)
+  if (matches.length <= 1) return matches[0]
+  return matches.find((c) => !c.options.summary) ?? matches[0]
+}
+
 /**
  * Navigate from a root StateNode to a descendant node by path.
  * @param {import('../state/types.js').StateNode} root
@@ -18,8 +32,30 @@ export function resolveNode (root, path) {
   for (const segment of segments) {
     if (!current?.children) return undefined
     const key = /^\d+$/.test(segment) ? parseInt(segment, 10) : segment
-    current = current.children.find((c) => c.key === key)
+    current = findChild(current.children, key)
   }
 
   return current
 }
+
+/**
+ * Children of a node as they should be presented to an agent: hidden nodes are removed
+ * and the duplicated activated list item is deduplicated.
+ * @param {import('../state/types.js').StateNode} node
+ * @returns {import('../state/types.js').StateNode[]}
+ */
+export function visibleChildren (node) {
+  if (!node.children) return []
+  /** @type {import('../state/types.js').StateNode[]} */
+  const children = []
+  for (const child of node.children) {
+    if (child.layout.comp === 'none') continue
+    const existingIndex = children.findIndex((c) => c.fullKey === child.fullKey)
+    if (existingIndex === -1) {
+      children.push(child)
+    } else if (children[existingIndex].options.summary && !child.options.summary) {
+      children[existingIndex] = child
+    }
+  }
+  return children
+}

package/src/webmcp/schema.js

@@ -0,0 +1,169 @@
+/**
+ * @file Sub-schema resolution and skeleton projection for webmcp tools
+ * @description Large schemas cannot be serialized as a whole for a LLM agent,
+ * these utilities extract the fragment that governs a single node of the form.
+ */
+
+import { resolvePointerFragment } from '../utils/json-pointer.js'
+
+/** @typedef {import('../state/types.js').StateNode} StateNode */
+/** @typedef {import('../state/index.js').StatefulLayout} StatefulLayout */
+
+// keys injected in the schema by the compilation step, they are noise for a LLM agent.
+// errorMessage is always written by skeleton-node.js, at least as an empty object; a user
+// defined one survives in the pristine schema, which is preferred and never cleaned.
+const internalSchemaKeys = ['__pointer', 'errorMessage']
+
+/**
+ * @typedef {{ key: string | number, path: string, type?: string, title?: string, required?: boolean, enum?: unknown[], declared: true }} DeclaredField
+ */
+
+// keywords whose value maps a name chosen by the user to a sub-schema: their keys are not
+// schema keywords, a property may legitimately be named "errorMessage" or "__pointer"
+const schemaMapKeys = ['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas']
+
+/**
+ * Deep clone a schema fragment while removing the keys added by the compilation step.
+ * @param {unknown} fragment
+ * @returns {unknown}
+ */
+export function cleanSchemaFragment (fragment) {
+  if (Array.isArray(fragment)) return fragment.map(cleanSchemaFragment)
+  if (fragment && typeof fragment === 'object') {
+    /** @type {Record<string, unknown>} */
+    const clean = {}
+    for (const [key, value] of Object.entries(fragment)) {
+      if (internalSchemaKeys.includes(key)) continue
+      clean[key] = schemaMapKeys.includes(key) ? cleanSchemaMap(value) : cleanSchemaFragment(value)
+    }
+    return clean
+  }
+  return fragment
+}
+
+/**
+ * Clean the sub-schemas of a map without filtering the names used as its keys.
+ * @param {unknown} map
+ * @returns {unknown}
+ */
+function cleanSchemaMap (map) {
+  if (!map || typeof map !== 'object' || Array.isArray(map)) return cleanSchemaFragment(map)
+  /** @type {Record<string, unknown>} */
+  const clean = {}
+  for (const [name, subSchema] of Object.entries(map)) clean[name] = cleanSchemaFragment(subSchema)
+  return clean
+}
+
+/**
+ * Resolve a schema fragment from a skeleton pointer (ex: "_jl#/properties/filters/items").
+ * @param {object} schema - a JSON schema, its $id should match the pointer prefix
+ * @param {string} pointer
+ * @returns {object|undefined}
+ */
+export function resolveSchemaPointer (schema, pointer) {
+  const hashIndex = pointer.indexOf('#')
+  if (hashIndex === -1) return undefined
+  const schemaId = pointer.slice(0, hashIndex)
+  const fragment = pointer.slice(hashIndex + 1)
+  const schemaObject = /** @type {Record<string, unknown>} */(schema)
+  // '_jl' is the default id given by the compilation step to an anonymous schema. A pointer into
+  // another schema is refused even when this one has no $id at all: resolving it here would
+  // silently return a same-shaped fragment of the wrong document instead of failing over.
+  if (schemaId && schemaId !== '_jl' && schemaObject.$id !== schemaId) return undefined
+  if (!fragment) return schema
+  const resolved = resolvePointerFragment(schema, fragment)
+  if (!resolved.found) return undefined
+  return resolved.value && typeof resolved.value === 'object' ? /** @type {object} */(resolved.value) : undefined
+}
+
+/**
+ * Resolve the sub-schema that governs a node of the form.
+ * The schema given to the WebMCP instance is preferred (it is pristine),
+ * the compiled one is used as a fallback (it is cleaned up before being returned).
+ * @param {StateNode} node
+ * @param {StatefulLayout} statefulLayout
+ * @param {object|null} [originalSchema]
+ * @returns {object|undefined}
+ */
+export function resolveNodeSchema (node, statefulLayout, originalSchema) {
+  const pointers = [node.skeleton.refPointer, node.skeleton.pointer]
+  if (originalSchema) {
+    for (const pointer of pointers) {
+      const fragment = pointer && resolveSchemaPointer(originalSchema, pointer)
+      if (fragment) return fragment
+    }
+  }
+  const compiledSchema = statefulLayout.compiledLayout.schema
+  if (compiledSchema) {
+    for (const pointer of pointers) {
+      const fragment = pointer && resolveSchemaPointer(compiledSchema, pointer)
+      if (fragment) return /** @type {object} */(cleanSchemaFragment(fragment))
+    }
+  }
+  return undefined
+}
+
+/**
+ * Component of a node known only from its skeleton, used as a display hint.
+ * This is an approximation of the resolution done in state-node.js: a switch is resolved
+ * there by evaluating its expressions against the data, which is not available for a node
+ * the state tree did not hydrate, so the first case is taken as a representative one.
+ * @param {StatefulLayout} statefulLayout
+ * @param {string} pointer
+ * @returns {string|undefined}
+ */
+function getSkeletonComp (statefulLayout, pointer) {
+  const normalizedLayout = /** @type {any} */(statefulLayout.compiledLayout.normalizedLayouts[pointer])
+  if (!normalizedLayout) return undefined
+  if (typeof normalizedLayout.comp === 'string') return normalizedLayout.comp
+  if (Array.isArray(normalizedLayout.switch) && typeof normalizedLayout.switch[0]?.comp === 'string') {
+    return normalizedLayout.switch[0].comp
+  }
+  return undefined
+}
+
+/**
+ * List the fields declared by the skeleton of a node, even when the state tree
+ * did not hydrate them yet (a collapsed list item for example).
+ * @param {StateNode} node
+ * @param {StatefulLayout} statefulLayout
+ * @param {object|null} [originalSchema]
+ * @returns {DeclaredField[]}
+ */
+export function projectDeclaredFields (node, statefulLayout, originalSchema) {
+  /** @type {DeclaredField[]} */
+  const fields = []
+  let childrenKeys = node.skeleton.children ?? []
+  let pathPrefix = node.fullKey
+  if (childrenKeys.length === 0 && node.skeleton.childrenTrees?.length &&
+    (Array.isArray(node.data) || node.layout.comp === 'list')) {
+    // an array keeps the skeleton of its items in a separate tree, so the fields it declares
+    // are those of an item, addressed through an index
+    const itemSkeleton = statefulLayout.compiledLayout.skeletonNodes[node.skeleton.childrenTrees[0]]
+    childrenKeys = itemSkeleton?.children ?? []
+    pathPrefix = `${node.fullKey}/0`
+  }
+  for (const childKey of childrenKeys) {
+    const childSkeleton = statefulLayout.compiledLayout.skeletonNodes[childKey]
+    if (!childSkeleton) continue
+    const comp = getSkeletonComp(statefulLayout, childSkeleton.pointer)
+    if (comp === 'none') continue
+    /** @type {DeclaredField} */
+    const field = {
+      key: childSkeleton.key,
+      path: `${pathPrefix}/${childSkeleton.key}`,
+      declared: true
+    }
+    if (childSkeleton.title) field.title = childSkeleton.title
+    if (childSkeleton.required) field.required = true
+    const childSchema = /** @type {Record<string, any>|undefined} */(
+      (originalSchema && resolveSchemaPointer(originalSchema, childSkeleton.refPointer)) ||
+      (statefulLayout.compiledLayout.schema && resolveSchemaPointer(statefulLayout.compiledLayout.schema, childSkeleton.refPointer))
+    )
+    if (typeof childSchema?.type === 'string') field.type = childSchema.type
+    else if (comp) field.type = comp
+    if (Array.isArray(childSchema?.enum)) field.enum = childSchema.enum
+    fields.push(field)
+  }
+  return fields
+}

package/src/webmcp/suggestions-store.js

@@ -0,0 +1,121 @@
+/**
+ * @file Memory of the last suggestions returned for each node path
+ * @description Suggestion values can be large objects, they are not returned in full
+ * to the agent. They are memorized here so that setFieldValue can reuse the original
+ * value from its index.
+ *
+ * Searches on the same path accumulate rather than replace one another, and indices are
+ * absolute across them. Replacing meant a second search silently rebound every index the
+ * first had handed out, so an agent applying an index it had been given a moment earlier
+ * would set a different value with no error — the worst kind of failure this protocol can
+ * produce, since nothing in the transcript looks wrong. A write can change another
+ * field's options, so writes drop what they invalidate — see `retainFresh`.
+ */
+
+/** @typedef {{value: unknown, title: string, key?: string}} SuggestionItem */
+
+/**
+ * Per WebMCP instance memory of the suggestions, keyed by node path.
+ */
+export class SuggestionsStore {
+  /**
+   * @private
+   * @type {Map<string, SuggestionItem[]>}
+   */
+  _byPath = new Map()
+
+  /**
+   * What the node's items depended on when each path was memorized, so a write can tell
+   * whether it invalidated them. See `retainFresh`.
+   * @private
+   * @type {Map<string, unknown>}
+   */
+  _cacheKeys = new Map()
+
+  /**
+   * Paths that HAD memorized suggestions until a write dropped them. Kept so that the
+   * failure can say which of the two things happened: an agent told to "call
+   * getFieldSuggestions first" when it did exactly that, one call ago, cannot tell that
+   * the list went stale, and the eval shows it stops trusting suggestionIndex entirely.
+   * @private
+   * @type {Set<string>}
+   */
+  _invalidated = new Set()
+
+  /**
+   * Memorize a search's items and return the index its first item was given. Indices are
+   * absolute per path, so an index handed out earlier keeps meaning what the agent saw.
+   * @param {string} path
+   * @param {SuggestionItem[]} items
+   * @param {unknown} [cacheKey] - the node's itemsCacheKey, what its options depend on
+   * @returns {number} the index of the first of these items
+   */
+  add (path, items, cacheKey) {
+    this._invalidated.delete(path)
+    this._cacheKeys.set(path, cacheKey)
+    const known = this._byPath.get(path)
+    if (!known) {
+      this._byPath.set(path, [...items])
+      return 0
+    }
+    const baseIndex = known.length
+    known.push(...items)
+    return baseIndex
+  }
+
+  /**
+   * Drop only the paths a write actually invalidated.
+   *
+   * Clearing everything on every write was correct but far broader than the hazard it
+   * guarded: writing one field cannot change the options of a field whose list does not
+   * depend on it, and the eval caught the cost twice on the same case — once recovered in
+   * one call, once in three. `isFresh` is given the key recorded at `add` time so the
+   * caller can compare it with the node's current `itemsCacheKey`, which is what the state
+   * layer itself uses to decide whether to re-fetch: a resolved URL for a remote picker, so
+   * the comparison is exact where it matters, and a value that simply differs for an
+   * expression-based list, which over-invalidates in the safe direction.
+   * @param {(path: string, cacheKey: unknown) => boolean} isFresh
+   */
+  retainFresh (isFresh) {
+    for (const path of [...this._byPath.keys()]) {
+      if (isFresh(path, this._cacheKeys.get(path))) continue
+      this._byPath.delete(path)
+      this._cacheKeys.delete(path)
+      this._invalidated.add(path)
+    }
+  }
+
+  /**
+   * @param {string} path
+   * @returns {SuggestionItem[]|undefined}
+   */
+  get (path) {
+    return this._byPath.get(path)
+  }
+
+  /**
+   * Get the full original value memorized for a path at a given index.
+   * @param {string} path
+   * @param {number} index
+   * @returns {unknown}
+   */
+  getValue (path, index) {
+    const items = this._byPath.get(path)
+    if (!items) {
+      if (this._invalidated.has(path)) {
+        throw new Error(`the suggestions memorized for path "${path}" were dropped by a write that may have changed this field's options, call getFieldSuggestions on this path again`)
+      }
+      throw new Error(`no suggestion memorized for path "${path}", call getFieldSuggestions on this path first`)
+    }
+    if (!Number.isInteger(index) || index < 0 || index >= items.length) {
+      throw new Error(`suggestionIndex ${index} out of bounds for path "${path}" (${items.length} suggestion(s) memorized)`)
+    }
+    return items[index].value
+  }
+
+  clear () {
+    for (const path of this._byPath.keys()) this._invalidated.add(path)
+    this._byPath.clear()
+    this._cacheKeys.clear()
+  }
+}

package/src/webmcp/tools/describe-state.js

@@ -2,98 +2,54 @@
  * @file describeState tool
  */
 
-import { projectStateTree, projectNode, collectErrors, projectNodeToMarkdown, projectStateTreeToMarkdown, formatMutationResult } from '../project.js'
+import { collectScopedErrors, projectNodeToMarkdown, projectStateTreeToMarkdown, formatMutationResult } from '../project.js'
 import { resolveNode } from '../resolve.js'
+import { VariantsMemo } from '../variants-memo.js'
 
 export const inputSchema = {
   type: 'object',
   properties: {
     path: {
       type: 'string',
-      description: 'Path to a specific node (e.g. "/address/city"). Omit for full tree.'
-    }
-  }
-}
-
-export const outputSchema = {
-  type: 'object',
-  properties: {
-    state: {
-      type: 'object',
-      description: 'Projected state tree or single node'
-    },
-    valid: {
-      type: 'boolean'
-    },
-    errors: {
-      type: 'array',
-      items: {
-        type: 'object',
-        properties: {
-          path: { type: 'string' },
-          message: { type: 'string' }
-        }
-      }
+      description: 'Node path as returned by describeState (e.g. "/address/city"). Omit for the whole tree.'
     }
   }
 }
 
 /**
  * @param {string} dataTitle
- * @param {"small"|"medium"|"large"} [complexity]
  * @returns {string}
  */
-export function getDescription (dataTitle, complexity) {
-  let desc = `Describe the "${dataTitle}" form structure, field types, constraints, and current errors.`
-  if (complexity === 'large') {
-    desc += ' Use the "path" parameter to focus on a subtree — avoid calling without a path on large forms.'
-  }
-  return desc
-}
-
-/**
- * @param {import('../../state/index.js').StatefulLayout} statefulLayout
- * @param {{ path?: string }} args
- * @returns {{state: ReturnType<typeof projectStateTree>|ReturnType<typeof projectNode>, valid: boolean, errors: Array<{path: string, message: string}>}}
- */
-export function execute (statefulLayout, args) {
-  const errors = collectErrors(statefulLayout.stateTree.root)
-
-  if (args.path) {
-    const node = resolveNode(statefulLayout.stateTree.root, args.path)
-    if (!node) {
-      throw new Error(`node not found at path: ${args.path}`)
-    }
-    return {
-      state: projectNode(node, statefulLayout),
-      valid: statefulLayout.valid,
-      errors
-    }
-  }
-
-  return {
-    state: projectStateTree(statefulLayout.stateTree, statefulLayout),
-    valid: statefulLayout.valid,
-    errors
-  }
+export function getDescription (dataTitle) {
+  return `Describe the "${dataTitle}" form: every field with its path, type, constraints, current value and errors. Pass "path" to describe one subtree instead of the whole form.`
 }
 
 /**
  * @param {import('../../state/index.js').StatefulLayout} statefulLayout
  * @param {{ path?: string }} args
+ * @param {import('../variants-memo.js').VariantsMemo} [variantsMemo] - updated, not consulted:
+ * a read is what the agent asked to see, so every union under it is listed in full, and the
+ * memo is what later writes use to avoid repeating those lists
  * @returns {string}
  */
-export function toMarkdown (statefulLayout, args) {
+export function toMarkdown (statefulLayout, args, variantsMemo) {
+  const listed = new VariantsMemo()
+
   if (args.path) {
     const node = resolveNode(statefulLayout.stateTree.root, args.path)
     if (!node) {
       throw new Error(`node not found at path: ${args.path}`)
     }
-    const errors = collectErrors(node)
-    return formatMutationResult(statefulLayout.valid, errors,
-      projectNodeToMarkdown(node, statefulLayout)
+    const { errors, otherErrors } = collectScopedErrors(statefulLayout, node)
+    const markdown = formatMutationResult(statefulLayout.valid, errors,
+      projectNodeToMarkdown(node, statefulLayout, 0, undefined, listed),
+      otherErrors
     )
+    variantsMemo?.merge(listed)
+    return markdown
   }
 
-  return projectStateTreeToMarkdown(statefulLayout.stateTree, statefulLayout)
+  const markdown = projectStateTreeToMarkdown(statefulLayout.stateTree, statefulLayout, listed)
+  variantsMemo?.merge(listed)
+  return markdown
 }

package/src/webmcp/tools/edit-array.js

@@ -2,7 +2,7 @@
  * @file editArray tool
  */
 
-import { collectErrors } from '../project.js'
+import { collectScopedErrors, projectNodeToMarkdown } from '../project.js'
 import { resolveNode } from '../resolve.js'
 
 export const inputSchema = {
@@ -10,7 +10,7 @@ export const inputSchema = {
   properties: {
     path: {
       type: 'string',
-      description: 'Path to the array field (e.g. "/items", "/tags")'
+      description: 'Node path as returned by describeState (e.g. "/address/city"). Must be an array field.'
     },
     action: {
       type: 'string',
@@ -28,38 +28,23 @@ export const inputSchema = {
   required: ['path', 'action']
 }
 
-export const outputSchema = {
-  type: 'object',
-  properties: {
-    valid: { type: 'boolean' },
-    itemCount: { type: 'number' },
-    errors: {
-      type: 'array',
-      items: {
-        type: 'object',
-        properties: {
-          path: { type: 'string' },
-          message: { type: 'string' }
-        }
-      }
-    }
-  }
-}
-
 /**
  * @param {string} dataTitle
  * @returns {string}
  */
 export function getDescription (dataTitle) {
-  return `Add or remove items in an array field of "${dataTitle}". Use describeState to see current array contents.`
+  return `Add or remove items in an array field of "${dataTitle}". Use describeState to see current array contents. When adding an item it is activated for edition and its children fields are returned, they can then be filled with setFieldValue. The returned errors are scoped to this array.`
 }
 
 /**
  * @param {import('../../state/index.js').StatefulLayout} statefulLayout
  * @param {{ path: string, action: 'add'|'remove', index?: number, value?: unknown }} args
- * @returns {{ valid: boolean, itemCount: number, errors: Array<{path: string, message: string}> }}
+ * @param {import('../variants-memo.js').VariantsMemo} [variantsMemo] - a new item of a
+ * recursive schema carries the same union as the item that contains it; the memo keeps the
+ * response from printing it again
+ * @returns {{ valid: boolean, itemCount: number, index: number, itemMarkdown?: string, errors: Array<{path: string, message: string}>, otherErrors: number }}
  */
-export function execute (statefulLayout, args) {
+export function execute (statefulLayout, args, variantsMemo) {
   const node = resolveNode(statefulLayout.stateTree.root, args.path)
   if (!node) {
     throw new Error(`node not found at path: ${args.path}`)
@@ -70,16 +55,24 @@ export function execute (statefulLayout, args) {
   }
 
   const currentData = Array.isArray(node.data) ? [...node.data] : []
+  // input() drops the activation when the array shrinks, so it has to be read before
+  const activatedBefore = statefulLayout.activatedItems[node.fullKey]
+  let index
 
   if (args.action === 'add') {
-    const index = args.index !== undefined ? args.index : currentData.length
+    index = args.index !== undefined ? args.index : currentData.length
+    // splice() would silently clamp an out of bounds index, but the reported index and the
+    // item activated below would then designate an item that does not exist
+    if (!Number.isInteger(index) || index < 0 || index > currentData.length) {
+      throw new Error(`index ${index} out of bounds (array length: ${currentData.length}, an item can be added at 0 to ${currentData.length})`)
+    }
     currentData.splice(index, 0, args.value !== undefined ? args.value : undefined)
   } else if (args.action === 'remove') {
     if (currentData.length === 0) {
       throw new Error('cannot remove from an empty array')
     }
-    const index = args.index !== undefined ? args.index : currentData.length - 1
-    if (index < 0 || index >= currentData.length) {
+    index = args.index !== undefined ? args.index : currentData.length - 1
+    if (!Number.isInteger(index) || index < 0 || index >= currentData.length) {
       throw new Error(`index ${index} out of bounds (array length: ${currentData.length})`)
     }
     currentData.splice(index, 1)
@@ -89,9 +82,39 @@ export function execute (statefulLayout, args) {
 
   statefulLayout.input(node, currentData)
 
-  return {
+  // the list components only hydrate the editable children of an item when it is activated,
+  // the same activation is applied here so that the agent can fill the new item
+  const listEditMode = /** @type {Record<string, unknown>} */(node.layout).listEditMode
+  const listNodeAfterInput = resolveNode(statefulLayout.stateTree.root, args.path)
+  if (listNodeAfterInput) {
+    if (args.action === 'add' && listEditMode !== 'inline') {
+      statefulLayout.activateItem(listNodeAfterInput, index)
+    } else if (args.action === 'remove' && typeof activatedBefore === 'number' && activatedBefore !== index) {
+      // input() dropped the activation, but the item being edited is not the one that was
+      // removed: it is restored, shifted down by one when it was after the removed item, so
+      // that the agent does not silently lose the item it was filling
+      statefulLayout.activateItem(listNodeAfterInput, activatedBefore > index ? activatedBefore - 1 : activatedBefore)
+    }
+  }
+
+  const listNode = resolveNode(statefulLayout.stateTree.root, args.path) ?? node
+  const { errors, otherErrors } = collectScopedErrors(statefulLayout, listNode)
+
+  /** @type {{ valid: boolean, itemCount: number, index: number, itemMarkdown?: string, errors: Array<{path: string, message: string}>, otherErrors: number }} */
+  const result = {
     valid: statefulLayout.valid,
     itemCount: currentData.length,
-    errors: collectErrors(statefulLayout.stateTree.root)
+    index,
+    errors,
+    otherErrors
+  }
+
+  if (args.action === 'add') {
+    const itemNode = resolveNode(statefulLayout.stateTree.root, `${args.path}/${index}`)
+    if (itemNode) {
+      result.itemMarkdown = projectNodeToMarkdown(itemNode, statefulLayout, 0, undefined, variantsMemo)
+    }
   }
+
+  return result
 }

package/src/webmcp/tools/fill-form-skill.js

@@ -2,13 +2,6 @@
  * @file fillFormSkill tool
  */
 
-export const outputSchema = {
-  type: 'object',
-  properties: {
-    content: { type: 'string' }
-  }
-}
-
 /**
  * @param {string} dataTitle
  * @returns {string}
@@ -18,50 +11,33 @@ export function getDescription (dataTitle) {
 }
 
 /**
- * Generate skill content with dataTitle injected
+ * The one path. There used to be three, chosen by counting normalized layouts and calling
+ * the result small, medium or large — a threshold nobody could justify, measuring the
+ * schema when the question was about data, and duplicated between here and index.js. Four
+ * commits in a row went to fixing contradictions between those branches, and across four
+ * recorded baselines the small and medium advice was never taken on a real form: setData
+ * was used zero times and getSchema once.
  * @param {string} dataTitle
  * @param {string} prefixName
- * @param {boolean} hasSchema
- * @param {import('../../state/index.js').StatefulLayout} statefulLayout
  * @returns {string}
  */
-export function generateSkill (dataTitle, prefixName, hasSchema, statefulLayout) {
-  /** @type {"small" | "medium" | "large"} */
-  let complexity = 'small'
-  const nbNormalizedLayouts = Object.keys(statefulLayout.compiledLayout.normalizedLayouts).length
-  if (nbNormalizedLayouts > 15) complexity = 'medium'
-  if (nbNormalizedLayouts > 50) complexity = 'large'
-  let skill = `# JSON ${dataTitle.charAt(0).toUpperCase() + dataTitle.slice(1)} Form-Filling Guide
+export function generateSkill (dataTitle, prefixName) {
+  return `# JSON ${dataTitle.charAt(0).toUpperCase() + dataTitle.slice(1)} Form-Filling Guide
 
 This guide teaches you how to use tools to fill the data of a form in the user's page.
 
-Always start by getting the current data using ${prefixName}getData.
-`
+Start with ${prefixName}describeState. It lists every field with its path, its current value and anything invalid; a value too large to inline is shown as its type and size, with the path to read it. Call it again on a path whenever you need to look at one part of the form.
 
-  if (complexity === 'small') {
-    skill += `
-Given the small complexity of this form you should start by reading the full schema definition using ${prefixName}${hasSchema ? 'getSchema' : 'describeState'} and attempt updating the whole data using ${prefixName}setData.
-Only use ${prefixName}describeState and iterate with ${prefixName}setFieldValue if you encounter some difficulties with ${prefixName}setData.
-`
-  }
+Then write. If the goal already tells you every value, set them in one call with ${prefixName}setData. Otherwise change one field at a time with ${prefixName}setFieldValue, which is also what you need when a value has to be looked up first or when a field only exists once another has been set. Every write reports whether the form is valid and lists what is wrong, so you rarely need to read anything back.
 
-  if (complexity === 'medium') {
-    skill += `
-Given the medium complexity of this form you should start by reading the full schema definition using ${prefixName}${hasSchema ? 'getSchema' : 'describeState'}, if you have a satisfying understanding of the schema you can attempt updating the whole data using ${prefixName}setData at least once.
-Then use ${prefixName}describeState and iterate with ${prefixName}setFieldValue.
-`
-  }
+Never invent a value for a field that has a fixed set of accepted ones. ${prefixName}describeState tells you which case you are in: it either states them on the field's line as values=[...], and you write one of those directly, or it marks the field "suggestions", and the list exists only behind a request — then call ${prefixName}getFieldSuggestions, whose description says how to apply what it returns.
 
-  if (complexity === 'large') {
-    skill += `
-Given the large complexity of this form you should avoid reading the full schema definition using ${prefixName}${hasSchema ? 'getSchema' : 'describeState'}.
-Prefer using ${prefixName}describeState and iterating with ${prefixName}setFieldValue.
-`
-  }
+A field shown as (variant-selector) chooses between shapes rather than between values: ${prefixName}describeState lists its branches under it as "variant N: label", and you switch to one by setting the field to that number with ${prefixName}setFieldValue, which then lists the fields the branch contains.
 
-  skill += `
-If you encounter getItems definitions in the schema or "suggestions" flags in the state, you must use ${prefixName}getFieldSuggestions to fetch the accepted values, then pass the chosen value directly to ${prefixName}setFieldValue or include it in ${prefixName}setData.
-`
+To fill an array, call ${prefixName}editArray with action "add": the new item is activated for edition and the tool returns the fields it contains, then fill them one by one with ${prefixName}setFieldValue.
 
-  return skill
+${prefixName}getData returns the data document itself, whole or one part of it by path, for when you need the values rather than a description of them.
+
+The errors returned by ${prefixName}setFieldValue and ${prefixName}editArray are scoped to the node you just modified, other errors of the form are only counted.
+`
 }