@numericoach/gskills-admin-cli 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -20,6 +20,24 @@ Content-like resources default to `instanceId = "global"` when `--instance` is o
20
20
  Deletes require both `--force` and an exact `--confirm-delete <resource>:<id>` token.
21
21
  CLI writes are logged in the GSkills admin logs with the authenticated user and CLI metadata.
22
22
 
23
+ Sync dry-runs use the shared GSkills diff preview system:
24
+
25
+ ```bash
26
+ gskills-admin sync presets --output json
27
+ gskills-admin sync logs --target <instanceId> --take 10 --output json
28
+ gskills-admin sync diff --target <instanceId> --only pages,menus --pages <pageId,pageId> --languages fr,en --output json
29
+ gskills-admin sync diff --target <instanceId> --preset client-content --output json
30
+ gskills-admin sync run --targets <instanceId,instanceId> --only pages,quizzes --dry-run --output json
31
+ ```
32
+
33
+ Deploy cache can be invalidated at the same scopes as the super-admin content settings screen:
34
+
35
+ ```bash
36
+ gskills-admin cache scopes --output json
37
+ gskills-admin cache invalidate --instance <instanceId> --scope pages --languages fr,en --dry-run --output json
38
+ gskills-admin cache invalidate --instance <instanceId> --scope menu-bundle --yes --output json
39
+ ```
40
+
23
41
  ## Agent skill
24
42
 
25
43
  Install the bundled skill so AI agents know the auth model, resource map, output modes, sync workflow, and content-authoring standards.
