@numericoach/gskills-admin-cli 0.1.8 → 0.1.10

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
@@ -38,6 +38,15 @@ gskills-admin cache invalidate --instance <instanceId> --scope pages --languages
38
38
  gskills-admin cache invalidate --instance <instanceId> --scope menu-bundle --yes --output json
39
39
  ```
40
40
 
41
+ CRUD help includes cache hints for resources that can leave deploy views stale after a raw write:
42
+
43
+ ```bash
44
+ gskills-admin pages help --output json
45
+ gskills-admin topics help --output json
46
+ ```
47
+
48
+ Use the listed `cache.scopes` with `gskills-admin cache invalidate` after create, update, or delete when the end-user view must reflect the change immediately.
49
+
41
50
  Operational helpers are available for the admin-only flows agents should not improvise:
42
51
 
43
52
  ```bash
@@ -53,14 +62,16 @@ gskills-admin ambassadors label --instance <instanceId> --language fr --output j
53
62
 
54
63
  Feedback reply bodies are file-based on purpose. Production replies are multi-line, and `send-reply` rejects inline body text to avoid shell parsing surprises.
55
64
 
56
- 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`.
65
+ Raw project and analytics data can be read or adjusted through resources such as `project-data`, `ticket-sla-rules`, `analytics`, `quiz-attempts`, `user-paths`, `chromebook-progress`, `user-badges`, `user-learning-paths`, and `user-learning-path-item-completions`.
57
66
 
58
67
  ## Agent skill
59
68
 
60
- Install the bundled skills so AI agents know the auth model, resource map, output modes, sync workflow, content-authoring standards, and recurring DB-backed ops runbooks.
69
+ Install the bundled skills so AI agents know the auth model, resource map, output modes, sync workflow, content-authoring standards, recurring DB-backed ops runbooks, GSkills vocabulary, and recurring customer playbooks.
61
70
 
62
71
  ```bash
63
72
  gskills-admin skills install --target ~/.codex/skills
73
+ gskills-admin skills install --name gskills-vocabulary --target ~/.codex/skills
74
+ gskills-admin skills install --name gskills-customer-playbooks --target ~/.codex/skills
64
75
  gskills-admin skills install --name gskills-feedback-db-ops --target ~/.codex/skills
65
76
  ```
66
77
 
@@ -177,9 +177,11 @@ var loginWithGSkills = async (input) => {
177
177
  const startUrl = new URL("/api/cli/auth/start", baseUrl);
178
178
  startUrl.searchParams.set("redirect_uri", redirectUri);
179
179
  startUrl.searchParams.set("state", state);
180
- await openUrl(startUrl.toString());
181
- process.stderr.write(`Opened ${startUrl.toString()}
180
+ const opened = await openUrl(startUrl.toString());
181
+ if (opened) {
182
+ process.stderr.write(`Opened ${startUrl.toString()}
182
183
  `);
184
+ }
183
185
  });
