@numericoach/gskills-admin-cli 0.1.1 → 0.1.3

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,38 @@ 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
+
41
+ Operational helpers are available for the admin-only flows agents should not improvise:
42
+
43
+ ```bash
44
+ gskills-admin feedback claim <feedbackId> --dry-run --output json
45
+ gskills-admin feedback send-claim <feedbackId> --recipient-email user@example.com --subject "..." --body "..." --yes --output json
46
+ gskills-admin access grant --user <userId> --type DEFAULT --dry-run --output json
47
+ gskills-admin entities list --instance <instanceId> --output json
48
+ gskills-admin entities set-page-visibility --instance <instanceId> --page <pageId> --entity-ids google-group:team@example.com --dry-run --output json
49
+ gskills-admin org-units-sync google --instance <instanceId> --yes --output json
50
+ gskills-admin ambassadors label --instance <instanceId> --language fr --output json
51
+ ```
52
+
53
+ Raw project and analytics data can be read through resources such as `project-data`, `ticket-sla-rules`, `analytics`, `quiz-attempts`, `user-paths`, `chromebook-progress`, and `user-learning-paths`.
54
+
23
55
  ## Agent skill
24
56
 
25
57
  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",
@@ -387,6 +405,33 @@ var resources = [
387
405
  aliases: ["instance-project-data"],
388
406
  defaultFields: ["id", "instanceId", "clientAdminEmail", "clientType", "goLiveAt", "updatedAt"]
389
407
  },
