# How to configure enrichments



## When to use this [#when-to-use-this]

You want different output for specific operations (e.g., a
custom title on a specific form, or a different label for a
field on the `CreateUser` form) without modifying the generator.
If the generator's enrichment schema doesn't expose what you need,
see [tutorial: cloning a generator](/docs/authoring/tutorials/01-cloning-a-generator)
instead.

## Prerequisites [#prerequisites]

* A SKMTC project with the target generator installed (e.g.,
  `@skmtc/gen-shadcn-form`).
* Knowledge of the operation IDs (or model refNames) you want to
  customize. List them via `skmtc agent-context --json | jq
  '.projects[] | .generators'`.

## Steps [#steps]

### Locate the generator's enrichment schema [#locate-the-generators-enrichment-schema]

Each generator declares its accepted enrichment shape in
`src/enrichments.ts` as a Valibot schema. The shape is the
contract — keys outside it are silently stripped.

For stock generators, the shape is documented in the per-generator
reference (e.g., [gen-shadcn-form](/docs/reference/stock-generators/gen-shadcn-form)).

### Add enrichments to client.json [#add-enrichments-to-clientjson]

The routing keys depend on the generator's projection-base kind:

| Factory           | Key path                                                              |
| ----------------- | --------------------------------------------------------------------- |
| OAS operation     | `enrichments[generatorId][operation.path][operation.method][variant]` |
| Model             | `enrichments[generatorId][refName][variant]`                          |
| GraphQL operation | `enrichments[generatorId][rootKind][fieldName][variant]`              |

The trailing `variant` key is `"main"` by default. Write your override
under it; whenever you declare any variant for an item, `"main"` must
be one of them.

Example for `gen-shadcn-form` (OAS operation) on `POST /users`:

```jsonc
{
  "settings": {
    "enrichments": {
      "@skmtc/gen-shadcn-form": {
        "/users": {
          "post": {
            "main": {
              "title": "Create a user",
              "submitLabel": "Create",
              "fields": [
                { "moduleSelect": { "schemaPath": ["name"] }, "label": "Full name" }
              ]
            }
          }
        }
      }
    }
  }
}
```

Example for `gen-zod` (model) on `UserModel`:

```jsonc
{
  "settings": {
    "enrichments": {
      "@skmtc/gen-zod": {
        "UserModel": {
          "main": { "description": "A user account" }
        }
      }
    }
  }
}
```

See [enrichments shape reference](/docs/reference/settings/enrichments-shape)
for all three routing shapes.

### Regenerate [#regenerate]

```bash
skmtc generate <project>
```

No rebundle needed — `client.json` is runtime config.

## Verification [#verification]

Inspect the generated file for the operation you customized. The
new title/label/etc. should appear in the output. If it doesn't,
either:

* The routing keys are wrong (for OAS operations check the
  literal `path` and lowercase `method` match the OAS spec; for
  models check the refName)
* The enrichment field name doesn't match the schema (check
  the generator's `enrichments.ts`)

## Troubleshooting [#troubleshooting]

* **Enrichments silently ignored** — Most likely a key-path typo.
  Run `skmtc agent-context --json | jq '.projects[] |
  .settings.enrichmentsConfigured'` to confirm `client.json`
  parsed; then double-check the routing keys against the actual
  values: for OAS operations the keys are the literal `path` and
  lowercase `method` (not `operationId`); for models the key is
  the refName; for GraphQL operations the keys are `rootKind` and
  `fieldName`.
* **"Type mismatch in enrichments"** — A required enrichment
  field has the wrong type. Re-check the generator's
  `enrichments.ts` for the Valibot schema.
* **Unknown enrichment keys** — Unknown keys are silently
  stripped (Valibot default). If the field you want isn't in the
  generator's schema, clone the generator and add it (see
  [add enrichment options](/docs/authoring/how-to/add-enrichment-options)).

## Related [#related]

* [Enrichments concept](/docs/concepts/enrichments)
* [Enrichments shape reference](/docs/reference/settings/enrichments-shape)
* [client.json schema](/docs/reference/settings/client-json-schema)
* [Per-generator enrichment docs](/docs/reference/stock-generators)