@ghentcdh/crouton-core 0.0.1-alpha.83 → 0.0.1-alpha.85

package/agent-docs/1.getting-started/index.md

@@ -192,3 +192,7 @@ npx @ghentcdh/add-crouton --cwd /path/to/project
 6. **Installs dependencies** — runs `<pm> install` if missing deps were detected.
 
 After running `@ghentcdh/add-crouton`, wire `CroutonApiModule` into your NestJS app module — see [Backend setup](backend.md).
+
+## Keeping agent files current
+
+After upgrading crouton, run `crouton migrate` to update your `resource.json` files **and** refresh the Claude skill, Cursor rule, and `AGENTS.md` block to the new version. See [Migrations](../5.tooling/migrate.md#agent-files) for details.

package/agent-docs/5.tooling/migrate.md

@@ -1,10 +1,10 @@
 ---
-description: crouton migrate — automated codemod for upgrading resource.json files.
+description: crouton migrate — automated codemod for upgrading resource.json files and syncing agent files.
 ---
 
 # Migrations
 
-The `crouton migrate` command transforms `resource.json` files automatically.
+The `crouton migrate` command transforms `resource.json` files automatically and keeps your agent files (Claude skill, Cursor rule, `AGENTS.md` block) in sync with the installed crouton version.
 
 ## `crouton migrate`
 
@@ -45,6 +45,58 @@ crouton migrate --check
 
 The transform is **idempotent** — running it twice produces no further diff.
 
+### Flags
+
+| Flag | Description |
+|---|---|
+| `--dry-run` | Print a diff of what would change; do not write files. |
+| `--check` | Exit 1 if any file needs migration or agent files are out of date (useful in CI). |
+| `--no-agent-files` | Only migrate `resource.json` files; skip agent file sync. |
+| `--agent-files-only` | Only sync agent files; skip `resource.json` migration. |
+| `--targets claude,cursor` | Which agent file sets to sync (default: those already present, or both on first run). |
+| `--force` | Overwrite agent files even if they were edited locally. |
+| `[paths...]` | One or more file or directory paths to scan (default: `resourcesDir` from `crouton.json`). |
+
 ### When to run
 
 Run after upgrading `@ghentcdh/crouton-core` to a version that introduces breaking layout or schema changes. The schema validator will tell you when migration is needed.
+
+---
+
+## Agent files
+
+`crouton migrate` also keeps your AI agent files in sync with the installed crouton version. This ensures agents always write resources in the current schema shape.
+
+### What is synced
+
+| File | Description |
+|---|---|
+| `.claude/skills/crouton/SKILL.md` | Main crouton skill for Claude Code. Includes YAML frontmatter with `crouton-version`. |
+| `.claude/skills/crouton/references/*.md` | Reference files: `resource-json.md`, `relations.md`, `field-inputs.md`, `data-sources.md`, `recipes.md`, `common-mistakes.md`. |
+| `.cursor/rules/crouton.mdc` | Cursor rule equivalent. |
+| `AGENTS.md` (crouton block) | The `<!-- crouton configuration -->` block. |
+
+### Safe updates
+
+A manifest at `.crouton/agent-files.json` tracks what crouton last wrote. The update logic per file:
+
+- **File missing** → written.
+- **Hash matches manifest** (untouched since last crouton write) → overwritten with the new version.
+- **Hash differs** (you edited it) → skipped; the new version is written to `.crouton/agent-files/<name>.new` and reported. Use `--force` to overwrite.
+- **File crouton no longer ships** → deleted if untouched, reported if edited.
+
+### Project-specific notes
+
+Put project conventions in `.claude/skills/crouton/project.md`. Crouton never touches this file. The skill links to it automatically if it exists.
+
+### `crouton.json` configuration
+
+After the first run, crouton stores the chosen targets in `crouton.json`:
+
+```json
+{
+  "agentFiles": { "targets": ["claude", "cursor"] }
+}
+```
+
+Change or remove this to adjust which sets are managed.

package/dist/crouton.schema.json

@@ -913,6 +913,25 @@
         "languages"
       ],
       "markdownDescription": "Optional i18n / translation configuration. Omit if the app is single-language.\n\n[Docs](https://ghentcdh.github.io/crouton/guide/1.setup/crouton-json)"
+    },
+    "agentFiles": {
+      "description": "Agent file sync configuration for `crouton migrate`. Stored after the first run.",
+      "type": "object",
+      "properties": {
+        "targets": {
+          "description": "Which agent file sets to manage. Defaults to those already present in the project, or both on first run.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "claude",
+              "cursor"
+            ]
+          },
+          "markdownDescription": "Which agent file sets to manage. Defaults to those already present in the project, or both on first run.\n\n[Docs](https://ghentcdh.github.io/crouton/guide/1.setup/crouton-json)"
+        }
+      },
+      "markdownDescription": "Agent file sync configuration for `crouton migrate`. Stored after the first run.\n\n[Docs](https://ghentcdh.github.io/crouton/guide/1.setup/crouton-json)"
     }
   },
   "required": [

package/dist/index.cjs

@@ -4485,7 +4485,10 @@ var CroutonConfigSchema = import_zod48.z.object({
   rules: RulesetSchema.default(RulesetSchema.parse({})).describe("Optional overrides of the default visibility and behaviour ruleset applied to all resources."),
   sidebarGroups: import_zod48.z.record(import_zod48.z.string(), SidebarGroupSchema).default({}).describe('Sidebar group definitions, keyed by group slug (e.g. "metadata"). Resources reference a group via sidebar.group in their resource.json.'),
   autoSave: import_zod48.z.boolean().default(true).describe("Whether form fields are saved automatically as the user edits them. Default true."),
-  i18n: I18nConfigSchema.optional().describe("Optional i18n / translation configuration. Omit if the app is single-language.")
+  i18n: I18nConfigSchema.optional().describe("Optional i18n / translation configuration. Omit if the app is single-language."),
+  agentFiles: import_zod48.z.object({
+    targets: import_zod48.z.array(import_zod48.z.enum(["claude", "cursor"])).optional().describe("Which agent file sets to manage. Defaults to those already present in the project, or both on first run.")
+  }).optional().describe("Agent file sync configuration for `crouton migrate`. Stored after the first run.")
 });
 
 // src/lib/config/readConfig.ts