408
+ {
409
+ name: "project-contacts",
410
+ delegate: "instanceClientContact",
411
+ label: "Project contacts",
412
+ aliases: ["project-contact", "client-contacts", "additional-contacts"],
413
+ defaultFields: ["id", "instanceProjectDataId", "email", "firstName", "lastName", "jobTitle", "order", "updatedAt"],
414
+ instanceField: null,
415
+ dangerousDelete: true
416
+ },
417
+ {
418
+ name: "ticket-sla-rules",
419
+ delegate: "instanceTicketSlaRule",
420
+ label: "Ticket SLA rules",
421
+ aliases: ["sla-rules", "ticket-sla-rule"],
422
+ defaultFields: ["id", "instanceProjectDataId", "label", "ackTargetValue", "ackTargetUnit", "resolutionTargetValue", "resolutionTargetUnit", "order", "updatedAt"],
423
+ instanceField: null,
424
+ dangerousDelete: true
425
+ },
426
+ {
427
+ name: "ticket-sla-contacts",
428
+ delegate: "instanceTicketSlaContact",
429
+ label: "Ticket SLA contacts",
430
+ aliases: ["sla-contacts", "ticket-sla-contact"],
431
+ defaultFields: ["id", "instanceProjectDataId", "email", "firstName", "lastName", "jobTitle", "order", "updatedAt"],
432
+ instanceField: null,
433
+ dangerousDelete: true
434
+ },
390
435
  {
391
436
  name: "instances",
392
437
  delegate: "instance",
@@ -427,6 +472,58 @@ var resources = [
427
472
  aliases: ["feedback"],
428
473
  defaultFields: ["id", "instanceId", "userId", "type", "status", "priority", "createdAt", "updatedAt"]
429
474
  },
475
+ {
476
+ name: "feedback-replies",
477
+ delegate: "feedbackReply",
478
+ label: "Feedback replies",
479
+ aliases: ["feedback-reply", "replies"],
480
+ defaultFields: ["id", "feedbackId", "authorId", "subjectFr", "targetLang", "createdAt"],
481
+ instanceField: null,
482
+ dangerousDelete: true
483
+ },
484
+ {
485
+ name: "feedback-assignees",
486
+ delegate: "feedbackAssignee",
487
+ label: "Feedback assignees",
488
+ aliases: ["feedback-assignee"],
489
+ defaultFields: ["id", "feedbackId", "userId", "assignedAt"],
490
+ instanceField: null,
491
+ dangerousDelete: true
492
+ },
493
+ {
494
+ name: "feedback-claim-notifications",
495
+ delegate: "feedbackClaimNotification",
496
+ label: "Feedback claim notifications",
497
+ aliases: ["claim-notifications", "feedback-emails"],
498
+ defaultFields: ["id", "feedbackId", "authorId", "recipientEmail", "subject", "source", "createdAt"],
499
+ instanceField: null
500
+ },
501
+ {
502
+ name: "ambassadors",
503
+ delegate: "ambassadorInstance",
504
+ label: "Ambassadors",
505
+ aliases: ["ambassador", "champions", "champion", "experts", "expert"],
506
+ defaultFields: ["id", "userId", "active", "descriptionAmbassador", "contactContent", "createdOn"],
507
+ instanceField: null,
508
+ dangerousDelete: true
509
+ },
510
+ {
511
+ name: "tags",
512
+ delegate: "tag",
513
+ label: "Tags",
514
+ aliases: ["tag"],
515
+ defaultFields: ["id", "name", "normalizedName", "color", "scope", "ownerInstanceId", "createdAt", "updatedAt"],
516
+ instanceField: "ownerInstanceId",
517
+ dangerousDelete: true
518
+ },
519
+ {
520
+ name: "tag-assignments",
521
+ delegate: "tagAssignment",
522
+ label: "Tag assignments",
523
+ aliases: ["tag-assignment"],
524
+ defaultFields: ["id", "tagId", "instanceId", "entityType", "entityId", "createdAt", "updatedAt"],
525
+ dangerousDelete: true
526
+ },
430
527
  {
431
528
  name: "menus",
432
529
  delegate: "menuItem",
@@ -461,19 +558,119 @@ var resources = [
461
558
  aliases: ["feature-flag", "flags"],
462
559
  defaultFields: ["id", "featureKey", "targetType", "targetId", "active", "variant", "updatedAt"]
463
560
  },
561
+ {
562
+ name: "groups",
563
+ delegate: "group",
564
+ label: "Manual groups",
565
+ aliases: ["group", "manual-groups", "manual-group"],
566
+ defaultFields: ["id", "name", "description", "instanceId", "isRevert", "createdAt", "updatedAt"],
567
+ dangerousDelete: true
568
+ },
569
+ {
570
+ name: "org-units",
571
+ delegate: "orgUnit",
572
+ label: "Org units",
573
+ aliases: ["org-unit", "ou", "ous"],
574
+ defaultFields: ["id", "name", "code", "type", "googleOuId", "parentId", "instanceId", "instanceCountryParentId", "createdAt", "updatedAt"],
575
+ dangerousDelete: true
576
+ },
577
+ {
578
+ name: "user-org-units",
579
+ delegate: "userOrgUnit",
580
+ label: "User org unit assignments",
581
+ aliases: ["user-org-unit", "ou-memberships"],
582
+ defaultFields: ["userId", "orgUnitId", "primary", "assignedAt"],
583
+ instanceField: null,
584
+ dangerousDelete: true
585
+ },
586
+ {
587
+ name: "ou-admin-scopes",
588
+ delegate: "ouAdminOrgUnitScope",
589
+ label: "OU admin scopes",
590
+ aliases: ["ou-admin-scope"],
591
+ defaultFields: ["userId", "orgUnitId", "assignedAt"],
592
+ instanceField: null,
593
+ dangerousDelete: true
594
+ },
595
+ {
596
+ name: "entity-rule-configs",
597
+ delegate: "entityRuleConfig",
598
+ label: "Entity restriction rules",
599
+ aliases: ["entity-rules", "content-restriction-rules", "restrictions"],
600
+ defaultFields: ["id", "instanceId", "entityId", "restrictionMode", "categoryIds", "learningPathRestrictionMode", "learningPathIds", "alphaAllPrograms", "alphaProgramIds", "updatedAt"],
601
+ dangerousDelete: true
602
+ },
464
603
  {
465
604
  name: "users",
466
605
  delegate: "user",
467
606
  label: "Users",
468
607
  aliases: ["user"],
469
- defaultFields: ["id", "email", "name", "adminState", "instanceID", "lastSeen", "updatedAt"]
608
+ defaultFields: ["id", "email", "name", "adminState", "instanceID", "lastSeen", "updatedAt"],
609
+ instanceField: "instanceID"
470
610
  },
471
611
  {
472
612
  name: "access-passes",
473
613
  delegate: "accessPass",
474
614
  label: "Access passes",
475
615
  aliases: ["access-pass", "passes"],
476
- defaultFields: ["id", "userId", "instanceId", "createdAt", "updatedAt"]
616
+ defaultFields: ["id", "userId", "type", "startAt", "expireAt", "givenAt", "createdAt", "updatedAt"],
617
+ instanceField: "user.instanceID",
618
+ dangerousDelete: true
619
+ },
620
+ {
621
+ name: "analytics",
622
+ delegate: "analytics",
623
+ label: "Analytics events",
624
+ aliases: ["analytics-events"],
625
+ defaultFields: ["id", "instanceId", "userId", "pageId", "createdAt"]
626
+ },
627
+ {
628
+ name: "user-paths",
629
+ delegate: "userPath",
630
+ label: "User course completions",
631
+ aliases: ["user-path", "course-completions"],
632
+ defaultFields: ["id", "userId", "pageId", "isAchieved", "createdAt", "updatedAt"],
633
+ instanceField: null
634
+ },
635
+ {
636
+ name: "quiz-attempts",
637
+ delegate: "userQuizAttempt",
638
+ label: "Quiz attempts",
639
+ aliases: ["quiz-attempt", "attempts"],
640
+ defaultFields: ["id", "userId", "quizId", "pageId", "score", "percentage", "passed", "isCompleted", "createdAt", "updatedAt"],
641
+ instanceField: null
642
+ },
643
+ {
644
+ name: "chromebook-progress",
645
+ delegate: "chromebookUserProgress",
646
+ label: "Chromebook progress",
647
+ aliases: ["chromebook-user-progress"],
648
+ defaultFields: ["id", "userId", "exerciseId", "currentStep", "isCompleted", "startedAt", "completedAt", "createdAt", "updatedAt"],
649
+ instanceField: null
650
+ },
651
+ {
652
+ name: "user-badges",
653
+ delegate: "userBadge",
654
+ label: "User badges",
655
+ aliases: ["user-badge"],
656
+ defaultFields: ["id", "userId", "badgeId", "obtainedAt", "read"],
657
+ instanceField: null
658
+ },
659
+ {
660
+ name: "user-learning-paths",
661
+ delegate: "userLearningPath",
662
+ label: "User learning paths",
663
+ aliases: ["user-learning-path"],
664
+ defaultFields: ["id", "userId", "learningPathId", "isCompleted", "startedAt", "completedAt", "createdAt", "updatedAt"],
665
+ instanceField: null
666
+ },
667
+ {
668
+ name: "user-learning-path-item-completions",
669
+ delegate: "userLearningPathItemCompletion",
670
+ label: "User learning path item completions",
671
+ aliases: ["learning-path-item-completions", "user-learning-path-item-completion"],
672
+ defaultFields: ["id", "userId", "learningPathItemId", "completedAt"],
673
+ instanceField: null
477
674
  }
478
675
  ];
479
676
  var findResource = (name) => {
@@ -510,6 +707,18 @@ var runCommand = async (ctx) => {
510
707
  return resourceHelpRows();
511
708
  if (group === "sync")
512
709
  return runSyncCommand(actionOrResource, ctx);
710
+ if (group === "cache")
711
+ return runCacheCommand(actionOrResource, ctx);
712
+ if (group === "feedback")
713
+ return runFeedbackCommand(actionOrResource, maybeAction, ctx);
714
+ if (group === "access")
715
+ return runAccessCommand(actionOrResource, ctx);
716
+ if (group === "entities")
717
+ return runEntitiesCommand(actionOrResource, maybeAction, ctx);
718
+ if (group === "org-units-sync")
719
+ return runOrgUnitsSyncCommand(actionOrResource, ctx);
720
+ if (group === "ambassadors" && actionOrResource === "label")
721
+ return runAmbassadorsCommand(actionOrResource, ctx);
513
722
  const resource = findResource(group);
514
723
  return runResourceCommand(resource, actionOrResource, maybeAction, rest, ctx);
515
724
  };
@@ -572,8 +781,9 @@ var listResource = async (resource, ctx) => {
572
781
  const searchParams = new URLSearchParams;
573
782
  const where = parseJsonObject(getStringFlag(ctx, "where"), "--where");
574
783
  const instanceId = getStringFlag(ctx, "instance") ?? defaultInstanceId(resource);
575
- if (instanceId)
576
- where.instanceId = instanceId;
784
+ const instanceField = resource.instanceField === undefined ? "instanceId" : resource.instanceField;
785
+ if (instanceId && instanceField)
786
+ setWhereValue(where, instanceField, instanceId);
577
787
  searchParams.set("where", JSON.stringify(where));
578
788
  searchParams.set("fields", getFields(resource, ctx).join(","));
579
789
  searchParams.set("take", String(getNumberFlag(ctx, "take") ?? 25));
@@ -581,13 +791,25 @@ var listResource = async (resource, ctx) => {
581
791
  const orderBy = getStringFlag(ctx, "order-by");
582
792
  if (orderBy)
583
793
  searchParams.set("orderBy", orderBy);
794
+ if (hasFlag(ctx, "dry-run")) {
795
+ return {
796
+ dryRun: true,
797
+ resource: resource.name,
798
+ where,
799
+ fields: getFields(resource, ctx),
800
+ take: getNumberFlag(ctx, "take") ?? 25,
801
+ skip: getNumberFlag(ctx, "skip") ?? 0,
802
+ orderBy: orderBy ? parseJsonObject(orderBy, "--order-by") : {}
803
+ };
804
+ }
584
805
  return requestApi(`/api/cli/${resource.name}?${searchParams.toString()}`);
585
806
  };
586
807
  var createResource = async (resource, ctx) => {
587
808
  const data = parseJsonObject(getStringFlag(ctx, "data"), "--data");
588
809
  const instanceId = getStringFlag(ctx, "instance") ?? defaultInstanceId(resource);
589
- if (instanceId && data.instanceId === undefined)
590
- data.instanceId = instanceId;
810
+ const instanceField = resource.instanceField === undefined ? "instanceId" : resource.instanceField;
811
+ if (instanceId && instanceField && !instanceField.includes(".") && data[instanceField] === undefined)
812
+ data[instanceField] = instanceId;
591
813
  if (Object.keys(data).length === 0)
592
814
  throw new CliError("Missing --data JSON", 2);
593
815
  if (hasFlag(ctx, "dry-run"))
@@ -644,28 +866,303 @@ var deleteResource = async (resource, id, ctx) => {
644
866
  })
645
867
  });
646
868
  };