184
186
  if (callback.state !== state) {
185
187
  throw new CliError("GSkills auth state mismatch", 403);
@@ -285,13 +287,15 @@ var normalizeBaseUrl = (value) => {
285
287
  return url.toString().replace(/\/$/, "");
286
288
  };
287
289
  var openUrl = async (url) => {
288
- const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
289
- const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
290
+ const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "powershell.exe" : "xdg-open";
291
+ const args = process.platform === "win32" ? ["-NoProfile", "-NonInteractive", "-Command", "Start-Process -FilePath $args[0]", url] : [url];
290
292
  try {
291
293
  await execFileAsync(command, args);
294
+ return true;
292
295
  } catch {
293
296
  process.stderr.write(`Could not open browser automatically. Use ${url}
294
297
  `);
298
+ return false;
295
299
  }
296
300
  };
297
301
 
@@ -334,7 +338,8 @@ var resources = [
334
338
  aliases: ["page", "content"],
335
339
  defaultFields: ["id", "name", "slug", "language", "instanceId", "disabled", "archived", "alphaProgramIds", "updatedAt"],
336
340
  syncable: true,
337
- dangerousDelete: true
341
+ dangerousDelete: true,
342
+ cacheScopes: ["pages", "pages-knowledge"]
338
343
  },
339
344
  {
340
345
  name: "topics",
@@ -343,7 +348,8 @@ var resources = [
343
348
  aliases: ["topic", "applications", "category-apps", "categories", "thematics", "thematic"],
344
349
  defaultFields: ["id", "name", "slug", "language", "instanceId", "disabled", "archived", "alphaProgramIds", "updatedAt"],
345
350
  syncable: true,
346
- dangerousDelete: true
351
+ dangerousDelete: true,
352
+ cacheScopes: ["applications", "pages", "pages-knowledge"]
347
353
  },
348
354
  {
349
355
  name: "resources",
@@ -352,7 +358,8 @@ var resources = [
352
358
  aliases: ["resource", "ebooks", "e-books", "webinars", "magazines"],
353
359
  defaultFields: ["id", "title", "type", "language", "instanceId", "isActive", "disabled", "archived", "alphaProgramIds", "updatedAt"],
354
360
  syncable: true,
355
- dangerousDelete: true
361
+ dangerousDelete: true,
362
+ cacheScopes: ["pages-knowledge"]
356
363
  },
357
364
  {
358
365
  name: "internal-knowledge",
@@ -361,7 +368,8 @@ var resources = [
361
368
  aliases: ["knowledge", "knowledges"],
362
369
  defaultFields: ["id", "title", "language", "instanceId", "isActive", "isAIAllowed", "disabled", "archived", "alphaProgramIds", "updatedAt"],
363
370
  syncable: true,
364
- dangerousDelete: true
371
+ dangerousDelete: true,
372
+ cacheScopes: ["pages-knowledge"]
365
373
  },
366
374
  {
367
375
  name: "learning-paths",
@@ -370,7 +378,8 @@ var resources = [
370
378
  aliases: ["learning-path", "paths", "path"],
371
379
  defaultFields: ["id", "name", "slug", "language", "instanceId", "isActive", "mandatory", "disabled", "archived", "alphaProgramIds", "updatedAt"],
372
380
  syncable: true,
373
- dangerousDelete: true
381
+ dangerousDelete: true,
382
+ cacheScopes: ["pages", "pages-knowledge"]
374
383
  },
375
384
  {
376
385
  name: "changelogs",
@@ -387,7 +396,8 @@ var resources = [
387
396
  aliases: ["chromebook", "chromebook-game", "chromebook-exercise", "chromebook-games"],
388
397
  defaultFields: ["id", "title", "language", "instanceId", "type", "order", "isActive", "parentId", "sourceExerciseId", "updatedAt"],
389
398
  instanceField: "instanceId",
390
- dangerousDelete: true
399
+ dangerousDelete: true,
400
+ cacheScopes: ["pages", "pages-knowledge"]
391
401
  },
392
402
  {
393
403
  name: "chromebook-steps",
@@ -396,7 +406,8 @@ var resources = [
396
406
  aliases: ["chromebook-step", "chromebook-exercise-steps"],
397
407
  defaultFields: ["id", "exerciseId", "stepNumber", "title", "language", "contentType", "order", "updatedAt"],
398
408
  instanceField: null,
399
- dangerousDelete: true
409
+ dangerousDelete: true,
410
+ cacheScopes: ["pages", "pages-knowledge"]
400
411
  },
401
412
  {
402
413
  name: "project-data",
@@ -438,7 +449,8 @@ var resources = [
438
449
  label: "Instances",
439
450
  aliases: ["instance"],
440
451
  defaultFields: ["id", "name", "URL", "licenceType", "alphaProgramKeys", "createdAt", "updatedAt"],
441
- dangerousDelete: true
452
+ dangerousDelete: true,
453
+ cacheScopes: ["all"]
442
454
  },
443
455
  {
444
456
  name: "alpha-programs",
@@ -454,7 +466,8 @@ var resources = [
454
466
  aliases: ["quiz"],
455
467
  defaultFields: ["id", "title", "language", "instanceId", "mandatory", "isActive", "disabled", "archived", "alphaProgramIds", "updatedAt"],
456
468
  syncable: true,
457
- dangerousDelete: true
469
+ dangerousDelete: true,
470
+ cacheScopes: ["pages", "pages-knowledge"]
458
471
  },
459
472
  {
460
473
  name: "badges",
@@ -463,7 +476,8 @@ var resources = [
463
476
  aliases: ["badge"],
464
477
  defaultFields: ["id", "name", "language", "instanceId", "disabled", "archived", "alphaProgramIds", "updatedAt"],
465
478
  syncable: true,
466
- dangerousDelete: true
479
+ dangerousDelete: true,
480
+ cacheScopes: ["pages", "pages-knowledge"]
467
481
  },
468
482
  {
469
483
  name: "feedbacks",
@@ -505,7 +519,8 @@ var resources = [
505
519
  aliases: ["ambassador", "champions", "champion", "experts", "expert"],
506
520
  defaultFields: ["id", "userId", "active", "descriptionAmbassador", "contactContent", "createdOn"],
507
521
  instanceField: null,
508
- dangerousDelete: true
522
+ dangerousDelete: true,
523
+ cacheScopes: ["pages"]
509
524
  },
510
525
  {
511
526
  name: "tags",
@@ -514,7 +529,8 @@ var resources = [
514
529
  aliases: ["tag"],
515
530
  defaultFields: ["id", "name", "normalizedName", "color", "scope", "ownerInstanceId", "createdAt", "updatedAt"],
516
531
  instanceField: "ownerInstanceId",
517
- dangerousDelete: true
532
+ dangerousDelete: true,
533
+ cacheScopes: ["pages", "pages-knowledge"]
518
534
  },
519
535
  {
520
536
  name: "tag-assignments",
@@ -522,7 +538,8 @@ var resources = [
522
538
  label: "Tag assignments",
523
539
  aliases: ["tag-assignment"],
524
540
  defaultFields: ["id", "tagId", "instanceId", "entityType", "entityId", "createdAt", "updatedAt"],
525
- dangerousDelete: true
541
+ dangerousDelete: true,
542
+ cacheScopes: ["pages", "pages-knowledge"]
526
543
  },
527
544
  {
528
545
  name: "menus",
@@ -531,7 +548,8 @@ var resources = [
531
548
  aliases: ["menu", "menu-items"],
532
549
  defaultFields: ["id", "name", "url", "pageId", "parentId", "instanceId", "disabled", "archived", "alphaProgramIds", "updatedAt"],
533
550
  syncable: true,
534
- dangerousDelete: true
551
+ dangerousDelete: true,
552
+ cacheScopes: ["menu-bundle"]
535
553
  },
536
554
  {
537
555
  name: "menu-sections",
@@ -540,7 +558,8 @@ var resources = [
540
558
  aliases: ["menu-instances"],
541
559
  defaultFields: ["id", "name", "order", "instanceId", "disabled", "archived", "alphaProgramIds"],
542
560
  syncable: true,
543
- dangerousDelete: true
561
+ dangerousDelete: true,
562
+ cacheScopes: ["menu-bundle"]
544
563
  },
545
564
  {
546
565
  name: "workflows",
@@ -549,14 +568,16 @@ var resources = [
549
568
  aliases: ["workflow"],
550
569
  defaultFields: ["id", "name", "triggerType", "isActive", "instanceId", "disabled", "archived", "alphaProgramIds", "updatedAt"],
551
570
  syncable: true,
552
- dangerousDelete: true
571
+ dangerousDelete: true,
572
+ cacheScopes: ["pages", "pages-knowledge"]
553
573
  },
554
574
  {
555
575
  name: "feature-flags",
556
576
  delegate: "featureFlagAssignment",
557
577
  label: "Feature flags",
558
578
  aliases: ["feature-flag", "flags"],
559
- defaultFields: ["id", "featureKey", "targetType", "targetId", "active", "variant", "updatedAt"]
579
+ defaultFields: ["id", "featureKey", "targetType", "targetId", "active", "variant", "updatedAt"],
580
+ cacheScopes: ["all"]
560
581
  },
561
582
  {
562
583
  name: "groups",
@@ -564,7 +585,8 @@ var resources = [
564
585
  label: "Manual groups",
565
586
  aliases: ["group", "manual-groups", "manual-group"],
566
587
  defaultFields: ["id", "name", "description", "instanceId", "isRevert", "createdAt", "updatedAt"],
567
- dangerousDelete: true
588
+ dangerousDelete: true,
589
+ cacheScopes: ["menu-bundle"]
568
590
  },
569
591
  {
570
592
  name: "org-units",
@@ -572,7 +594,8 @@ var resources = [
572
594
  label: "Org units",
573
595
  aliases: ["org-unit", "ou", "ous"],
574
596
  defaultFields: ["id", "name", "code", "type", "googleOuId", "parentId", "instanceId", "instanceCountryParentId", "createdAt", "updatedAt"],
575
- dangerousDelete: true
597
+ dangerousDelete: true,
598
+ cacheScopes: ["menu-bundle"]
576
599
  },
577
600
  {
578
601
  name: "user-org-units",
@@ -581,7 +604,8 @@ var resources = [
581
604
  aliases: ["user-org-unit", "ou-memberships"],
582
605
  defaultFields: ["userId", "orgUnitId", "primary", "assignedAt"],
583
606
  instanceField: null,
584
- dangerousDelete: true
607
+ dangerousDelete: true,
608
+ cacheScopes: ["menu-bundle"]
585
609
  },
586
610
  {
587
611
  name: "ou-admin-scopes",
@@ -598,7 +622,8 @@ var resources = [
598
622
  label: "Entity restriction rules",
599
623
  aliases: ["entity-rules", "content-restriction-rules", "restrictions"],
600
624
  defaultFields: ["id", "instanceId", "entityId", "restrictionMode", "categoryIds", "learningPathRestrictionMode", "learningPathIds", "alphaAllPrograms", "alphaProgramIds", "updatedAt"],
601
- dangerousDelete: true
625
+ dangerousDelete: true,
626
+ cacheScopes: ["menu-bundle", "pages", "pages-knowledge", "applications"]
602
627
  },
603
628
  {
604
629
  name: "users",
@@ -615,7 +640,8 @@ var resources = [
615
640
  aliases: ["access-pass", "passes"],
616
641
  defaultFields: ["id", "userId", "type", "startAt", "expireAt", "givenAt", "createdAt", "updatedAt"],
617
642
  instanceField: "user.instanceID",
618
- dangerousDelete: true
643
+ dangerousDelete: true,
644
+ cacheScopes: ["menu-bundle"]
619
645
  },
620
646
  {
621
647
  name: "analytics",
@@ -687,6 +713,7 @@ var resourceHelpRows = () => resources.map((resource) => ({
687
713
  resource: resource.name,
688
714
  db: resource.delegate,
689
715
  sync: resource.syncable ? "yes" : "no",
716
+ cacheScopes: resource.cacheScopes?.join(", ") || "",
690
717
  aliases: resource.aliases.join(", ")
691
718
  }));
692
719
  // ../../src/cli/commands.ts
@@ -1469,7 +1496,9 @@ var schemaHelp = () => ({
1469
1496
  name: resource.name,
1470
1497
  aliases: resource.aliases,
1471
1498
  defaultFields: resource.defaultFields,
1472
- syncable: Boolean(resource.syncable)
1499
+ syncable: Boolean(resource.syncable),
1500
+ cacheScopes: resource.cacheScopes ?? [],
1501
+ cacheNote: resource.cacheScopes?.length ? "After create/update/delete, visible deploy content may stay stale until these cache scopes are invalidated." : "No deploy-cache scope is listed for this raw resource. Still verify visible product state after writes."
1473
1502
  }))
1474
1503
  });
1475
1504
  var authHelp = () => ({
@@ -1484,6 +1513,8 @@ var skillsHelp = () => ({
1484
1513
  usage: [
1485
1514
  "gskills-admin skills install",
1486
1515
  "gskills-admin skills install --target ~/.codex/skills",
1516
+ "gskills-admin skills install --name gskills-vocabulary",
1517
+ "gskills-admin skills install --name gskills-customer-playbooks",
1487
1518
  "gskills-admin skills install --name gskills-feedback-db-ops",
1488
1519
  "gskills-admin skills path"
1489
1520
  ],
@@ -1593,6 +1624,11 @@ var resourceHelp = (resource) => ({
1593
1624
  `gskills-admin ${resource.name} delete <id> --force --confirm-delete ${resource.name}:<id>`
1594
1625
  ],
1595
1626
  defaultFields: resource.defaultFields,
1627
+ cache: {
1628
+ scopes: resource.cacheScopes ?? [],
1629
+ invalidate: resource.cacheScopes?.length ? `gskills-admin cache invalidate --instance <instanceId> --scope ${resource.cacheScopes[0]} --dry-run` : null,
1630
+ note: resource.cacheScopes?.length ? "After create/update/delete, deploy views may still show cached content. Dry-run and invalidate the relevant scope, then verify the visible page." : "No deploy-cache scope is listed for this raw resource. If the write affects visible content indirectly, use cache scopes to choose a broader invalidation."
1631
+ },
1596
1632
  deleteWarning: "Delete permanently removes production data and requires an exact --confirm-delete token."
1597
1633
  });
1598
1634
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@numericoach/gskills-admin-cli",
3
- "version": "0.1.8",
3
+ "version": "0.1.10",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Admin-only CLI for GSkills super-admin operations.",
@@ -9,6 +9,11 @@ Use this skill when you need to operate GSkills as a super admin from an agent.
9
9
 
10
10
  The CLI is intentionally boring. It logs in through GSkills Auth, calls GSkills API routes, and never asks an agent for a database URL.
11
11
 
12
+ Also install and use the companion skills:
13
+
14
+ - `gskills-vocabulary` when explaining work to admins or writing user-facing summaries.
15
+ - `gskills-customer-playbooks` when the task names a recurring GSkills customer.
16
+
12
17
  ## Install
13
18
 
14
19
  ```bash
@@ -54,6 +59,16 @@ gskills-admin pages update <id> --data '{"disabled":false}' --dry-run --output j
54
59
 
55
60
  5. Apply the exact same command without `--dry-run` only after the payload is correct.
56
61
 
62
+ 6. For visible content changes, check the resource cache hint and refresh cache when needed.
63
+
64
+ ```bash
65
+ gskills-admin pages help --output json
66
+ gskills-admin cache invalidate --instance <instanceId> --scope pages --dry-run --output json
67
+ gskills-admin cache invalidate --instance <instanceId> --scope pages --yes --output json
68
+ ```
69
+
70
+ CRUD help exposes `cache.scopes` for resources that are known to feed deploy caches. After create, update, or delete, the database can be correct while the end-user view is still stale. Use the narrowest listed scope first. Use `all` only when the changed setting affects many deploy surfaces or when the narrow scope did not clear the visible stale state.
71
+
57
72
  Deletes are stricter than other writes. They require both `--force` and an exact confirmation token.
58
73
 
59
74
  ```bash
@@ -258,6 +273,17 @@ gskills-admin cache invalidate --instance <instanceId> --scope menu-bundle --yes
258
273
  gskills-admin cache invalidate --instance <instanceId> --scope all --yes --output json
259
274
  ```
260
275
 
276
+ CRUD resources that expose `cache.scopes` in `gskills-admin <resource> help --output json` should be treated as cached. After a raw write on one of those resources, dry-run the cache invalidation plan, apply it with `--yes`, then re-check the visible product surface.
277
+
278
+ Typical mapping:
279
+
280
+ - courses, tutorials, granules, modules, quizzes, badges, parcours, Chromebook content: `pages`
281
+ - base de connaissance pages and knowledge-facing resources: `pages-knowledge`
282
+ - applications: `applications`, often with `pages` or `pages-knowledge`
283
+ - menus: `menu-bundle`
284
+ - content restrictions and group visibility: usually `menu-bundle`, sometimes `pages`, `pages-knowledge`, or `applications`
285
+ - broad instance settings or feature flags: `all`
286
+
261
287
  ## Feedback Emails
262
288
 
263
289
  Use `send-reply` for the normal email available from the feedback detail dialog. It uses the `GSkillsEmail` template, sends to the feedback user, stores a `FeedbackReply`, updates `repliedAt`, and writes admin logs.
@@ -415,6 +441,36 @@ gskills-admin quiz-attempts list --where '{"user":{"instanceID":"<instanceId>"}}
415
441
 
416
442
  Prefer these read paths for analytics investigation. They are intentionally raw enough to match UI analytics data without giving the agent a DB URL.
417
443
 
444
+ ## User Activity Raw Ops
445
+
446
+ The CLI intentionally exposes user activity as raw authenticated resources, not as a magic repair wizard.
447
+
448
+ Supported raw activity surfaces:
449
+
450
+ - `user-paths`: course, tutorial, granule, or module completion rows.
451
+ - `quiz-attempts`: quiz attempts and completion state.
452
+ - `user-badges`: awarded badges.
453
+ - `user-learning-paths`: parcours progress and completion.
454
+ - `user-learning-path-item-completions`: completed items inside a parcours.
455
+ - `chromebook-progress`: Chromebook game exercise progress.
456
+ - `analytics`: raw activity events used by analytics surfaces.
457
+
458
+ When a super admin asks whether an agent can inspect or fix activity, the answer is yes through these raw resources. Read the user, instance, content row, and existing activity rows first. Use `--dry-run` before writes, then re-read the changed rows.
459
+
460
+ Examples:
461
+
462
+ ```bash
463
+ gskills-admin users list --where '{"email":"user@example.com"}' --fields id,email,name,instanceID --output json
464
+ gskills-admin user-paths list --where '{"userId":"<userId>"}' --output json
465
+ gskills-admin quiz-attempts list --where '{"userId":"<userId>"}' --output json
466
+ gskills-admin user-badges list --where '{"userId":"<userId>"}' --output json
467
+ gskills-admin user-learning-paths list --where '{"userId":"<userId>"}' --output json
468
+ gskills-admin user-learning-path-item-completions list --where '{"userId":"<userId>"}' --output json
469
+ gskills-admin chromebook-progress list --where '{"userId":"<userId>"}' --output json
470
+ ```
471
+
472
+ Raw fixes are allowed, but do not pretend a single row always covers the whole product behavior. For example, a quiz completion can also matter for a parcours, a badge, a workflow, points, or analytics. If the user asked for a visible result, verify the visible result after the raw write.
473
+
418
474
  ## Cache Scope Choice
419
475
 
420
476
  Prefer the narrowest scope:
@@ -0,0 +1,180 @@
1
+ ---
2
+ name: gskills-customer-playbooks
3
+ description: Use when a GSkills task names a recurring customer and the agent needs operational memory about that customer, common requests, likely checks, sync patterns, access quirks, or communication sources.
4
+ ---
5
+
6
+ # GSkills Customer Playbooks
7
+
8
+ Use this skill when the user names a recurring GSkills customer. This is operational memory, not live proof. If the answer or action matters in production, re-check current DB rows, admin logs, sync logs, Slack, Gmail, Google Chat, or the app before acting.
9
+
10
+ ## General Defaults
11
+
12
+ - Start from the customer instance, not from a generic global theory.
13
+ - For broken syncs, compare the target instance against global and against a working synced sibling when useful.
14
+ - For feedbacks, inspect the feedback row, user, instance, and admin logs before explaining the cause.
15
+ - For access issues, check user instance, access passes, auth mode, domain or account allowlists, then logs.
16
+ - For client wording, use the real thread or channel when available.
17
+ - Use `gskills-vocabulary` before writing human-facing summaries.
18
+
19
+ ## Air Liquide
20
+
21
+ Air Liquide is the heavy recurring customer. Expect large content volume, customized content, language constraints, and auth or Google Admin setup work.
22
+
23
+ Common work:
24
+
25
+ - Broad content synchronisation from global, often with thousands of items.
26
+ - Large diffs with many `SKIPPED_CUSTOMIZED` items. This is normal, not automatically a failure.
27
+ - Page, quiz, parcours, menu, resource, badge, and internal knowledge parity checks after sync.
28
+ - Feedback instance attribution and page-family parity repairs.
29
+ - Access-denied work around expired access passes or domain allowlists.
30
+ - Okta setup and auth callback checks.
31
+ - Google Admin users, groups, and OU checks. Users and groups have worked before while OU access required scope/config follow-up.
32
+ - Locale and wording work, especially Quebec French.
33
+ - Short natural client-facing email drafts from the actual thread.
34
+
35
+ Known context:
36
+
37
+ - Customer id used during Google Admin checks: `C028v0b9g`.
38
+ - Known Google Chat space: `Air Liquide x Numericoach - GSkills`, `spaces/AAQAc2CT1qI`.
39
+ - Harold OUSSET was a known user whose display name required surname-first parsing.
40
+ - Air Liquide syncs should usually start with `sync logs`, then `sync diff`, then a narrow or preset run.
41
+
42
+ ## HASAP
43
+
44
+ HASAP often appears in feedback and content visibility work.
45
+
46
+ Common work:
47
+
48
+ - Webinar content, parcours updates, invitations, user imports, and client-side launch follow-up.
49
+ - Badge visibility and badge delivery repairs.
50
+ - Google Forms badge issues where the page trigger stayed the same but the badge target changed.
51
+ - Quiz completion and answer submission investigations.
52
+ - Page sync visibility issues where disabled or archived state and sync logs mattered.
53
+
54
+ Known context:
55
+
56
+ - Known Google Chat space: `GSkills_Hasap_x_Numericoach`, `spaces/AAQAxJEETeI`.
57
+ - The recurring badge pitfall is workflow deduplication. A same-page `QUIZ_COMPLETED` execution can block a new badge action if only the badge target changed.
58
+ - Do not explain HASAP sync issues from the URL alone. Use prod data, the exact sync run, `LogsUser`, and the page or parcours family.
59
+
60
+ ## FM LOGISTIC Google & Co
61
+
62
+ FM Logistic work is usually about resources, webinars, and visibility rules.
63
+
64
+ Known fixed facts:
65
+
66
+ - Instance name: `FM LOGISTIC Google & Co`.
67
+ - Instance id: `cmgtgrz02000t04l501wbp459`.
68
+ - Instance slug: `fm-logistic`.
69
+ - Main language: `fr`.
70
+
71
+ Common work:
72
+
73
+ - Add or audit webinar replays.
74
+ - Upload Drive recordings to GCS-backed GSkills resources.
75
+ - Keep AI webinars restricted to the right audience.
76
+ - Verify the end-user webinar page and custom video player.
77
+
78
+ Important rule:
79
+
80
+ - AI webinars should keep the French `IA` application/category attached.
81
+ - FM has a manual group named `Groupe AVEC IA` with inverted visibility. Do not add a broad active application like Google Workspace unless the user explicitly wants broader access.
82
+
83
+ Use the `fm-logistic-webinar-ingestion` skill for detailed webinar work.
84
+
85
+ ## LGCF
86
+
87
+ LGCF often appears in technical rollout, Google Group access, feedback, and success-story work.
88
+
89
+ Common work:
90
+
91
+ - Google Chat and Gmail context checks before drafting client replies.
92
+ - Security group or Google Group behavior.
93
+ - Progression quiz feedback.
94
+ - Leaderboard and adjusted-points investigations, especially when unavailable quiz history changes visible ranking.
95
+ - Success-story outreach drafts.
96
+
97
+ Known context:
98
+
99
+ - Known Google Chat space: `LGCF & Numericoach | GSkills Technique IT`, `spaces/AAQACgXH1kQ`.
100
+ - A known feedback case involved leaderboard ordering versus raw points. Verify whether the complaint is raw progress, visible ranking, adjusted points, or course activity before digging.
101
+
102
+ ## V&B
103
+
104
+ V&B has appeared in feedback triage around evaluation quiz behavior.
105
+
106
+ Common work:
107
+
108
+ - Quiz or evaluation feedback checks.
109
+ - Treat as a feedback-backed investigation. Verify the exact feedback row and current quiz state before describing the issue.
110
+
111
+ ## Seine Yonne
112
+
113
+ Seine Yonne has appeared in access/login diagnosis.
114
+
115
+ Common work:
116
+
117
+ - Granular account allowlist checks.
118
+ - Login denial troubleshooting.
119
+
120
+ Known context:
121
+
122
+ - One prior issue was that `dmoindrot@farmidable.fr` was not in `accountGranular`, while `dmoindrot@seineyonne.fr` was.
123
+ - Do not collapse similar emails into one access story.
124
+
125
+ ## Euromaster
126
+
127
+ Euromaster has appeared in sync and broad repair work.
128
+
129
+ Common work:
130
+
131
+ - Page-only or pages plus parcours synchronisation.
132
+ - Post-sync verification.
133
+ - Data repair blast-radius checks.
134
+
135
+ ## Commune de Divonne-les-Bains, AS de Pic, 360 Courtage
136
+
137
+ These have appeared as new-client style pushes.
138
+
139
+ Common work:
140
+
141
+ - Broad first synchronisation from global.
142
+ - High created counts are expected.
143
+ - Run `client-content` diff first, then apply, then verify menus and deploy cache.
144
+
145
+ ## Nickel Banque
146
+
147
+ Nickel Banque has appeared in feedback instance selection and page-family parity context.
148
+
149
+ Common work:
150
+
151
+ - Feedback routing or instance attribution checks.
152
+ - Verify the actual route context, target instance, and content family before repairing.
153
+
154
+ ## Terega
155
+
156
+ Terega has appeared as a one-off client synchronisation target.
157
+
158
+ Common work:
159
+
160
+ - Treat as normal client-content sync unless the live logs say otherwise.
161
+ - Resolve the instance id and check recent sync logs before applying.
162
+
163
+ ## Euralis, Orqual, Groupe Kiosque, UTT Yarns
164
+
165
+ These have appeared in broad data repair blast-radius checks.
166
+
167
+ Common work:
168
+
169
+ - Verify current state before touching anything.
170
+ - Do not infer a recurring product rule only because they were touched by a previous multi-instance repair.
171
+
172
+ ## Instance Mere And Global
173
+
174
+ Global is the source of truth for shared content.
175
+
176
+ Common work:
177
+
178
+ - Create or update global courses, tutorials, granules, modules, quizzes, parcours, badges, menus, resources, and base de connaissance content.
179
+ - Compare global to a client instance before sync.
180
+ - Keep client customizations intact unless the user explicitly wants to overwrite or repair them.
@@ -0,0 +1,97 @@
1
+ ---
2
+ name: gskills-vocabulary
3
+ description: Use when an agent explains GSkills operations to admins, writes summaries after CLI work, drafts messages about GSkills entities, or translates raw CLI/database concepts into the product vocabulary.
4
+ ---
5
+
6
+ # GSkills Vocabulary
7
+
8
+ Use this skill whenever you talk to a human about GSkills operations. The CLI is not the story. It is just a way for an authorized agent to contact GSkills servers.
9
+
10
+ ## Core Rule
11
+
12
+ Never make the conversation sound technical unless the user explicitly asks for implementation details.
13
+
14
+ Good:
15
+
16
+ - "J'ai demandé a GSkills de mettre a jour le parcours."
17
+ - "Je vais verifier les feedbacks et l'activite de l'utilisateur."
18
+ - "Le contenu est pret a etre pousse vers Air Liquide."
19
+
20
+ Avoid with non-dev admins:
21
+
22
+ - "J'ai appele l'API."
23
+ - "J'ai modifie une ressource CRUD."
24
+ - "La table Prisma a ete update."
25
+ - "Le payload JSON a ete envoye."
26
+ - "Le CLI a mute la row."
27
+
28
+ Commands, ids, JSON, and table names are fine in command blocks or agent notes. Translate them before speaking to admins.
29
+
30
+ ## Product Vocabulary
31
+
32
+ - `learning path` means `parcours` in French.
33
+ - `category app`, `category application`, and `thematic` are spoken as `application`.
34
+ - `page` is usually not spoken as `page`. Prefer the pedagogical word that fits the context: `cours`, `tutoriel`, `granule`, or `module`.
35
+ - `tickets` are `feedbacks`.
36
+ - `base de co` and `base de connaissance` mean the end-user internal knowledge area. It regroups tutorial content, internal knowledge videos, webinars, documents, guides, and other resources.
37
+ - `internal knowledge` is `base de connaissance` or `contenu de base de connaissance` depending on the sentence.
38
+ - `resources` are `ressources`, such as webinars, replays, guides, documents, magazines, or useful links.
39
+ - `access pass` is an `acces`.
40
+ - `entity`, `group`, `org unit`, and `Google group` should become `groupe`, `groupe Google`, or `OU` depending on the real object.
41
+ - `feature flag` should usually become `parametre`, `option`, or `activation`.
42
+ - `workflow` should usually become `automatisation`.
43
+ - `cache invalidate` should become `rafraichir le cache` or `rafraichir le contenu`.
44
+ - `sync` should become `synchronisation` or `pousser le contenu`.
45
+ - `global` is the source instance or `instance mere`, not a customer.
46
+ - `instance` can stay `instance` with internal admins, but for clients prefer `espace client` or the client name.
47
+
48
+ ## Speaking About Activity
49
+
50
+ Use product words:
51
+
52
+ - `user-paths` means completed courses, tutorials, granules, or modules.
53
+ - `quiz-attempts` means quiz attempts and quiz completion.
54
+ - `user-badges` means badges obtained by the user.
55
+ - `user-learning-paths` means parcours progress.
56
+ - `user-learning-path-item-completions` means completed steps inside a parcours.
57
+ - `chromebook-progress` means Chromebook game progress.
58
+
59
+ Do not tell a non-dev admin "I updated user-paths". Say the user is now marked as having completed the course, then mention the technical row only if the user asks for proof.
60
+
61
+ ## Examples
62
+
63
+ Technical note:
64
+
65
+ ```text
66
+ Updated user-paths row cm... with isAchieved=true.
67
+ ```
68
+
69
+ Admin-facing wording:
70
+
71
+ ```text
72
+ J'ai marque le cours comme termine pour l'utilisateur et j'ai reverifie son activite.
73
+ ```
74
+
75
+ Technical note:
76
+
77
+ ```text
78
+ Ran sync diff with preset client-content.
79
+ ```
80
+
81
+ Admin-facing wording:
82
+
83
+ ```text
84
+ J'ai compare le contenu a pousser avant de lancer la synchronisation.
85
+ ```
86
+
87
+ Technical note:
88
+
89
+ ```text
90
+ Invalidated pages cache.
91
+ ```
92
+
93
+ Admin-facing wording:
94
+
95
+ ```text
96
+ J'ai rafraichi le contenu pour que les changements remontent cote utilisateur.
97
+ ```