@@ -340,7 +340,7 @@ var resources = [
340
340
  name: "topics",
341
341
  delegate: "category_Application",
342
342
  label: "Topics",
343
- aliases: ["topic", "applications", "category-apps", "categories"],
343
+ aliases: ["topic", "applications", "category-apps", "categories", "thematics", "thematic"],
344
344
  defaultFields: ["id", "name", "slug", "language", "instanceId", "disabled", "archived", "alphaProgramIds", "updatedAt"],
345
345
  syncable: true,
346
346
  dangerousDelete: true
@@ -380,6 +380,24 @@ var resources = [
380
380
  defaultFields: ["id", "title", "slug", "target", "status", "language", "updatedAt"],
381
381
  dangerousDelete: true
382
382
  },
383
+ {
384
+ name: "chromebook-exercises",
385
+ delegate: "chromebookExercise",
386
+ label: "Chromebook exercises",
387
+ aliases: ["chromebook", "chromebook-game", "chromebook-exercise", "chromebook-games"],
388
+ defaultFields: ["id", "title", "language", "instanceId", "type", "order", "isActive", "parentId", "sourceExerciseId", "updatedAt"],
389
+ instanceField: "instanceId",
390
+ dangerousDelete: true
391
+ },
392
+ {
393
+ name: "chromebook-steps",
394
+ delegate: "chromebookExerciseStep",
395
+ label: "Chromebook exercise steps",
396
+ aliases: ["chromebook-step", "chromebook-exercise-steps"],
397
+ defaultFields: ["id", "exerciseId", "stepNumber", "title", "language", "contentType", "order", "updatedAt"],
398
+ instanceField: null,
399
+ dangerousDelete: true
400
+ },
383
401
  {
384
402
  name: "project-data",
385
403
  delegate: "instanceProjectData",
@@ -427,6 +445,23 @@ var resources = [
427
445
  aliases: ["feedback"],
428
446
  defaultFields: ["id", "instanceId", "userId", "type", "status", "priority", "createdAt", "updatedAt"]
429
447
  },
448
+ {
449
+ name: "tags",
450
+ delegate: "tag",
451
+ label: "Tags",
452
+ aliases: ["tag"],
453
+ defaultFields: ["id", "name", "normalizedName", "color", "scope", "ownerInstanceId", "createdAt", "updatedAt"],
454
+ instanceField: "ownerInstanceId",
455
+ dangerousDelete: true
456
+ },
457
+ {
458
+ name: "tag-assignments",
459
+ delegate: "tagAssignment",
460
+ label: "Tag assignments",
461
+ aliases: ["tag-assignment"],
462
+ defaultFields: ["id", "tagId", "instanceId", "entityType", "entityId", "createdAt", "updatedAt"],
463
+ dangerousDelete: true
464
+ },
430
465
  {
431
466
  name: "menus",
432
467
  delegate: "menuItem",
@@ -466,7 +501,8 @@ var resources = [
466
501
  delegate: "user",
467
502
  label: "Users",
468
503
  aliases: ["user"],
469
- defaultFields: ["id", "email", "name", "adminState", "instanceID", "lastSeen", "updatedAt"]
504
+ defaultFields: ["id", "email", "name", "adminState", "instanceID", "lastSeen", "updatedAt"],
505
+ instanceField: "instanceID"
470
506
  },
471
507
  {
472
508
  name: "access-passes",
@@ -510,6 +546,8 @@ var runCommand = async (ctx) => {
510
546
  return resourceHelpRows();
511
547
  if (group === "sync")
512
548
  return runSyncCommand(actionOrResource, ctx);
549
+ if (group === "cache")
550
+ return runCacheCommand(actionOrResource, ctx);
513
551
  const resource = findResource(group);
514
552
  return runResourceCommand(resource, actionOrResource, maybeAction, rest, ctx);
515
553
  };
@@ -572,8 +610,9 @@ var listResource = async (resource, ctx) => {
572
610
  const searchParams = new URLSearchParams;
573
611
  const where = parseJsonObject(getStringFlag(ctx, "where"), "--where");
574
612
  const instanceId = getStringFlag(ctx, "instance") ?? defaultInstanceId(resource);
575
- if (instanceId)
576
- where.instanceId = instanceId;
613
+ const instanceField = resource.instanceField === undefined ? "instanceId" : resource.instanceField;
614
+ if (instanceId && instanceField)
615
+ where[instanceField] = instanceId;
577
616
  searchParams.set("where", JSON.stringify(where));
578
617
  searchParams.set("fields", getFields(resource, ctx).join(","));
579
618
  searchParams.set("take", String(getNumberFlag(ctx, "take") ?? 25));
@@ -581,13 +620,25 @@ var listResource = async (resource, ctx) => {
581
620
  const orderBy = getStringFlag(ctx, "order-by");
582
621
  if (orderBy)
583
622
  searchParams.set("orderBy", orderBy);
623
+ if (hasFlag(ctx, "dry-run")) {
624
+ return {
625
+ dryRun: true,
626
+ resource: resource.name,
627
+ where,
628
+ fields: getFields(resource, ctx),
629
+ take: getNumberFlag(ctx, "take") ?? 25,
630
+ skip: getNumberFlag(ctx, "skip") ?? 0,
631
+ orderBy: orderBy ? parseJsonObject(orderBy, "--order-by") : {}
632
+ };
633
+ }
584
634
  return requestApi(`/api/cli/${resource.name}?${searchParams.toString()}`);
585
635
  };
586
636
  var createResource = async (resource, ctx) => {
587
637
  const data = parseJsonObject(getStringFlag(ctx, "data"), "--data");
588
638
  const instanceId = getStringFlag(ctx, "instance") ?? defaultInstanceId(resource);
589
- if (instanceId && data.instanceId === undefined)
590
- data.instanceId = instanceId;
639
+ const instanceField = resource.instanceField === undefined ? "instanceId" : resource.instanceField;
640
+ if (instanceId && instanceField && data[instanceField] === undefined)
641
+ data[instanceField] = instanceId;
591
642
  if (Object.keys(data).length === 0)
592
643
  throw new CliError("Missing --data JSON", 2);
593
644
  if (hasFlag(ctx, "dry-run"))
@@ -647,25 +698,117 @@ var deleteResource = async (resource, id, ctx) => {
647
698
  var runSyncCommand = async (action, ctx) => {
648
699
  if (!action || action === "help")
649
700
  return syncHelp();
650
- if (action !== "run")
701
+ if (action === "presets")
702
+ return syncPresets();
703
+ if (action === "logs")
704
+ return syncLogs(ctx);
705
+ if (action !== "run" && action !== "diff")
651
706
  throw new CliError(`Unknown sync command "${action}"`, 2);
652
- const targetInstanceId = getStringFlag(ctx, "target");
653
- if (!targetInstanceId)
654
- throw new CliError("Missing --target", 2);
655
- if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
656
- throw new CliError("Sync writes DB data. Add --yes or use --dry-run.", 2);
707
+ const targetInstanceIds = getTargetInstanceIds(ctx);
708
+ if (targetInstanceIds.length === 0)
709
+ throw new CliError("Missing --target or --targets", 2);
710
+ if (action === "run" && !hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
711
+ throw new CliError("Sync writes DB data. Add --yes, use --dry-run, or use sync diff.", 2);
657
712
  }
658
- const payload = {
713
+ const basePayload = {
659
714
  sourceInstanceId: getStringFlag(ctx, "source") ?? "global",
660
- targetInstanceId,
661
- options: buildSyncOptions(ctx),
715
+ options: buildSyncOptions(ctx)
716
+ };
717
+ const endpoint = action === "diff" || hasFlag(ctx, "dry-run") ? "/api/cli/sync/diff" : "/api/cli/sync/run";
718
+ const runForTarget = (targetInstanceId) => requestApi(endpoint, {
719
+ method: "POST",
720
+ body: JSON.stringify({
721
+ ...basePayload,
722
+ targetInstanceId,
723
+ dryRun: action === "diff" || hasFlag(ctx, "dry-run")
724
+ })
725
+ });
726
+ if (targetInstanceIds.length === 1)
727
+ return runForTarget(targetInstanceIds[0]);
728
+ const results = [];
729
+ for (const targetInstanceId of targetInstanceIds) {
730
+ results.push({
731
+ targetInstanceId,
732
+ result: await runForTarget(targetInstanceId)
733
+ });
734
+ }
735
+ return { targets: results };
736
+ };
737
+ var runCacheCommand = async (action, ctx) => {
738
+ if (!action || action === "help")
739
+ return cacheHelp();
740
+ if (action === "scopes")
741
+ return requestApi("/api/cli/cache/scopes");
742
+ if (action !== "invalidate")
743
+ throw new CliError(`Unknown cache command "${action}"`, 2);
744
+ const instanceId = getStringFlag(ctx, "instance") ?? getStringFlag(ctx, "target");
745
+ if (!instanceId)
746
+ throw new CliError("Missing --instance", 2);
747
+ const scope = getStringFlag(ctx, "scope") ?? "all";
748
+ const languages = splitCsv(getStringFlag(ctx, "languages"));
749
+ const payload = {
750
+ instanceId,
751
+ scope,
752
+ languages,
662
753
  dryRun: hasFlag(ctx, "dry-run")
663
754
  };
664
- return requestApi("/api/cli/sync/run", {
755
+ if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
756
+ throw new CliError("Cache invalidation writes deploy-cache versions. Add --yes or use --dry-run.", 2, payload);
757
+ }
758
+ return requestApi("/api/cli/cache/invalidate", {
665
759
  method: "POST",
666
760
  body: JSON.stringify(payload)
667
761
  });
668
762
  };
763
+ var syncLogs = (ctx) => {
764
+ const searchParams = new URLSearchParams;
765
+ const targetInstanceId = getStringFlag(ctx, "target") ?? getStringFlag(ctx, "instance");
766
+ const sourceInstanceId = getStringFlag(ctx, "source");
767
+ const status = getStringFlag(ctx, "status");
768
+ if (targetInstanceId)
769
+ searchParams.set("targetInstanceId", targetInstanceId);
770
+ if (sourceInstanceId)
771
+ searchParams.set("sourceInstanceId", sourceInstanceId);
772
+ if (status)
773
+ searchParams.set("status", status);
774
+ searchParams.set("take", String(getNumberFlag(ctx, "take") ?? 10));
775
+ return requestApi(`/api/cli/sync/logs?${searchParams.toString()}`);
776
+ };
777
+ var syncPresets = () => ({
778
+ note: "Presets from common super-admin sync runs. Always run sync diff before sync run --yes.",
779
+ presets: [
780
+ {
781
+ name: "full-content",
782
+ description: "Same broad content push as the global synchro-content screen.",
783
+ command: "gskills-admin sync diff --target <instanceId> --preset full-content",
784
+ only: ["languages", "categories", "pages", "menus", "quizzes", "learningPaths", "knowledge", "resources", "badges", "workflows"]
785
+ },
786
+ {
787
+ name: "client-content",
788
+ description: "Most common client content shape in recent Marina-correlated runs.",
789
+ command: "gskills-admin sync diff --target <instanceId> --preset client-content",
790
+ only: ["categories", "pages", "menus", "quizzes", "learningPaths", "resources", "badges"]
791
+ },
792
+ {
793
+ name: "pages-learning-paths",
794
+ description: "Common refinement pass after a broader run.",
795
+ command: "gskills-admin sync diff --target <instanceId> --preset pages-learning-paths",
796
+ only: ["pages", "learningPaths"]
797
+ },
798
+ {
799
+ name: "pages-only",
800
+ description: "Use for syncing-pages style checks or page-only corrections.",
801
+ command: "gskills-admin sync diff --target <instanceId> --preset pages-only --pages <pageId,pageId>",
802
+ only: ["pages"]
803
+ },
804
+ {
805
+ name: "knowledge-resources-paths",
806
+ description: "Useful when content assets or learning paths need a narrow rerun.",
807
+ command: "gskills-admin sync diff --target <instanceId> --preset knowledge-resources-paths",
808
+ only: ["knowledge", "resources", "learningPaths"]
809
+ }
810
+ ]
811
+ });
669
812
  var runSkillsCommand = async (action, ctx) => {
670
813
  if (!action || action === "help")
671
814
  return skillsHelp();
@@ -682,6 +825,11 @@ var runSkillsCommand = async (action, ctx) => {
682
825
  };
683
826
  var buildSyncOptions = (ctx) => {
684
827
  const only = new Set(splitCsv(getStringFlag(ctx, "only")));
828
+ const preset = getStringFlag(ctx, "preset");
829
+ if (preset) {
830
+ for (const item of syncPresetItems(preset))
831
+ only.add(item);
832
+ }
685
833
  const hasOnly = only.size > 0;
686
834
  const enabled = (key) => !hasOnly || only.has(key);
687
835
  return {
@@ -714,6 +862,32 @@ var buildSyncOptions = (ctx) => {
714
862
  collectSummary: true
715
863
  };
716
864
  };
865
+ var syncPresetItems = (preset) => {
866
+ switch (preset) {
867
+ case "full-content":
868
+ return ["languages", "categories", "pages", "menus", "quizzes", "learningPaths", "knowledge", "resources", "badges", "workflows"];
869
+ case "client-content":
870
+ return ["categories", "pages", "menus", "quizzes", "learningPaths", "resources", "badges"];
871
+ case "pages-learning-paths":
872
+ return ["pages", "learningPaths"];
873
+ case "pages-only":
874
+ return ["pages"];
875
+ case "knowledge-resources-paths":
876
+ return ["knowledge", "resources", "learningPaths"];
877
+ default:
878
+ throw new CliError(`Unknown sync preset "${preset}"`, 2, {
879
+ available: ["full-content", "client-content", "pages-learning-paths", "pages-only", "knowledge-resources-paths"]
880
+ });
881
+ }
882
+ };
883
+ var getTargetInstanceIds = (ctx) => {
884
+ const explicitTargets = splitCsv(getStringFlag(ctx, "targets"));
885
+ const target = getStringFlag(ctx, "target");
886
+ return Array.from(new Set([
887
+ ...explicitTargets,
888
+ ...target ? [target] : []
889
+ ]));
890
+ };
717
891
  var getFields = (resource, ctx) => splitCsv(getStringFlag(ctx, "fields")).length > 0 ? splitCsv(getStringFlag(ctx, "fields")) : resource.defaultFields;
718
892
  var splitCsv = (value) => value ? value.split(",").map((item) => item.trim()).filter(Boolean) : [];
719
893
  var GLOBAL_DEFAULT_RESOURCES = new Set([
@@ -726,7 +900,8 @@ var GLOBAL_DEFAULT_RESOURCES = new Set([
726
900
  "badges",
727
901
  "menus",
728
902
  "menu-sections",
729
- "workflows"
903
+ "workflows",
904
+ "chromebook-exercises"
730
905
  ]);
731
906
  var defaultInstanceId = (resource) => GLOBAL_DEFAULT_RESOURCES.has(resource.name) ? "global" : undefined;
732
907
  var skillsSourceDir = async () => {
@@ -798,9 +973,14 @@ var schemaHelp = () => ({
798
973
  { name: "resources", writes: false },
799
974
  { name: "schema", writes: false },
800
975
  { name: "skills install", flags: ["--target"], writes: true },
801
- { name: "sync run", required: ["--target"], safety: ["--yes or --dry-run"], writes: true },
976
+ { name: "sync diff", required: ["--target or --targets"], writes: false },
977
+ { name: "sync run", required: ["--target or --targets"], safety: ["--yes or --dry-run"], writes: true },
978
+ { name: "sync logs", flags: ["--target", "--source", "--status", "--take"], writes: false },
979
+ { name: "sync presets", writes: false },
980
+ { name: "cache scopes", writes: false },
981
+ { name: "cache invalidate", required: ["--instance"], flags: ["--scope", "--languages", "--yes", "--dry-run"], writes: true },
802
982
  ...resources.flatMap((resource) => [
803
- { name: `${resource.name} list`, writes: false, flags: ["--where", "--fields", "--take", "--skip", "--order-by", "--instance"] },
983
+ { name: `${resource.name} list`, writes: false, flags: ["--where", "--fields", "--take", "--skip", "--order-by", "--instance", "--dry-run"] },
804
984
  { name: `${resource.name} get`, args: ["id"], writes: false },
805
985
  { name: `${resource.name} create`, flags: ["--data", "--instance", "--dry-run"], writes: true },
806
986
  { name: `${resource.name} update`, args: ["id"], flags: ["--data", "--dry-run"], writes: true },
@@ -833,12 +1013,29 @@ var skillsHelp = () => ({
833
1013
  });
834
1014
  var syncHelp = () => ({
835
1015
  usage: [
1016
+ "gskills-admin sync diff --target <instanceId> --only pages,menus --pages <id,id> --languages fr,en",
1017
+ "gskills-admin sync diff --target <instanceId> --preset client-content",
1018
+ "gskills-admin sync logs --target <instanceId> --take 10",
1019
+ "gskills-admin sync presets",
836
1020
  "gskills-admin sync run --target <instanceId> --yes",
1021
+ "gskills-admin sync run --targets <id,id> --only pages,quizzes --dry-run",
837
1022
  "gskills-admin sync run --target <instanceId> --only pages,quizzes,learningPaths --pages <id,id> --languages fr,en --yes",
838
1023
  "gskills-admin sync run --target <instanceId> --dry-run"
839
1024
  ],
840
1025
  syncable: resources.filter((resource) => resource.syncable).map((resource) => resource.name),
841
- sourceDefault: "global"
1026
+ presets: ["full-content", "client-content", "pages-learning-paths", "pages-only", "knowledge-resources-paths"],
1027
+ sourceDefault: "global",
1028
+ dryRun: "Uses the shared sync diff preview system without writing DB data."
1029
+ });
1030
+ var cacheHelp = () => ({
1031
+ usage: [
1032
+ "gskills-admin cache scopes",
1033
+ "gskills-admin cache invalidate --instance <instanceId> --scope pages --languages fr,en --dry-run",
1034
+ "gskills-admin cache invalidate --instance <instanceId> --scope menu-bundle --yes",
1035
+ "gskills-admin cache invalidate --instance <instanceId> --scope all --yes"
1036
+ ],
1037
+ scopes: ["all", "pages", "pages-knowledge", "menu-bundle", "applications"],
1038
+ note: "Uses the same deploy-cache version bump system as the super-admin content settings screen."
842
1039
  });
843
1040
  var resourceHelp = (resource) => ({
844
1041
  resource: resource.name,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@numericoach/gskills-admin-cli",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Admin-only CLI for GSkills super-admin operations.",
@@ -145,11 +145,134 @@ Use selectors for narrow syncs:
145
145
  gskills-admin sync run --target <instanceId> --pages <pageId,pageId> --languages fr,en --dry-run --output json
146
146
  ```
147
147
 
148
+ Use `sync diff` before a real run when the user wants to inspect what would change. It uses the same shared diff-preview system as the super-admin sync UI.
149
+
150
+ ```bash
151
+ gskills-admin sync presets --output json
152
+ gskills-admin sync logs --target <instanceId> --take 10 --output json
153
+ gskills-admin sync diff --target <instanceId> --only pages,menus --pages <pageId,pageId> --languages fr,en --output json
154
+ gskills-admin sync diff --target <instanceId> --preset client-content --output json
155
+ gskills-admin sync run --targets <instanceId,instanceId> --only pages,quizzes --dry-run --output json
156
+ ```
157
+
158
+ Common presets:
159
+
160
+ - `client-content`: categories, pages, menus, quizzes, learning paths, resources, badges. This matches the most common Marina-correlated client sync shape.
161
+ - `full-content`: broad global content push including languages, knowledge, and workflows.
162
+ - `pages-only`: page-only correction or syncing-pages style checks.
163
+ - `pages-learning-paths`: refinement pass after broad syncs.
164
+ - `knowledge-resources-paths`: narrow asset and learning path rerun.
165
+
166
+ ## Marina Sync Playbook
167
+
168
+ This section is based on prod admin logs and sync runs checked on 2026-05-13 for the period 2026-03-13 to 2026-05-13.
169
+
170
+ Important evidence note: old `SyncRun` rows do not store the user who clicked run. Marina attribution here comes from her admin visit logs near sync runs on the same target instance. Treat close matches as strong operational evidence, but not a hard audit identity. New CLI `sync run` operations are logged with `slug = "cli.sync.run"`, `entityType = "sync"`, `entityId = runId`, and metadata containing `actorType = "cli"`, `agent`, source, target, options, and summary totals.
171
+
172
+ Marina's current pattern:
173
+
174
+ - She mostly uses `/super-admin/<instance>/synchro-content`.
175
+ - In the last two months, Marina had 33 sync-related visits, 31 on `synchro-content` and 2 on `syncing-pages`.
176
+ - She often checks the global sync page first, then one or more target instances.
177
+ - Frequent targets were Air Liquide, V&B, HASAP, Actual, Seine Yonne, plus one-off onboarding or update pushes for Divonne, LGCF, FM Logistic, Terega, AS de Pic, Nickel Banque, 360 Courtage, Euromaster.
178
+ - The common broad client run shape is categories, pages, menus, quizzes, learning paths, resources, and badges.
179
+ - A broader full-content shape appears often too, adding internal knowledge.
180
+ - Refinement runs after a broad pass are usually pages-only or pages plus learning paths.
181
+ - Air Liquide is the heavy target. Expect thousands of items and many `SKIPPED_CUSTOMIZED` entries, so always inspect diff and summary before applying.
182
+
183
+ Direct examples from recent logs:
184
+
185
+ - 2026-04-10, Air Liquide: Marina visited the Air Liquide sync page and a run started 5 minutes earlier. Shape was full-content with 5,545 sync items: 3,087 pages, 701 quizzes, 477 categories, 836 badges, 248 learning paths, 67 knowledge items, 71 resources, menus. Most were skipped identical, with 585 skipped customized and 27 updates.
186
+ - 2026-04-09, Air Liquide: repeated full-content attempts around the same sync session, including failed broad runs, then a completed full-content run, then page-only runs with around 2,918 page items. For CLI agents, this means do not retry blindly. Use `sync logs`, inspect failures, run `sync diff`, then narrow the next run if the broad run already mostly applied.
187
+ - 2026-04-27, HASAP: two very close `synchro-content` visits matched narrow client-content style runs. One had 208 items with categories, pages, quizzes, menu, resources, badges, learning paths. Another had 200 items with very few pages and knowledge. This is a good model for targeted client maintenance after content changes.
188
+ - 2026-04-14, Euromaster: Marina used `syncing-pages`; nearby runs were page-only and pages plus learning paths. Use `pages-learning-paths` for this pattern, not a full sync.
189
+ - 2026-04-14, LGCF: a broad run was followed by page-only and pages plus learning paths passes. This is common after a content batch needs correction.
190
+ - 2026-04-15, Commune de Divonne-les-Bains: a new target push created most of the content, 647 created out of 723 items. For new client onboarding, expect high created counts and run the broad `client-content` diff first.
191
+ - 2026-04-03, AS de Pic and 2026-03-27, 360 Courtage: new-client style pushes created nearly everything. These are not casual maintenance runs. Use diff, then `client-content`, then verify menus and deploy cache.
192
+
193
+ When the user says content was created this week and asks to push it to a client:
194
+
195
+ 1. Resolve the target instance id.
196
+
197
+ ```bash
198
+ gskills-admin instances list --where '{"name":{"contains":"Air Liquide","mode":"insensitive"}}' --fields id,name,URL --output json
199
+ ```
200
+
201
+ 2. Look at recent sync history before touching anything.
202
+
203
+ ```bash
204
+ gskills-admin sync logs --target cmfwilgzb000404kzmfrkuifm --take 10 --output json
205
+ ```
206
+
207
+ 3. Start with the Marina-style diff.
208
+
209
+ ```bash
210
+ gskills-admin sync diff --target cmfwilgzb000404kzmfrkuifm --preset client-content --output json
211
+ ```
212
+
213
+ 4. If the new content includes internal knowledge or workflows, use full content.
214
+
215
+ ```bash
216
+ gskills-admin sync diff --target cmfwilgzb000404kzmfrkuifm --preset full-content --output json
217
+ ```
218
+
219
+ 5. If the diff is only pages or only a page family, narrow it.
220
+
221
+ ```bash
222
+ gskills-admin sync diff --target cmfwilgzb000404kzmfrkuifm --preset pages-only --pages <pageId,pageId> --output json
223
+ gskills-admin sync run --target cmfwilgzb000404kzmfrkuifm --preset pages-only --pages <pageId,pageId> --yes --output json
224
+ ```
225
+
226
+ 6. If the diff looks like a normal broad content push, run the same preset you diffed.
227
+
228
+ ```bash
229
+ gskills-admin sync run --target cmfwilgzb000404kzmfrkuifm --preset client-content --yes --output json
230
+ ```
231
+
232
+ 7. After the run, check logs and reset only the needed deploy cache scope.
233
+
234
+ ```bash
235
+ gskills-admin sync logs --target cmfwilgzb000404kzmfrkuifm --take 3 --output json
236
+ gskills-admin cache invalidate --instance cmfwilgzb000404kzmfrkuifm --scope pages --dry-run --output json
237
+ gskills-admin cache invalidate --instance cmfwilgzb000404kzmfrkuifm --scope pages --yes --output json
238
+ ```
239
+
240
+ For Air Liquide specifically, expect large diffs and customized skips. Do not treat `SKIPPED_CUSTOMIZED` as an error. It usually means the client instance deliberately diverged after a previous sync.
241
+
242
+ Preset choice from Marina patterns:
243
+
244
+ - Use `client-content` for normal client content pushes.
245
+ - Use `full-content` when the request mentions internal knowledge, workflows, language setup, or a broad global refresh.
246
+ - Use `pages-only` when she would have used `syncing-pages`, or when only page content changed.
247
+ - Use `pages-learning-paths` when pages are part of learning paths, especially after a broad sync.
248
+ - Use `knowledge-resources-paths` when assets, internal knowledge, webinars, or learning path references changed without normal page content.
249
+
250
+ ## Cache
251
+
252
+ Use the CLI cache commands when the user asks to reset deploy content cache. These commands use the same deploy-cache scopes as the super-admin instance settings content tab.
253
+
254
+ ```bash
255
+ gskills-admin cache scopes --output json
256
+ gskills-admin cache invalidate --instance <instanceId> --scope pages --languages fr,en --dry-run --output json
257
+ gskills-admin cache invalidate --instance <instanceId> --scope menu-bundle --yes --output json
258
+ gskills-admin cache invalidate --instance <instanceId> --scope all --yes --output json
259
+ ```
260
+
261
+ Prefer the narrowest scope:
262
+
263
+ - `pages`
264
+ - `pages-knowledge`
265
+ - `menu-bundle`
266
+ - `applications`
267
+ - `all`
268
+
148
269
  ## Safety
149
270
 
150
271
  - Prefer `list` and `get` before writes
151
272
  - Use `--dry-run` before create, update, delete, and sync
152
273
  - Use `--force --confirm-delete <resource>:<id>` only for deletes the user explicitly requested
274
+ - Use `sync diff` before `sync run --yes`
275
+ - Use cache `--dry-run` before cache `--yes`
153
276
  - Re-read changed rows after writes
154
277
  - Keep output structured so another agent can parse it
155
278
  - If production behavior matters, separate code state, deploy state, and data state