869
+ var runFeedbackCommand = async (action, feedbackId, ctx) => {
870
+ if (!action || action === "help")
871
+ return feedbackHelp();
872
+ if ((action === "claim" || action === "send-claim") && !feedbackId) {
873
+ throw new CliError("Missing feedback id", 2);
874
+ }
875
+ if (action === "claim") {
876
+ return requestApi("/api/cli/feedback/claim", {
877
+ method: "POST",
878
+ body: JSON.stringify({
879
+ feedbackId,
880
+ dryRun: hasFlag(ctx, "dry-run")
881
+ })
882
+ });
883
+ }
884
+ if (action === "send-claim") {
885
+ if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
886
+ throw new CliError("Sending feedback email requires --yes or --dry-run", 2);
887
+ }
888
+ return requestApi("/api/cli/feedback/send-claim", {
889
+ method: "POST",
890
+ body: JSON.stringify({
891
+ feedbackId,
892
+ recipientEmail: getStringFlag(ctx, "recipient-email"),
893
+ recipientName: getStringFlag(ctx, "recipient-name"),
894
+ ccEmails: splitCsv(getStringFlag(ctx, "cc")),
895
+ subject: getStringFlag(ctx, "subject"),
896
+ body: getStringFlag(ctx, "body"),
897
+ dryRun: hasFlag(ctx, "dry-run")
898
+ })
899
+ });
900
+ }
901
+ throw new CliError(`Unknown feedback command "${action}"`, 2);
902
+ };
903
+ var runAccessCommand = async (action, ctx) => {
904
+ if (!action || action === "help")
905
+ return accessHelp();
906
+ if (action === "grant") {
907
+ const userId = getStringFlag(ctx, "user");
908
+ if (!userId)
909
+ throw new CliError("Missing --user", 2);
910
+ if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
911
+ throw new CliError("Granting access writes production data. Add --yes or use --dry-run.", 2);
912
+ }
913
+ return requestApi("/api/cli/access/grant", {
914
+ method: "POST",
915
+ body: JSON.stringify({
916
+ userId,
917
+ type: getStringFlag(ctx, "type") ?? "DEFAULT",
918
+ startAt: getStringFlag(ctx, "start-at"),
919
+ customDurationDays: getNumberFlag(ctx, "custom-duration-days"),
920
+ preferredLanguage: getStringFlag(ctx, "preferred-language"),
921
+ dryRun: hasFlag(ctx, "dry-run")
922
+ })
923
+ });
924
+ }
925
+ if (action === "revoke-active") {
926
+ const userId = getStringFlag(ctx, "user");
927
+ if (!userId)
928
+ throw new CliError("Missing --user", 2);
929
+ if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
930
+ throw new CliError("Revoking access writes production data. Add --yes or use --dry-run.", 2);
931
+ }
932
+ return requestApi("/api/cli/access/revoke-active", {
933
+ method: "POST",
934
+ body: JSON.stringify({
935
+ userId,
936
+ dryRun: hasFlag(ctx, "dry-run")
937
+ })
938
+ });
939
+ }
940
+ throw new CliError(`Unknown access command "${action}"`, 2);
941
+ };
942
+ var runEntitiesCommand = async (action, entityId, ctx) => {
943
+ if (!action || action === "help")
944
+ return entitiesHelp();
945
+ const instanceId = getStringFlag(ctx, "instance");
946
+ if (["list", "detail", "access-summary", "sync-google-groups", "save-access-rules", "set-restrictions", "set-page-visibility"].includes(action) && !instanceId) {
947
+ throw new CliError("Missing --instance", 2);
948
+ }
949
+ if (action === "list") {
950
+ return requestApi(`/api/cli/entities/list?${entitySearchParams(ctx).toString()}`);
951
+ }
952
+ if (action === "detail") {
953
+ if (!entityId)
954
+ throw new CliError("Missing entity id", 2);
955
+ const searchParams = entitySearchParams(ctx);
956
+ searchParams.set("entityId", entityId);
957
+ return requestApi(`/api/cli/entities/detail?${searchParams.toString()}`);
958
+ }
959
+ if (action === "access-summary") {
960
+ return requestApi(`/api/cli/entities/access-summary?${entitySearchParams(ctx).toString()}`);
961
+ }
962
+ if (action === "sync-google-groups") {
963
+ return requestApi("/api/cli/entities/sync-google-groups", {
964
+ method: "POST",
965
+ body: JSON.stringify({
966
+ instanceId,
967
+ language: getStringFlag(ctx, "language") ?? "en",
968
+ dryRun: hasFlag(ctx, "dry-run")
969
+ })
970
+ });
971
+ }
972
+ if (action === "save-access-rules") {
973
+ if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
974
+ throw new CliError("Changing instance access rules writes production data. Add --yes or use --dry-run.", 2);
975
+ }
976
+ return requestApi("/api/cli/entities/save-access-rules", {
977
+ method: "POST",
978
+ body: JSON.stringify({
979
+ instanceId,
980
+ entityIds: splitCsv(getStringFlag(ctx, "entity-ids")),
981
+ dryRun: hasFlag(ctx, "dry-run")
982
+ })
983
+ });
984
+ }
985
+ if (action === "set-restrictions") {
986
+ const selectedEntityId = entityId ?? getStringFlag(ctx, "entity-id");
987
+ if (!selectedEntityId)
988
+ throw new CliError("Missing entity id", 2);
989
+ if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
990
+ throw new CliError("Changing content restrictions writes production data. Add --yes or use --dry-run.", 2);
991
+ }
992
+ return requestApi("/api/cli/entities/set-restrictions", {
993
+ method: "POST",
994
+ body: JSON.stringify({
995
+ instanceId,
996
+ entityId: selectedEntityId,
997
+ restrictionMode: getStringFlag(ctx, "restriction-mode"),
998
+ categoryIds: splitCsv(getStringFlag(ctx, "category-ids")),
999
+ learningPathRestrictionMode: getStringFlag(ctx, "learning-path-restriction-mode"),
1000
+ learningPathIds: splitCsv(getStringFlag(ctx, "learning-path-ids")),
1001
+ alphaAllPrograms: hasFlag(ctx, "alpha-all-programs"),
1002
+ alphaProgramIds: splitCsv(getStringFlag(ctx, "alpha-program-ids")),
1003
+ dryRun: hasFlag(ctx, "dry-run")
1004
+ })
1005
+ });
1006
+ }
1007
+ if (action === "set-page-visibility") {
1008
+ const pageId = getStringFlag(ctx, "page");
1009
+ if (!pageId)
1010
+ throw new CliError("Missing --page", 2);
1011
+ if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
1012
+ throw new CliError("Changing page visibility writes production data. Add --yes or use --dry-run.", 2);
1013
+ }
1014
+ return requestApi("/api/cli/entities/set-page-visibility", {
1015
+ method: "POST",
1016
+ body: JSON.stringify({
1017
+ instanceId,
1018
+ pageId,
1019
+ entityIds: splitCsv(getStringFlag(ctx, "entity-ids")),
1020
+ dryRun: hasFlag(ctx, "dry-run")
1021
+ })
1022
+ });
1023
+ }
1024
+ throw new CliError(`Unknown entities command "${action}"`, 2);
1025
+ };
1026
+ var runOrgUnitsSyncCommand = async (action, ctx) => {
1027
+ if (!action || action === "help")
1028
+ return orgUnitsSyncHelp();
1029
+ if (action !== "google")
1030
+ throw new CliError(`Unknown org-units-sync command "${action}"`, 2);
1031
+ const instanceId = getStringFlag(ctx, "instance");
1032
+ if (!instanceId)
1033
+ throw new CliError("Missing --instance", 2);
1034
+ if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
1035
+ throw new CliError("Google OU sync writes org-unit and membership data. Add --yes or use --dry-run.", 2);
1036
+ }
1037
+ return requestApi("/api/cli/org-units/sync-google", {
1038
+ method: "POST",
1039
+ body: JSON.stringify({
1040
+ instanceId,
1041
+ dryRun: hasFlag(ctx, "dry-run")
1042
+ })
1043
+ });
1044
+ };
1045
+ var runAmbassadorsCommand = async (_action, ctx) => {
1046
+ const instanceId = getStringFlag(ctx, "instance");
1047
+ if (!instanceId)
1048
+ throw new CliError("Missing --instance", 2);
1049
+ const language = getStringFlag(ctx, "language") ?? "fr";
1050
+ return requestApi(`/api/cli/ambassadors/label?instanceId=${encodeURIComponent(instanceId)}&language=${encodeURIComponent(language)}`);
1051
+ };
647
1052
  var runSyncCommand = async (action, ctx) => {
648
1053
  if (!action || action === "help")
649
1054
  return syncHelp();
650
- if (action !== "run")
1055
+ if (action === "presets")
1056
+ return syncPresets();
1057
+ if (action === "logs")
1058
+ return syncLogs(ctx);
1059
+ if (action !== "run" && action !== "diff")
651
1060
  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);
