@numericoach/gskills-admin-cli 0.1.0 → 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
@@ -17,6 +17,26 @@ bun run gskills-admin sync run --target <instanceId> --only pages,quizzes --yes
17
17
  ```
18
18
 
19
19
  Content-like resources default to `instanceId = "global"` when `--instance` is omitted.
20
+ Deletes require both `--force` and an exact `--confirm-delete <resource>:<id>` token.
21
+ CLI writes are logged in the GSkills admin logs with the authenticated user and CLI metadata.
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
+ ```
20
40
 
21
41
  ## Agent skill
22
42
 
@@ -296,12 +296,23 @@ var openUrl = async (url) => {
296
296
  };
297
297
 
298
298
  // ../../src/cli/api-client.ts
299
+ var detectAgent = () => {
300
+ if (process.env.GSKILLS_CLI_AGENT)
301
+ return process.env.GSKILLS_CLI_AGENT;
302
+ if (process.env.CODEX_CI || process.env.CODEX_SHELL || process.env.CODEX_THREAD_ID)
303
+ return "codex";
304
+ if (process.env.CI)
305
+ return "ci";
306
+ return "manual";
307
+ };
299
308
  var requestApi = async (path, init = {}) => {
300
309
  const session = await getApiSession();
301
310
  const response = await fetch(new URL(path, session.baseUrl), {
302
311
  ...init,
303
312
  headers: {
304
313
  accept: "application/json",
314
+ "x-gskills-cli-client": "gskills-admin-cli",
315
+ "x-gskills-cli-agent": detectAgent(),
305
316
  ...init.body ? { "content-type": "application/json" } : {},
306
317
  ...init.headers ?? {},
307
318
  authorization: `Bearer ${session.token}`
@@ -329,7 +340,7 @@ var resources = [
329
340
  name: "topics",
330
341
  delegate: "category_Application",
331
342
  label: "Topics",
332
- aliases: ["topic", "applications", "category-apps", "categories"],
343
+ aliases: ["topic", "applications", "category-apps", "categories", "thematics", "thematic"],
333
344
  defaultFields: ["id", "name", "slug", "language", "instanceId", "disabled", "archived", "alphaProgramIds", "updatedAt"],
334
345
  syncable: true,
335
346
  dangerousDelete: true
@@ -369,6 +380,24 @@ var resources = [
369
380
  defaultFields: ["id", "title", "slug", "target", "status", "language", "updatedAt"],
370
381
  dangerousDelete: true
371
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
+ },
372
401
  {
373
402
  name: "project-data",
374
403
  delegate: "instanceProjectData",
@@ -416,6 +445,23 @@ var resources = [
416
445
  aliases: ["feedback"],
417
446
  defaultFields: ["id", "instanceId", "userId", "type", "status", "priority", "createdAt", "updatedAt"]
418
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
+ },
419
465
  {
420
466
  name: "menus",
421
467
  delegate: "menuItem",
@@ -455,7 +501,8 @@ var resources = [
455
501
  delegate: "user",
456
502
  label: "Users",
457
503
  aliases: ["user"],
458
- defaultFields: ["id", "email", "name", "adminState", "instanceID", "lastSeen", "updatedAt"]
504
+ defaultFields: ["id", "email", "name", "adminState", "instanceID", "lastSeen", "updatedAt"],
505
+ instanceField: "instanceID"
459
506
  },
460
507
  {
461
508
  name: "access-passes",
@@ -499,6 +546,8 @@ var runCommand = async (ctx) => {
499
546
  return resourceHelpRows();
500
547
  if (group === "sync")
501
548
  return runSyncCommand(actionOrResource, ctx);
549
+ if (group === "cache")
550
+ return runCacheCommand(actionOrResource, ctx);
502
551
  const resource = findResource(group);
503
552
  return runResourceCommand(resource, actionOrResource, maybeAction, rest, ctx);
504
553
  };
@@ -561,8 +610,9 @@ var listResource = async (resource, ctx) => {
561
610
  const searchParams = new URLSearchParams;
562
611
  const where = parseJsonObject(getStringFlag(ctx, "where"), "--where");
563
612
  const instanceId = getStringFlag(ctx, "instance") ?? defaultInstanceId(resource);
564
- if (instanceId)
565
- where.instanceId = instanceId;
613
+ const instanceField = resource.instanceField === undefined ? "instanceId" : resource.instanceField;
614
+ if (instanceId && instanceField)
615
+ where[instanceField] = instanceId;
566
616
  searchParams.set("where", JSON.stringify(where));
567
617
  searchParams.set("fields", getFields(resource, ctx).join(","));
568
618
  searchParams.set("take", String(getNumberFlag(ctx, "take") ?? 25));
@@ -570,13 +620,25 @@ var listResource = async (resource, ctx) => {
570
620
  const orderBy = getStringFlag(ctx, "order-by");
571
621
  if (orderBy)
572
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
+ }
573
634
  return requestApi(`/api/cli/${resource.name}?${searchParams.toString()}`);
574
635
  };
575
636
  var createResource = async (resource, ctx) => {
576
637
  const data = parseJsonObject(getStringFlag(ctx, "data"), "--data");
577
638
  const instanceId = getStringFlag(ctx, "instance") ?? defaultInstanceId(resource);
578
- if (instanceId && data.instanceId === undefined)
579
- data.instanceId = instanceId;
639
+ const instanceField = resource.instanceField === undefined ? "instanceId" : resource.instanceField;
640
+ if (instanceId && instanceField && data[instanceField] === undefined)
641
+ data[instanceField] = instanceId;
580
642
  if (Object.keys(data).length === 0)
581
643
  throw new CliError("Missing --data JSON", 2);
582
644
  if (hasFlag(ctx, "dry-run"))
@@ -598,35 +660,155 @@ var updateResource = async (resource, id, ctx) => {
598
660
  });
599
661
  };
600
662
  var deleteResource = async (resource, id, ctx) => {
663
+ const expectedConfirmation = `${resource.name}:${id}`;
601
664
  if (!hasFlag(ctx, "force")) {
602
- throw new CliError("Delete requires --force", 2, { id, resource: resource.name });
665
+ throw new CliError("Delete requires --force", 2, {
666
+ id,
667
+ resource: resource.name,
668
+ warning: "This permanently deletes production data.",
669
+ requiredConfirmation: expectedConfirmation
670
+ });
603
671
  }
604
- if (hasFlag(ctx, "dry-run"))
605
- return { dryRun: true, resource: resource.name, id, action: "delete" };
606
- return requestApi(`/api/cli/${resource.name}/${id}`, { method: "DELETE" });
672
+ if (getStringFlag(ctx, "confirm-delete") !== expectedConfirmation) {
673
+ throw new CliError(`Delete requires --confirm-delete ${expectedConfirmation}`, 2, {
674
+ id,
675
+ resource: resource.name,
676
+ warning: "This permanently deletes production data.",
677
+ requiredConfirmation: expectedConfirmation,
678
+ usage: `gskills-admin ${resource.name} delete ${id} --force --confirm-delete ${expectedConfirmation}`
679
+ });
680
+ }
681
+ if (hasFlag(ctx, "dry-run")) {
682
+ return {
683
+ dryRun: true,
684
+ resource: resource.name,
685
+ id,
686
+ action: "delete",
687
+ confirmed: true,
688
+ warning: "This permanently deletes production data."
689
+ };
690
+ }
691
+ return requestApi(`/api/cli/${resource.name}/${id}`, {
692
+ method: "DELETE",
693
+ body: JSON.stringify({
694
+ confirmation: expectedConfirmation
695
+ })
696
+ });
607
697
  };
608
698
  var runSyncCommand = async (action, ctx) => {
609
699
  if (!action || action === "help")
610
700
  return syncHelp();
611
- if (action !== "run")
701
+ if (action === "presets")
702
+ return syncPresets();
703
+ if (action === "logs")
704
+ return syncLogs(ctx);
705
+ if (action !== "run" && action !== "diff")
612
706
  throw new CliError(`Unknown sync command "${action}"`, 2);
613
- const targetInstanceId = getStringFlag(ctx, "target");
614
- if (!targetInstanceId)
615
- throw new CliError("Missing --target", 2);
616
- if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
617
- 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);
618
712
  }
619
- const payload = {
713
+ const basePayload = {
620
714
  sourceInstanceId: getStringFlag(ctx, "source") ?? "global",
621
- targetInstanceId,
622
- 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,
623
753
  dryRun: hasFlag(ctx, "dry-run")
624
754
  };
625
- 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", {
626
759
  method: "POST",
627
760
  body: JSON.stringify(payload)
628
761
  });
629
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
+ });
630
812
  var runSkillsCommand = async (action, ctx) => {
631
813
  if (!action || action === "help")
632
814
  return skillsHelp();
@@ -643,6 +825,11 @@ var runSkillsCommand = async (action, ctx) => {
643
825
  };
644
826
  var buildSyncOptions = (ctx) => {
645
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
+ }
646
833
  const hasOnly = only.size > 0;
647
834
  const enabled = (key) => !hasOnly || only.has(key);
648
835
  return {
@@ -675,6 +862,32 @@ var buildSyncOptions = (ctx) => {
675
862
  collectSummary: true
676
863
  };
677
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
+ };
678
891
  var getFields = (resource, ctx) => splitCsv(getStringFlag(ctx, "fields")).length > 0 ? splitCsv(getStringFlag(ctx, "fields")) : resource.defaultFields;
679
892
  var splitCsv = (value) => value ? value.split(",").map((item) => item.trim()).filter(Boolean) : [];
680
893
  var GLOBAL_DEFAULT_RESOURCES = new Set([
@@ -687,7 +900,8 @@ var GLOBAL_DEFAULT_RESOURCES = new Set([
687
900
  "badges",
688
901
  "menus",
689
902
  "menu-sections",
690
- "workflows"
903
+ "workflows",
904
+ "chromebook-exercises"
691
905
  ]);
692
906
  var defaultInstanceId = (resource) => GLOBAL_DEFAULT_RESOURCES.has(resource.name) ? "global" : undefined;
693
907
  var skillsSourceDir = async () => {
@@ -759,13 +973,18 @@ var schemaHelp = () => ({
759
973
  { name: "resources", writes: false },
760
974
  { name: "schema", writes: false },
761
975
  { name: "skills install", flags: ["--target"], writes: true },
762
- { 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 },
763
982
  ...resources.flatMap((resource) => [
764
- { 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"] },
765
984
  { name: `${resource.name} get`, args: ["id"], writes: false },
766
985
  { name: `${resource.name} create`, flags: ["--data", "--instance", "--dry-run"], writes: true },
767
986
  { name: `${resource.name} update`, args: ["id"], flags: ["--data", "--dry-run"], writes: true },
768
- { name: `${resource.name} delete`, args: ["id"], flags: ["--force", "--dry-run"], writes: true, destructive: true }
987
+ { name: `${resource.name} delete`, args: ["id"], flags: ["--force", "--confirm-delete", "--dry-run"], writes: true, destructive: true }
769
988
  ])
770
989
  ],
771
990
  resources: resources.map((resource) => ({
@@ -794,12 +1013,29 @@ var skillsHelp = () => ({
794
1013
  });
795
1014
  var syncHelp = () => ({
796
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",
797
1020
  "gskills-admin sync run --target <instanceId> --yes",
1021
+ "gskills-admin sync run --targets <id,id> --only pages,quizzes --dry-run",
798
1022
  "gskills-admin sync run --target <instanceId> --only pages,quizzes,learningPaths --pages <id,id> --languages fr,en --yes",
799
1023
  "gskills-admin sync run --target <instanceId> --dry-run"
800
1024
  ],
801
1025
  syncable: resources.filter((resource) => resource.syncable).map((resource) => resource.name),
802
- 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."
803
1039
  });
804
1040
  var resourceHelp = (resource) => ({
805
1041
  resource: resource.name,
@@ -810,9 +1046,10 @@ var resourceHelp = (resource) => ({
810
1046
  `gskills-admin ${resource.name} get <id>`,
811
1047
  `gskills-admin ${resource.name} create --data '{"instanceId":"global"}'`,
812
1048
  `gskills-admin ${resource.name} update <id> --data '{"disabled":true}'`,
813
- `gskills-admin ${resource.name} delete <id> --force`
1049
+ `gskills-admin ${resource.name} delete <id> --force --confirm-delete ${resource.name}:<id>`
814
1050
  ],
815
- defaultFields: resource.defaultFields
1051
+ defaultFields: resource.defaultFields,
1052
+ deleteWarning: "Delete permanently removes production data and requires an exact --confirm-delete token."
816
1053
  });
817
1054
 
818
1055
  // ../../src/cli/gskills-admin.ts
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@numericoach/gskills-admin-cli",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Admin-only CLI for GSkills super-admin operations.",
@@ -54,6 +54,17 @@ gskills-admin pages update <id> --data '{"disabled":false}' --dry-run --output j
54
54
 
55
55
  5. Apply the exact same command without `--dry-run` only after the payload is correct.
56
56
 
57
+ Deletes are stricter than other writes. They require both `--force` and an exact confirmation token.
58
+
59
+ ```bash
60
+ gskills-admin pages delete <id> --force --confirm-delete pages:<id> --dry-run --output json
61
+ gskills-admin pages delete <id> --force --confirm-delete pages:<id> --output json
62
+ ```
63
+
64
+ Never add `--confirm-delete` unless the user explicitly asked for a permanent deletion and the target row was read first.
65
+
66
+ CLI create, update, and delete operations are written to the GSkills admin logs with the authenticated user, entity snapshots, and CLI metadata. When Codex runs the CLI, the log metadata includes `actorType = "cli"` and `agent = "codex"`.
67
+
57
68
  ## Instance Rules
58
69
 
59
70
  If `--instance` is omitted, content-like resources default to `instanceId = "global"`.
@@ -134,11 +145,134 @@ Use selectors for narrow syncs:
134
145
  gskills-admin sync run --target <instanceId> --pages <pageId,pageId> --languages fr,en --dry-run --output json
135
146
  ```
136
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
+
137
269
  ## Safety
138
270
 
139
271
  - Prefer `list` and `get` before writes
140
272
  - Use `--dry-run` before create, update, delete, and sync
141
- - Use `--force` only for deletes the user explicitly requested
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`
142
276
  - Re-read changed rows after writes
143
277
  - Keep output structured so another agent can parse it
144
278
  - If production behavior matters, separate code state, deploy state, and data state