1061
+ const targetInstanceIds = getTargetInstanceIds(ctx);
1062
+ if (targetInstanceIds.length === 0)
1063
+ throw new CliError("Missing --target or --targets", 2);
1064
+ if (action === "run" && !hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
1065
+ throw new CliError("Sync writes DB data. Add --yes, use --dry-run, or use sync diff.", 2);
657
1066
  }
658
- const payload = {
1067
+ const basePayload = {
659
1068
  sourceInstanceId: getStringFlag(ctx, "source") ?? "global",
660
- targetInstanceId,
661
- options: buildSyncOptions(ctx),
1069
+ options: buildSyncOptions(ctx)
1070
+ };
1071
+ const endpoint = action === "diff" || hasFlag(ctx, "dry-run") ? "/api/cli/sync/diff" : "/api/cli/sync/run";
1072
+ const runForTarget = (targetInstanceId) => requestApi(endpoint, {
1073
+ method: "POST",
1074
+ body: JSON.stringify({
1075
+ ...basePayload,
1076
+ targetInstanceId,
1077
+ dryRun: action === "diff" || hasFlag(ctx, "dry-run")
1078
+ })
1079
+ });
1080
+ if (targetInstanceIds.length === 1)
1081
+ return runForTarget(targetInstanceIds[0]);
1082
+ const results = [];
1083
+ for (const targetInstanceId of targetInstanceIds) {
1084
+ results.push({
1085
+ targetInstanceId,
1086
+ result: await runForTarget(targetInstanceId)
1087
+ });
1088
+ }
1089
+ return { targets: results };
1090
+ };
1091
+ var runCacheCommand = async (action, ctx) => {
1092
+ if (!action || action === "help")
1093
+ return cacheHelp();
1094
+ if (action === "scopes")
1095
+ return requestApi("/api/cli/cache/scopes");
1096
+ if (action !== "invalidate")
1097
+ throw new CliError(`Unknown cache command "${action}"`, 2);
1098
+ const instanceId = getStringFlag(ctx, "instance") ?? getStringFlag(ctx, "target");
1099
+ if (!instanceId)
1100
+ throw new CliError("Missing --instance", 2);
1101
+ const scope = getStringFlag(ctx, "scope") ?? "all";
1102
+ const languages = splitCsv(getStringFlag(ctx, "languages"));
1103
+ const payload = {
1104
+ instanceId,
1105
+ scope,
1106
+ languages,
662
1107
  dryRun: hasFlag(ctx, "dry-run")
663
1108
  };
664
- return requestApi("/api/cli/sync/run", {
1109
+ if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
1110
+ throw new CliError("Cache invalidation writes deploy-cache versions. Add --yes or use --dry-run.", 2, payload);
1111
+ }
1112
+ return requestApi("/api/cli/cache/invalidate", {
665
1113
  method: "POST",
666
1114
  body: JSON.stringify(payload)
667
1115
  });
668
1116
  };
1117
+ var syncLogs = (ctx) => {
1118
+ const searchParams = new URLSearchParams;
1119
+ const targetInstanceId = getStringFlag(ctx, "target") ?? getStringFlag(ctx, "instance");
1120
+ const sourceInstanceId = getStringFlag(ctx, "source");
1121
+ const status = getStringFlag(ctx, "status");
1122
+ if (targetInstanceId)
1123
+ searchParams.set("targetInstanceId", targetInstanceId);
1124
+ if (sourceInstanceId)
1125
+ searchParams.set("sourceInstanceId", sourceInstanceId);
1126
+ if (status)
1127
+ searchParams.set("status", status);
1128
+ searchParams.set("take", String(getNumberFlag(ctx, "take") ?? 10));
1129
+ return requestApi(`/api/cli/sync/logs?${searchParams.toString()}`);
1130
+ };
1131
+ var syncPresets = () => ({
1132
+ note: "Presets from common super-admin sync runs. Always run sync diff before sync run --yes.",
1133
+ presets: [
1134
+ {
1135
+ name: "full-content",
1136
+ description: "Same broad content push as the global synchro-content screen.",
1137
+ command: "gskills-admin sync diff --target <instanceId> --preset full-content",
1138
+ only: ["languages", "categories", "pages", "menus", "quizzes", "learningPaths", "knowledge", "resources", "badges", "workflows"]
1139
+ },
1140
+ {
1141
+ name: "client-content",
1142
+ description: "Most common client content shape in recent Marina-correlated runs.",
1143
+ command: "gskills-admin sync diff --target <instanceId> --preset client-content",
1144
+ only: ["categories", "pages", "menus", "quizzes", "learningPaths", "resources", "badges"]
1145
+ },
1146
+ {
1147
+ name: "pages-learning-paths",
1148
+ description: "Common refinement pass after a broader run.",
1149
+ command: "gskills-admin sync diff --target <instanceId> --preset pages-learning-paths",
1150
+ only: ["pages", "learningPaths"]
1151
+ },
1152
+ {
1153
+ name: "pages-only",
1154
+ description: "Use for syncing-pages style checks or page-only corrections.",
1155
+ command: "gskills-admin sync diff --target <instanceId> --preset pages-only --pages <pageId,pageId>",
1156
+ only: ["pages"]
1157
+ },
1158
+ {
1159
+ name: "knowledge-resources-paths",
1160
+ description: "Useful when content assets or learning paths need a narrow rerun.",
1161
+ command: "gskills-admin sync diff --target <instanceId> --preset knowledge-resources-paths",
1162
+ only: ["knowledge", "resources", "learningPaths"]
1163
+ }
1164
+ ]
1165
+ });
669
1166
  var runSkillsCommand = async (action, ctx) => {
670
1167
  if (!action || action === "help")
671
1168
  return skillsHelp();
@@ -682,6 +1179,11 @@ var runSkillsCommand = async (action, ctx) => {
682
1179
  };
683
1180
  var buildSyncOptions = (ctx) => {
684
1181
  const only = new Set(splitCsv(getStringFlag(ctx, "only")));
1182
+ const preset = getStringFlag(ctx, "preset");
1183
+ if (preset) {
1184
+ for (const item of syncPresetItems(preset))
1185
+ only.add(item);
1186
+ }
685
1187
  const hasOnly = only.size > 0;
686
1188
  const enabled = (key) => !hasOnly || only.has(key);
687
1189
  return {
@@ -714,8 +1216,58 @@ var buildSyncOptions = (ctx) => {
714
1216
  collectSummary: true
715
1217
  };
716
1218
  };
1219
+ var syncPresetItems = (preset) => {
1220
+ switch (preset) {
1221
+ case "full-content":
1222
+ return ["languages", "categories", "pages", "menus", "quizzes", "learningPaths", "knowledge", "resources", "badges", "workflows"];
1223
+ case "client-content":
1224
+ return ["categories", "pages", "menus", "quizzes", "learningPaths", "resources", "badges"];
1225
+ case "pages-learning-paths":
1226
+ return ["pages", "learningPaths"];
1227
+ case "pages-only":
1228
+ return ["pages"];
1229
+ case "knowledge-resources-paths":
1230
+ return ["knowledge", "resources", "learningPaths"];
1231
+ default:
1232
+ throw new CliError(`Unknown sync preset "${preset}"`, 2, {
1233
+ available: ["full-content", "client-content", "pages-learning-paths", "pages-only", "knowledge-resources-paths"]
1234
+ });
1235
+ }
1236
+ };
1237
+ var getTargetInstanceIds = (ctx) => {
1238
+ const explicitTargets = splitCsv(getStringFlag(ctx, "targets"));
1239
+ const target = getStringFlag(ctx, "target");
1240
+ return Array.from(new Set([
1241
+ ...explicitTargets,
1242
+ ...target ? [target] : []
1243
+ ]));
1244
+ };
717
1245
  var getFields = (resource, ctx) => splitCsv(getStringFlag(ctx, "fields")).length > 0 ? splitCsv(getStringFlag(ctx, "fields")) : resource.defaultFields;
1246
+ var entitySearchParams = (ctx) => {
1247
+ const searchParams = new URLSearchParams;
1248
+ const instanceId = getStringFlag(ctx, "instance");
1249
+ const language = getStringFlag(ctx, "language") ?? "en";
1250
+ if (instanceId)
1251
+ searchParams.set("instanceId", instanceId);
1252
+ if (language)
1253
+ searchParams.set("language", language);
1254
+ return searchParams;
1255
+ };
718
1256
  var splitCsv = (value) => value ? value.split(",").map((item) => item.trim()).filter(Boolean) : [];
1257
+ var setWhereValue = (where, fieldPath, value) => {
1258
+ const parts = fieldPath.split(".").map((part) => part.trim()).filter(Boolean);
1259
+ if (parts.length === 0)
1260
+ return;
1261
+ let cursor = where;
1262
+ for (const part of parts.slice(0, -1)) {
1263
+ const existing = cursor[part];
1264
+ if (!existing || typeof existing !== "object" || Array.isArray(existing)) {
1265
+ cursor[part] = {};
1266
+ }
1267
+ cursor = cursor[part];
1268
+ }
1269
+ cursor[parts[parts.length - 1]] = value;
1270
+ };
719
1271
  var GLOBAL_DEFAULT_RESOURCES = new Set([
720
1272
  "pages",
721
1273
  "topics",
@@ -726,7 +1278,8 @@ var GLOBAL_DEFAULT_RESOURCES = new Set([
726
1278
  "badges",
727
1279
  "menus",
728
1280
  "menu-sections",
729
- "workflows"
1281
+ "workflows",
1282
+ "chromebook-exercises"
730
1283
  ]);
731
1284
  var defaultInstanceId = (resource) => GLOBAL_DEFAULT_RESOURCES.has(resource.name) ? "global" : undefined;
732
1285
  var skillsSourceDir = async () => {
@@ -798,9 +1351,27 @@ var schemaHelp = () => ({
798
1351
  { name: "resources", writes: false },
799
1352
  { name: "schema", writes: false },
800
1353
  { name: "skills install", flags: ["--target"], writes: true },
801
- { name: "sync run", required: ["--target"], safety: ["--yes or --dry-run"], writes: true },
1354
+ { name: "sync diff", required: ["--target or --targets"], writes: false },
1355
+ { name: "sync run", required: ["--target or --targets"], safety: ["--yes or --dry-run"], writes: true },
1356
+ { name: "sync logs", flags: ["--target", "--source", "--status", "--take"], writes: false },
1357
+ { name: "sync presets", writes: false },
1358
+ { name: "cache scopes", writes: false },
1359
+ { name: "cache invalidate", required: ["--instance"], flags: ["--scope", "--languages", "--yes", "--dry-run"], writes: true },
1360
+ { name: "feedback claim", args: ["feedbackId"], flags: ["--dry-run"], writes: true },
1361
+ { name: "feedback send-claim", args: ["feedbackId"], flags: ["--recipient-email", "--recipient-name", "--cc", "--subject", "--body", "--yes", "--dry-run"], writes: true },
1362
+ { name: "access grant", required: ["--user"], flags: ["--type", "--start-at", "--custom-duration-days", "--preferred-language", "--yes", "--dry-run"], writes: true },
1363
+ { name: "access revoke-active", required: ["--user"], flags: ["--yes", "--dry-run"], writes: true },
1364
+ { name: "entities list", required: ["--instance"], flags: ["--language"], writes: false },
1365
+ { name: "entities detail", args: ["entityId"], required: ["--instance"], flags: ["--language"], writes: false },
1366
+ { name: "entities access-summary", required: ["--instance"], writes: false },
1367
+ { name: "entities sync-google-groups", required: ["--instance"], flags: ["--dry-run"], writes: false },
1368
+ { name: "entities save-access-rules", required: ["--instance", "--entity-ids"], flags: ["--yes", "--dry-run"], writes: true },
1369
+ { name: "entities set-restrictions", args: ["entityId"], required: ["--instance"], flags: ["--category-ids", "--learning-path-ids", "--alpha-program-ids", "--alpha-all-programs", "--yes", "--dry-run"], writes: true },
1370
+ { name: "entities set-page-visibility", required: ["--instance", "--page"], flags: ["--entity-ids", "--yes", "--dry-run"], writes: true },
1371
+ { name: "org-units-sync google", required: ["--instance"], flags: ["--yes", "--dry-run"], writes: true },
1372
+ { name: "ambassadors label", required: ["--instance"], flags: ["--language"], writes: false },
802
1373
  ...resources.flatMap((resource) => [
803
- { name: `${resource.name} list`, writes: false, flags: ["--where", "--fields", "--take", "--skip", "--order-by", "--instance"] },
1374
+ { name: `${resource.name} list`, writes: false, flags: ["--where", "--fields", "--take", "--skip", "--order-by", "--instance", "--dry-run"] },
804
1375
  { name: `${resource.name} get`, args: ["id"], writes: false },
805
1376
  { name: `${resource.name} create`, flags: ["--data", "--instance", "--dry-run"], writes: true },
806
1377
  { name: `${resource.name} update`, args: ["id"], flags: ["--data", "--dry-run"], writes: true },
@@ -833,12 +1404,63 @@ var skillsHelp = () => ({
833
1404
  });
834
1405
  var syncHelp = () => ({
835
1406
  usage: [
1407
+ "gskills-admin sync diff --target <instanceId> --only pages,menus --pages <id,id> --languages fr,en",
1408
+ "gskills-admin sync diff --target <instanceId> --preset client-content",
1409
+ "gskills-admin sync logs --target <instanceId> --take 10",
1410
+ "gskills-admin sync presets",
836
1411
  "gskills-admin sync run --target <instanceId> --yes",
1412
+ "gskills-admin sync run --targets <id,id> --only pages,quizzes --dry-run",
837
1413
  "gskills-admin sync run --target <instanceId> --only pages,quizzes,learningPaths --pages <id,id> --languages fr,en --yes",
838
1414
  "gskills-admin sync run --target <instanceId> --dry-run"
839
1415
  ],
840
1416
  syncable: resources.filter((resource) => resource.syncable).map((resource) => resource.name),
841
- sourceDefault: "global"
1417
+ presets: ["full-content", "client-content", "pages-learning-paths", "pages-only", "knowledge-resources-paths"],
1418
+ sourceDefault: "global",
1419
+ dryRun: "Uses the shared sync diff preview system without writing DB data."
1420
+ });
1421
+ var cacheHelp = () => ({
1422
+ usage: [
1423
+ "gskills-admin cache scopes",
1424
+ "gskills-admin cache invalidate --instance <instanceId> --scope pages --languages fr,en --dry-run",
1425
+ "gskills-admin cache invalidate --instance <instanceId> --scope menu-bundle --yes",
1426
+ "gskills-admin cache invalidate --instance <instanceId> --scope all --yes"
1427
+ ],
1428
+ scopes: ["all", "pages", "pages-knowledge", "menu-bundle", "applications"],
1429
+ note: "Uses the same deploy-cache version bump system as the super-admin content settings screen."
1430
+ });
1431
+ var feedbackHelp = () => ({
1432
+ usage: [
1433
+ "gskills-admin feedback claim <feedbackId> --dry-run",
1434
+ "gskills-admin feedback claim <feedbackId>",
1435
+ "gskills-admin feedback send-claim <feedbackId> --recipient-email user@example.com --subject '...' --body '...' --yes"
1436
+ ],
1437
+ note: "Claiming and sending emails use the same SLA recipient rules as the admin feedback UI and log through admin logs."
1438
+ });
1439
+ var accessHelp = () => ({
1440
+ usage: [
1441
+ "gskills-admin access grant --user <userId> --type DEFAULT --dry-run",
1442
+ "gskills-admin access grant --user <userId> --type PASS_90_DAYS --preferred-language fr --yes",
1443
+ "gskills-admin access revoke-active --user <userId> --yes"
1444
+ ],
1445
+ types: ["DEFAULT", "PASS_90_DAYS", "PASS_12_MONTHS", "CUSTOM", "UNLIMITED"]
1446
+ });
1447
+ var entitiesHelp = () => ({
1448
+ usage: [
1449
+ "gskills-admin entities list --instance <instanceId>",
1450
+ "gskills-admin entities detail <entityId> --instance <instanceId>",
1451
+ "gskills-admin entities access-summary --instance <instanceId>",
1452
+ "gskills-admin entities save-access-rules --instance <instanceId> --entity-ids manual-group:<id>,org-unit:<id> --dry-run",
1453
+ "gskills-admin entities set-restrictions <entityId> --instance <instanceId> --category-ids <id,id> --learning-path-ids <id,id> --yes",
1454
+ "gskills-admin entities set-page-visibility --instance <instanceId> --page <pageId> --entity-ids google-group:team@example.com --yes"
1455
+ ],
1456
+ note: "Entity ids use the shared admin entity format: manual-group:<id>, org-unit:<id>, google-group:<email>."
1457
+ });
1458
+ var orgUnitsSyncHelp = () => ({
1459
+ usage: [
1460
+ "gskills-admin org-units-sync google --instance <instanceId> --dry-run",
1461
+ "gskills-admin org-units-sync google --instance <instanceId> --yes"
1462
+ ],
1463
+ note: "Uses the same Google Admin OU sync engine as the instance admin UI."
842
1464
  });
843
1465
  var resourceHelp = (resource) => ({
844
1466
  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.3",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Admin-only CLI for GSkills super-admin operations.",
@@ -145,11 +145,244 @@ 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
+ ## Feedback And SLA Emails
262
+
263
+ Use these commands for feedback claim email flows. They reuse the same SLA contact flags and recipient validation as the admin feedback UI.
264
+
265
+ ```bash
266
+ gskills-admin feedback claim <feedbackId> --dry-run --output json
267
+ gskills-admin feedback claim <feedbackId> --output json
268
+ gskills-admin feedback send-claim <feedbackId> --recipient-email user@example.com --subject "GSkills - Ticket pris en charge" --body "Bonjour..." --dry-run --output json
269
+ gskills-admin feedback send-claim <feedbackId> --recipient-email user@example.com --subject "GSkills - Ticket pris en charge" --body "Bonjour..." --yes --output json
270
+ ```
271
+
272
+ Rules:
273
+
274
+ - Dry-run claim first to inspect recipient, CC recipients and draft.
275
+ - Send only after the ticket is claimed by the same CLI user.
276
+ - CC recipients must be allowed by instance SLA flags.
277
+ - All claim and email sends are admin-logged with CLI metadata.
278
+
279
+ ## Accesses
280
+
281
+ Use `access grant` and `access revoke-active` instead of raw `access-passes` writes when the operation should trigger workflows and admin logs.
282
+
283
+ ```bash
284
+ gskills-admin access grant --user <userId> --type DEFAULT --dry-run --output json
285
+ gskills-admin access grant --user <userId> --type PASS_90_DAYS --preferred-language fr --yes --output json
286
+ gskills-admin access revoke-active --user <userId> --dry-run --output json
287
+ gskills-admin access revoke-active --user <userId> --yes --output json
288
+ ```
289
+
290
+ Types are `DEFAULT`, `PASS_90_DAYS`, `PASS_12_MONTHS`, `CUSTOM`, and `UNLIMITED`.
291
+
292
+ ## Entities And Restrictions
293
+
294
+ Entities are the shared segmentation layer for manual groups, Google groups, and Google Admin OUs.
295
+
296
+ ```bash
297
+ gskills-admin entities list --instance <instanceId> --language fr --output json
298
+ gskills-admin entities detail manual-group:<groupId> --instance <instanceId> --language fr --output json
299
+ gskills-admin entities access-summary --instance <instanceId> --output json
300
+ gskills-admin entities sync-google-groups --instance <instanceId> --output json
301
+ gskills-admin org-units-sync google --instance <instanceId> --dry-run --output json
302
+ gskills-admin org-units-sync google --instance <instanceId> --yes --output json
303
+ ```
304
+
305
+ Entity ids use:
306
+
307
+ - `manual-group:<groupId>`
308
+ - `org-unit:<orgUnitId>`
309
+ - `google-group:<email>`
310
+
311
+ For instance access rules:
312
+
313
+ ```bash
314
+ gskills-admin entities save-access-rules --instance <instanceId> --entity-ids manual-group:<id>,org-unit:<id> --dry-run --output json
315
+ gskills-admin entities save-access-rules --instance <instanceId> --entity-ids manual-group:<id>,org-unit:<id> --yes --output json
316
+ ```
317
+
318
+ For content restrictions:
319
+
320
+ ```bash
321
+ gskills-admin entities set-restrictions manual-group:<id> --instance <instanceId> --category-ids <categoryId,categoryId> --learning-path-ids <pathId,pathId> --dry-run --output json
322
+ gskills-admin entities set-restrictions manual-group:<id> --instance <instanceId> --category-ids <categoryId,categoryId> --learning-path-ids <pathId,pathId> --yes --output json
323
+ gskills-admin entities set-page-visibility --instance <instanceId> --page <pageId> --entity-ids google-group:team@example.com --dry-run --output json
324
+ gskills-admin entities set-page-visibility --instance <instanceId> --page <pageId> --entity-ids google-group:team@example.com --yes --output json
325
+ ```
326
+
327
+ These commands update the same underlying shared restriction models as the UI and invalidate the dependent deploy cache scope.
328
+
329
+ ## Ambassadors
330
+
331
+ Ambassadors can be shown as ambassadors, experts or champions depending on the instance flag.
332
+
333
+ ```bash
334
+ gskills-admin ambassadors label --instance <instanceId> --language fr --output json
335
+ gskills-admin ambassadors list --where '{"user":{"instanceID":"<instanceId>"}}' --output json
336
+ ```
337
+
338
+ Use the label command before writing user-facing copy.
339
+
340
+ ## Project Data And Analytics
341
+
342
+ Project data resources:
343
+
344
+ - `project-data`
345
+ - `project-contacts`
346
+ - `ticket-sla-rules`
347
+ - `ticket-sla-contacts`
348
+
349
+ Analytics-readable resources:
350
+
351
+ - `analytics`
352
+ - `user-paths`
353
+ - `quiz-attempts`
354
+ - `chromebook-progress`
355
+ - `user-badges`
356
+ - `user-learning-paths`
357
+ - `user-learning-path-item-completions`
358
+
359
+ Examples:
360
+
361
+ ```bash
362
+ gskills-admin project-data list --instance <instanceId> --output json
363
+ gskills-admin analytics list --where '{"instanceId":"<instanceId>"}' --take 100 --output json
364
+ gskills-admin quiz-attempts list --where '{"user":{"instanceID":"<instanceId>"}}' --take 100 --output json
365
+ ```
366
+
367
+ Prefer these read paths for analytics investigation. They are intentionally raw enough to match UI analytics data without giving the agent a DB URL.
368
+
369
+ ## Cache Scope Choice
370
+
371
+ Prefer the narrowest scope:
372
+
373
+ - `pages`
374
+ - `pages-knowledge`
375
+ - `menu-bundle`
376
+ - `applications`
377
+ - `all`
378
+
148
379
  ## Safety
149
380
 
150
381
  - Prefer `list` and `get` before writes
151
382
  - Use `--dry-run` before create, update, delete, and sync
152
383
  - Use `--force --confirm-delete <resource>:<id>` only for deletes the user explicitly requested
384
+ - Use `sync diff` before `sync run --yes`
385
+ - Use cache `--dry-run` before cache `--yes`
153
386
  - Re-read changed rows after writes
154
387
  - Keep output structured so another agent can parse it
155
388
  - If production behavior matters, separate code state, deploy state, and data state