@numericoach/gskills-admin-cli 0.1.17 → 0.1.19

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
@@ -65,12 +65,19 @@ gskills-admin translate knowledge-video <knowledgeId> --from en --to es --yes --
65
65
  ```
66
66
 
67
67
  Supported kinds are `pages`, `quizzes`, `topics`, `badges`, `menus`, `menu-sections`, `internal-knowledge`, `knowledge-video`, `learning-paths`, and `chromebook-exercises`.
68
+ Target languages must be explicit. `--to all` is rejected.
68
69
 
69
70
  Operational helpers are available for the admin-only flows agents should not improvise:
70
71
 
71
72
  ```bash
73
+ gskills-admin feedback inspect <feedbackId> --output json
74
+ gskills-admin feedback translation-status <feedbackId> --output json
72
75
  gskills-admin feedback send-reply <feedbackId> --subject "GSkills - ..." --body-file ./reply.txt --dry-run --output json
76
+ gskills-admin access diagnose --email user@example.com --instance <instanceId> --output json
73
77
  gskills-admin access grant --user <userId> --type DEFAULT --dry-run --output json
78
+ gskills-admin internal-knowledge sync-media --source global --since today --languages fr --all-targets --dry-run --output json
79
+ gskills-admin admin-ingest repair-state --instance <instanceId> --output json
80
+ gskills-admin admin-ingest repair --instance <instanceId> --dry-run --output json
74
81
  gskills-admin instances create-plan --output json
75
82
  gskills-admin instances create --data '{"name":"Client","URL":"client","licenceType":"STARTER","tokensAllowed":50}' --dry-run --output json
76
83
  gskills-admin entities list --instance <instanceId> --output json
@@ -83,6 +90,8 @@ gskills-admin ambassadors label --instance <instanceId> --language fr --output j
83
90
 
84
91
  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.
85
92
 
93
+ `internal-knowledge sync-media` changes only selected media fields on existing target copies matched by `sourceKnowledgeId`. The default field is `url`, and it invalidates `pages-knowledge` cache for touched instances.
94
+
86
95
  Raw project and analytics data can be read or adjusted through resources such as `project-data`, `ticket-sla-rules`, `learning-path-items`, `learning-path-groups`, `quiz-questions`, `quiz-options`, `analytics`, `quiz-attempts`, `user-paths`, `chromebook-progress`, `user-badges`, `user-learning-paths`, and `user-learning-path-item-completions`.
87
96
 
88
97
  ## Agent skill
@@ -782,6 +782,8 @@ var runCommand = async (ctx) => {
782
782
  return runFeedbackCommand(actionOrResource, maybeAction, ctx);
783
783
  if (group === "access")
784
784
  return runAccessCommand(actionOrResource, ctx);
785
+ if (group === "admin-ingest")
786
+ return runAdminIngestCommand(actionOrResource, ctx);
785
787
  if (group === "entities")
786
788
  return runEntitiesCommand(actionOrResource, maybeAction, ctx);
787
789
  if (group === "org-units-sync")
@@ -828,6 +830,9 @@ var runAuthCommand = async (action, ctx) => {
828
830
  var runResourceCommand = async (resource, action, maybeId, _rest, ctx) => {
829
831
  if (!action || action === "help")
830
832
  return resourceHelp(resource);
833
+ if (resource.name === "internal-knowledge" && action === "sync-media") {
834
+ return runKnowledgeSyncMediaCommand(ctx);
835
+ }
831
836
  if (action === "list")
832
837
  return listResource(resource, ctx);
833
838
  if (action === "get") {
@@ -964,9 +969,17 @@ var deleteResource = async (resource, id, ctx) => {
964
969
  var runFeedbackCommand = async (action, feedbackId, ctx) => {
965
970
  if (!action || action === "help")
966
971
  return feedbackHelp();
972
+ if ((action === "inspect" || action === "translation-status") && !feedbackId) {
973
+ throw new CliError("Missing feedback id or URL", 2);
974
+ }
967
975
  if ((action === "claim" || action === "send-claim") && !feedbackId) {
968
976
  throw new CliError("Missing feedback id", 2);
969
977
  }
978
+ if (action === "inspect" || action === "translation-status") {
979
+ const searchParams = new URLSearchParams;
980
+ searchParams.set("ref", feedbackId);
981
+ return requestApi(`/api/cli/feedback/${action}?${searchParams.toString()}`);
982
+ }
970
983
  if (action === "claim") {
971
984
  return requestApi("/api/cli/feedback/claim", {
972
985
  method: "POST",
@@ -1051,6 +1064,21 @@ var runInstanceCreationCommand = async (action, ctx) => {
1051
1064
  var runAccessCommand = async (action, ctx) => {
1052
1065
  if (!action || action === "help")
1053
1066
  return accessHelp();
1067
+ if (action === "diagnose") {
1068
+ const userId = getStringFlag(ctx, "user");
1069
+ const email = getStringFlag(ctx, "email");
1070
+ if (!userId && !email)
1071
+ throw new CliError("Missing --user or --email", 2);
1072
+ const searchParams = new URLSearchParams;
1073
+ if (userId)
1074
+ searchParams.set("userId", userId);
1075
+ if (email)
1076
+ searchParams.set("email", email);
1077
+ const instance = getStringFlag(ctx, "instance");
1078
+ if (instance)
1079
+ searchParams.set("instance", instance);
1080
+ return requestApi(`/api/cli/access/diagnose?${searchParams.toString()}`);
1081
+ }
1054
1082
  if (action === "grant") {
1055
1083
  const userId = getStringFlag(ctx, "user");
1056
1084
  if (!userId)
@@ -1087,6 +1115,62 @@ var runAccessCommand = async (action, ctx) => {
1087
1115
  }
1088
1116
  throw new CliError(`Unknown access command "${action}"`, 2);
1089
1117
  };
1118
+ var runAdminIngestCommand = async (action, ctx) => {
1119
+ if (!action || action === "help")
1120
+ return adminIngestHelp();
1121
+ if (action === "repair-state") {
1122
+ const instanceId = getStringFlag(ctx, "instance");
1123
+ if (!instanceId)
1124
+ throw new CliError("Missing --instance", 2);
1125
+ return requestApi(`/api/cli/admin-ingest/repair-state?instanceId=${encodeURIComponent(instanceId)}`);
1126
+ }
1127
+ if (action === "repair") {
1128
+ const instanceId = getStringFlag(ctx, "instance");
1129
+ if (!instanceId)
1130
+ throw new CliError("Missing --instance", 2);
1131
+ if (hasFlag(ctx, "dry-run")) {
1132
+ return requestApi(`/api/cli/admin-ingest/repair-state?instanceId=${encodeURIComponent(instanceId)}`);
1133
+ }
1134
+ if (!hasFlag(ctx, "yes")) {
1135
+ throw new CliError("Admin ingest repair queues production workflows. Add --yes or use --dry-run.", 2);
1136
+ }
1137
+ return requestApi("/api/cli/admin-ingest/repair", {
1138
+ method: "POST",
1139
+ body: JSON.stringify({ instanceId })
1140
+ });
1141
+ }
1142
+ throw new CliError(`Unknown admin-ingest command "${action}"`, 2);
1143
+ };
1144
+ var runKnowledgeSyncMediaCommand = async (ctx) => {
1145
+ const targetInstanceIds = getTargetInstanceIds(ctx);
1146
+ const allTargets = hasFlag(ctx, "all-targets");
1147
+ if (targetInstanceIds.length === 0 && !allTargets) {
1148
+ throw new CliError("Missing --target, --targets, or --all-targets", 2);
1149
+ }
1150
+ if (targetInstanceIds.length > 0 && allTargets) {
1151
+ throw new CliError("Use either --target/--targets or --all-targets, not both", 2);
1152
+ }
1153
+ if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
1154
+ throw new CliError("Knowledge media sync writes production data. Add --yes or use --dry-run.", 2);
1155
+ }
1156
+ return requestApi("/api/cli/internal-knowledge/sync-media", {
1157
+ method: "POST",
1158
+ body: JSON.stringify({
1159
+ sourceInstanceId: getStringFlag(ctx, "source") ?? "global",
1160
+ targetInstanceIds,
1161
+ allTargets,
1162
+ languages: splitCsv(getStringFlag(ctx, "languages")),
1163
+ since: getStringFlag(ctx, "since") ?? getStringFlag(ctx, "updated-after") ?? "today",
1164
+ fields: splitCsv(getStringFlag(ctx, "fields")).length > 0 ? splitCsv(getStringFlag(ctx, "fields")) : ["url"],
1165
+ mime: getStringFlag(ctx, "mime") ?? "video",
1166
+ sourceType: getStringFlag(ctx, "source-type") ?? "UPLOAD",
1167
+ includeDisabled: hasFlag(ctx, "include-disabled"),
1168
+ includeArchived: hasFlag(ctx, "include-archived"),
1169
+ skipCache: hasFlag(ctx, "no-cache"),
1170
+ dryRun: hasFlag(ctx, "dry-run")
1171
+ })
1172
+ });
1173
+ };
1090
1174
  var runEntitiesCommand = async (action, entityId, ctx) => {
1091
1175
  if (!action || action === "help")
1092
1176
  return entitiesHelp();
@@ -1291,6 +1375,9 @@ var runTranslateCommand = async (kind, id, ctx) => {
1291
1375
  const targetLanguages = splitCsv(getStringFlag(ctx, "to") ?? getStringFlag(ctx, "languages"));
1292
1376
  if (targetLanguages.length === 0)
1293
1377
  throw new CliError("Missing --to", 2);
1378
+ if (targetLanguages.some((language) => language.toLowerCase() === "all")) {
1379
+ throw new CliError("Do not use --to all. Pass explicit target languages like --to en,es,pt-BR.", 2);
1380
+ }
1294
1381
  if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
1295
1382
  throw new CliError("AI translation writes content. Add --yes or use --dry-run.", 2);
1296
1383
  }
@@ -1554,7 +1641,8 @@ var rootHelp = () => ({
1554
1641
  `gskills-admin pages update <id> --data '{"disabled":true}'`,
1555
1642
  "gskills-admin pages delete <id> --force --confirm-delete pages:<id> # soft-disables only",
1556
1643
  "gskills-admin sync run --target <instanceId> --only pages,quizzes --yes",
1557
- "gskills-admin translate pages <id> --to en,es --dry-run"
1644
+ "gskills-admin translate pages <id> --to en,es --dry-run",
1645
+ "gskills-admin internal-knowledge sync-media --since today --languages fr --all-targets --dry-run"
1558
1646
  ],
1559
1647
  resources: resources.map((resource) => resource.name),
1560
1648
  output: "Use --output json, --output jsonl, --output table, or --output markdown. Piped output defaults to JSON.",
@@ -1587,11 +1675,17 @@ var schemaHelp = () => ({
1587
1675
  { name: "cache scopes", writes: false },
1588
1676
  { name: "cache invalidate", required: ["--instance"], flags: ["--scope", "--languages", "--yes", "--dry-run"], writes: true },
1589
1677
  { name: "translate", args: ["kind", "id?"], required: ["--to"], flags: ["--ids", "--all", "--instance", "--from", "--where", "--take", "--mode", "--source-history", "--yes", "--dry-run"], writes: true },
1678
+ { name: "internal-knowledge sync-media", flags: ["--source", "--target", "--targets", "--all-targets", "--languages", "--since", "--updated-after", "--fields", "--mime", "--source-type", "--include-disabled", "--include-archived", "--no-cache", "--yes", "--dry-run"], writes: true },
1679
+ { name: "feedback inspect", args: ["feedbackId or URL"], writes: false },
1680
+ { name: "feedback translation-status", args: ["feedbackId or URL"], writes: false },
1590
1681
  { name: "feedback claim", args: ["feedbackId"], flags: ["--dry-run"], writes: true },
1591
1682
  { name: "feedback send-claim", args: ["feedbackId"], flags: ["--recipient-email", "--recipient-name", "--cc", "--subject", "--body", "--yes", "--dry-run"], writes: true },
1592
1683
  { name: "feedback send-reply", args: ["feedbackId"], flags: ["--subject", "--subject-file", "--body-file", "--translated-subject", "--translated-subject-file", "--translated-body-file", "--user-language", "--current-language", "--yes", "--dry-run"], writes: true },
1684
+ { name: "access diagnose", required: ["--user or --email"], flags: ["--instance"], writes: false },
1593
1685
  { name: "access grant", required: ["--user"], flags: ["--type", "--start-at", "--custom-duration-days", "--preferred-language", "--yes", "--dry-run"], writes: true },
1594
1686
  { name: "access revoke-active", required: ["--user"], flags: ["--yes", "--dry-run"], writes: true },
1687
+ { name: "admin-ingest repair-state", required: ["--instance"], writes: false },
1688
+ { name: "admin-ingest repair", required: ["--instance"], flags: ["--yes", "--dry-run"], writes: true },
1595
1689
  { name: "instances create-plan", writes: false },
1596
1690
  { name: "instances create", flags: ["--data", "--yes", "--dry-run"], writes: true },
1597
1691
  { name: "entities list", required: ["--instance"], flags: ["--language"], writes: false },
@@ -1697,7 +1791,7 @@ var translateHelp = () => ({
1697
1791
  selection: "Pass one id, --ids for several source rows, or --all with optional --instance, --from, --where and --take.",
1698
1792
  warning: PAGE_TRANSLATION_REWRITE_WARNING,
1699
1793
  patchMode: "For pages, --mode patch uses source page history to update changed translatable text while preserving target non-text block data such as activity ids, quiz ids, embedded ids, files, and future custom fields. It updates existing translations only and fails when no previous source history exists.",
1700
- note: "Uses the same AI translation helpers as the editors. Dry-run plans the write without calling AI."
1794
+ note: "Uses the same AI translation helpers as the editors. Dry-run plans the write without calling AI. Pass explicit target languages. --to all is intentionally rejected."
1701
1795
  });
1702
1796
  var PAGE_TRANSLATION_REWRITE_WARNING = "WARNING: translate pages is a full translated-page rewrite, not a diff update. Rebuilding target pages can lose activity-specific fields, quiz ids, embedded ids, or future custom block data if the translator does not preserve them. Prefer the app diff update flow for pages with activities or custom blocks.";
1703
1797
  var addTranslatePagesWarning = (kind, mode, result) => {
@@ -1714,6 +1808,9 @@ var addTranslatePagesWarning = (kind, mode, result) => {
1714
1808
  };
1715
1809
  var feedbackHelp = () => ({
1716
1810
  usage: [
1811
+ "gskills-admin feedback inspect <feedbackId>",
1812
+ "gskills-admin feedback inspect 'https://client.g-skills.fr/fr/...'",
1813
+ "gskills-admin feedback translation-status <feedbackId>",
1717
1814
  "gskills-admin feedback send-reply <feedbackId> --subject 'GSkills - ...' --body-file ./reply.fr.txt --dry-run",
1718
1815
  "gskills-admin feedback send-reply <feedbackId> --subject 'GSkills - ...' --body-file ./reply.fr.txt --yes",
1719
1816
  "gskills-admin feedback claim <feedbackId> --dry-run",
@@ -1722,6 +1819,14 @@ var feedbackHelp = () => ({
1722
1819
  ],
1723
1820
  note: "send-reply is the normal feedback detail email template flow. claim/send-claim is only the SLA ticket-taken-in-charge flow."
1724
1821
  });
1822
+ var adminIngestHelp = () => ({
1823
+ usage: [
1824
+ "gskills-admin admin-ingest repair-state --instance <instanceId>",
1825
+ "gskills-admin admin-ingest repair --instance <instanceId> --dry-run",
1826
+ "gskills-admin admin-ingest repair --instance <instanceId> --yes"
1827
+ ],
1828
+ note: "repair-state reads the same historical repair planner as the admin-console data UI. repair queues the existing repair catchup workflow."
1829
+ });
1725
1830
  var instanceCreateHelp = () => ({
1726
1831
  usage: [
1727
1832
  "gskills-admin instances create-plan --output json",
@@ -1753,6 +1858,8 @@ var instanceCreateHelp = () => ({
1753
1858
  });
1754
1859
  var accessHelp = () => ({
1755
1860
  usage: [
1861
+ "gskills-admin access diagnose --email user@example.com --instance <instanceId>",
1862
+ "gskills-admin access diagnose --user <userId>",
1756
1863
  "gskills-admin access grant --user <userId> --type DEFAULT --dry-run",
1757
1864
  "gskills-admin access grant --user <userId> --type PASS_90_DAYS --preferred-language fr --yes",
1758
1865
  "gskills-admin access revoke-active --user <userId> --yes"
@@ -1788,7 +1895,8 @@ var resourceHelp = (resource) => ({
1788
1895
  `gskills-admin ${resource.name} get <id>`,
1789
1896
  `gskills-admin ${resource.name} create --data '{"instanceId":"global"}'`,
1790
1897
  `gskills-admin ${resource.name} update <id> --data '{"disabled":true}'`,
1791
- `gskills-admin ${resource.name} delete <id> --force --confirm-delete ${resource.name}:<id>`
1898
+ `gskills-admin ${resource.name} delete <id> --force --confirm-delete ${resource.name}:<id>`,
1899
+ ...resource.name === "internal-knowledge" ? [`gskills-admin ${resource.name} sync-media --since today --languages fr --all-targets --dry-run`] : []
1792
1900
  ],
1793
1901
  defaultFields: resource.defaultFields,
1794
1902
  cache: {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@numericoach/gskills-admin-cli",
3
- "version": "0.1.17",
3
+ "version": "0.1.19",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Admin-only CLI for GSkills super-admin operations.",
@@ -80,6 +80,20 @@ Never add `--confirm-delete` unless the user explicitly asked to remove somethin
80
80
 
81
81
  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"`.
82
82
 
83
+ ## CLI Plus Code Rule
84
+
85
+ Most agents do not have Theo's direct production DB access. Treat the CLI as the production access layer.
86
+
87
+ Good pattern:
88
+
89
+ 1. Use `gskills-admin schema`, resource reads, and specialized commands first.
90
+ 2. If the operation needs custom logic, inspect the app code and add or use an authenticated CLI API route.
91
+ 3. Keep the write path behind `--dry-run` and `--yes`.
92
+ 4. Log admin-visible writes and invalidate deploy cache when the data affects visible content.
93
+ 5. Publish the CLI and bundled skills when a recurring DB-only workaround becomes a normal operation.
94
+
95
+ Do not ask an agent for `DATABASE_URL` and do not write a one-off direct DB script when the same job will happen again. Code is still useful, but it should live behind the CLI or a reusable app helper.
96
+
83
97
  ## Instance Rules
84
98
 
85
99
  If `--instance` is omitted, content-like resources default to `instanceId = "global"`.
@@ -175,6 +189,8 @@ gskills-admin translate knowledge-video <knowledgeId> --from en --to es --yes --
175
189
 
176
190
  Always dry-run first. Dry-run lists planned rows and target languages without calling AI or writing data. Real runs require `--yes`.
177
191
 
192
+ Never use `--to all`. The CLI rejects it because target languages must be explicit.
193
+
178
194
  Warning for pages: `translate pages` rewrites each translated page from the source page. It is not a diff update. Recreating translated pages this way can lose activity-specific fields, quiz ids, embedded ids, or future custom block data if the translator does not preserve them. Prefer the app diff update flow for pages with activities or custom blocks.
179
195
 
180
196
  For pages with activities or custom blocks, prefer `--mode patch`. It uses the source page history to update changed translatable text while preserving target non-text block data such as activity ids, quiz ids, embedded ids, files, and future custom fields. It updates existing translations only and fails when no previous source history exists.
@@ -232,6 +248,23 @@ Common presets:
232
248
  - `pages-learning-paths`: refinement pass after broad syncs.
233
249
  - `knowledge-resources-paths`: narrow asset and learning path rerun.
234
250
 
251
+ ## Knowledge Media Sync
252
+
253
+ Use this when existing internal knowledge copies already exist on client instances and only the referenced media changed on global.
254
+
255
+ Default behavior changes only `url` on existing target copies matched by `sourceKnowledgeId`. It does not create knowledge rows and does not change activities, metadata, tags, categories, active state, parent links, or AI flags.
256
+
257
+ ```bash
258
+ gskills-admin internal-knowledge sync-media --source global --since today --languages fr --all-targets --dry-run --output json
259
+ gskills-admin internal-knowledge sync-media --source global --since today --languages fr --all-targets --yes --output json
260
+ ```
261
+
262
+ Use `--target <instanceId>` or `--targets <id,id>` instead of `--all-targets` for a smaller run.
263
+
264
+ Use `--fields url,updatedAt` only when the visible update date must mirror the source. The safer default is `url` only.
265
+
266
+ The command invalidates `pages-knowledge` for touched instances unless `--no-cache` is passed.
267
+
235
268
  ## Marina Sync Playbook
236
269
 
237
270
  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.
@@ -340,6 +373,16 @@ Typical mapping:
340
373
 
341
374
  ## Feedback Emails
342
375
 
376
+ Use `inspect` before investigating feedback through direct DB access. It returns the feedback row, user, instance, route metadata, analysis, assignees, recent replies and comments.
377
+
378
+ ```bash
379
+ gskills-admin feedback inspect <feedbackId> --output json
380
+ gskills-admin feedback inspect 'https://client.g-skills.fr/fr/...' --output json
381
+ gskills-admin feedback translation-status <feedbackId> --output json
382
+ ```
383
+
384
+ `translation-status` is useful when `translatedFr` exists but may simply be the original text after a translator fallback.
385
+
343
386
  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.
344
387
 
345
388
  Production reality from the latest 50 `FeedbackReply` rows checked on 2026-05-13: all reply bodies were multi-line, usually 9-13 lines with paragraph breaks. Translated PT/ES replies were multi-line too. Therefore, real feedback replies must use `--body-file`; never put the body inline in the shell.
@@ -407,6 +450,15 @@ Use dry-run to inspect the full plan and warnings. The real run creates the inst
407
450
 
408
451
  ## Accesses
409
452
 
453
+ Use `access diagnose` before granting, revoking, or asking for direct DB inspection.
454
+
455
+ ```bash
456
+ gskills-admin access diagnose --email user@example.com --instance <instanceId> --output json
457
+ gskills-admin access diagnose --user <userId> --output json
458
+ ```
459
+
460
+ It reports the user instance, active passes, upcoming passes, role bypass, automatic instance gate and Google group membership facts.
461
+
410
462
  Use `access grant` and `access revoke-active` instead of raw `access-passes` writes when the operation should trigger workflows and admin logs.
411
463
 
412
464
  ```bash
@@ -418,6 +470,18 @@ gskills-admin access revoke-active --user <userId> --yes --output json
418
470
 
419
471
  Types are `DEFAULT`, `PASS_90_DAYS`, `PASS_12_MONTHS`, `CUSTOM`, and `UNLIMITED`.
420
472
 
473
+ ## Admin Ingest Repair
474
+
475
+ Use this when the UI says synchronisations incomplètes or admin console data has repair tasks.
476
+
477
+ ```bash
478
+ gskills-admin admin-ingest repair-state --instance <instanceId> --output json
479
+ gskills-admin admin-ingest repair --instance <instanceId> --dry-run --output json
480
+ gskills-admin admin-ingest repair --instance <instanceId> --yes --output json
481
+ ```
482
+
483
+ `repair-state` reads the same planner as the admin-console data UI. `repair --yes` queues the existing repair catchup workflow and writes an admin log. Do not run the old direct `bun --conditions react-server` repair snippet unless the CLI path is unavailable in the deployed version.
484
+
421
485
  ## Entities And Restrictions
422
486
 
423
487
  Entities are the shared segmentation layer for manual groups, Google groups, and Google Admin OUs.
@@ -554,4 +618,4 @@ Prefer the narrowest scope:
554
618
  - `--take 100` when inventory matters
555
619
  - explicit `--fields` to avoid dumping huge content JSON
556
620
  - explicit `--where` instead of fuzzy reasoning in prose
557
- - no direct DB unless the user specifically asks for DB inspection or repair
621
+ - no direct DB for normal agents. If the CLI lacks the recurring operation, add the CLI route or reusable helper first
@@ -9,6 +9,8 @@ Use this for Codex-backed maintenance of GSkills content data.
9
9
 
10
10
  This is not about UI visits. It is about proving and fixing content state with DB, sync logs, cache helpers, and production verification.
11
11
 
12
+ For normal agents, use `gskills-admin` as the production access layer. If the old fix required direct DB or a repo script, first check whether the CLI now exposes that operation.
13
+
12
14
  ## What Codex Has Actually Been Used For
13
15
 
14
16
  - Investigating a Google Contacts page sync issue where source global content was published but client copies stayed disabled.
@@ -91,6 +93,24 @@ Known validated shape:
91
93
  - Before: 49,338 mapped pages, 25,611 mismatches.
92
94
  - After: 0 mismatches.
93
95
 
96
+ ## Knowledge Media Reference Sync
97
+
98
+ Use this when global internal knowledge videos changed and client copies already exist.
99
+
100
+ ```bash
101
+ gskills-admin internal-knowledge sync-media --source global --since today --languages fr --all-targets --dry-run --output json
102
+ gskills-admin internal-knowledge sync-media --source global --since today --languages fr --all-targets --yes --output json
103
+ ```
104
+
105
+ Rules:
106
+
107
+ - default `--fields url` changes only the referenced media URL
108
+ - use `--fields url,updatedAt` only when the visible date must mirror global
109
+ - target rows are matched by `sourceKnowledgeId`
110
+ - no rows are created
111
+ - activities, metadata, tags, categories, parent links and active state are not changed
112
+ - `pages-knowledge` cache is invalidated for touched instances unless `--no-cache` is passed
113
+
94
114
  ## Admin Ingest Repair
95
115
 
96
116
  Use this when the UI says synchronisations incomplètes or admin console data has repair tasks.
@@ -98,14 +118,12 @@ Use this when the UI says synchronisations incomplètes or admin console data ha
98
118
  Preferred path:
99
119
 
100
120
  ```bash
101
- bunx vercel env pull /tmp/gskills-prod.env --environment=production --yes
102
- bun --conditions react-server -e 'import { getAdminIngestRepairState } from "./src/lib/admin-ingest/repair"; ...'
121
+ gskills-admin admin-ingest repair-state --instance <instanceId> --output json
122
+ gskills-admin admin-ingest repair --instance <instanceId> --dry-run --output json
123
+ gskills-admin admin-ingest repair --instance <instanceId> --yes --output json
103
124
  ```
104
125
 
105
- Then run the existing repair workflow, not ad hoc writes:
106
-
107
- - `getAdminIngestRepairState(instanceId)`
108
- - `adminIngestRepairWorkflow(instanceId, { maxConcurrentDays: 1 })`
126
+ This uses the same repair planner and catchup workflow as the admin-console data UI. Do not use direct env pulls and one-off workflow snippets unless the deployed CLI route is missing.
109
127
 
110
128
  Verify the queue is empty:
111
129
 
@@ -7,7 +7,17 @@ description: Use when Codex is asked to handle GSkills feedback as an operationa
7
7
 
8
8
  Use this for recurring Codex feedback work, not generic UI ticket browsing.
9
9
 
10
- The pattern is: source evidence -> prod DB row -> root cause or data repair -> optional code fix -> feedback state/email update.
10
+ The pattern is: source evidence -> CLI feedback inspection -> root cause or data repair -> optional code fix -> feedback state/email update.
11
+
12
+ For normal agents, start with the CLI instead of direct DB access:
13
+
14
+ ```bash
15
+ gskills-admin feedback inspect <feedbackId> --output json
16
+ gskills-admin feedback inspect 'https://client.g-skills.fr/fr/...' --output json
17
+ gskills-admin feedback translation-status <feedbackId> --output json
18
+ ```
19
+
20
+ Use direct DB only when the CLI output proves the next required table is not exposed yet. If that gap is recurring, add a CLI route or reusable helper.
11
21
 
12
22
  ## What Codex Has Actually Been Used For
13
23
 
@@ -26,6 +36,7 @@ The pattern is: source evidence -> prod DB row -> root cause or data repair -> o
26
36
  - Gmail thread when the ticket comes from forwarded client mail.
27
37
  - Screenshot and client metadata.
28
38
  2. Read prod DB.
39
+ - Prefer `gskills-admin feedback inspect` first.
29
40
  - `Feedback`
30
41
  - `FeedbackAnalysis`
31
42
  - `CommentFeedback`
@@ -120,6 +131,8 @@ Only write after the dry-run proves eligibility.
120
131
  ## Common Pitfalls
121
132
 
122
133
  - Do not trust the automatic AI comment over Marina’s Slack reply.
134
+ - Do not skip `feedback inspect` when the ticket id or URL is known.
135
+ - Do not trust `FeedbackAnalysis.translatedFr` blindly. Use `translation-status` when it might be a fallback copy.
123
136
  - Do not import forwarded email as one ticket if it contains multiple asks.
124
137
  - Do not close a feedback before prod deploy is live when the fix depends on deploy.
125
138
  - Do not use inline body strings for real feedback reply emails.
@@ -19,6 +19,8 @@ Do not count UI visits as work. The signal is Codex-led investigation or mutatio
19
19
  - access/auth/session data changes,
20
20
  - content assistant or chat data lookup.
21
21
 
22
+ For current operations, remember that most agents only have the authenticated CLI, not Theo's direct DB access. The audit should identify which old DB-only steps are now covered by `gskills-admin`, and which recurring gaps still need a new CLI route or reusable helper.
23
+
22
24
  ## Current Pattern Map
23
25
 
24
26
  This is based on Codex memory and rollout summaries checked on 2026-05-13.
@@ -53,6 +55,13 @@ Common Codex-backed GSkills ops:
53
55
  - mutation safety rule,
54
56
  - verification output,
55
57
  - whether an admin log/email/customer effect happened.
58
+ 5. Convert repeatable DB-only operations into CLI guidance.
59
+ - feedback context: `gskills-admin feedback inspect`
60
+ - feedback translation fallback: `gskills-admin feedback translation-status`
61
+ - access truth: `gskills-admin access diagnose`
62
+ - existing knowledge media reference changes: `gskills-admin internal-knowledge sync-media`
63
+ - admin ingest repair state and launch: `gskills-admin admin-ingest repair-state` then `repair --yes`
64
+ - cache repairs: `gskills-admin cache invalidate`
56
65
 
57
66
  ## High-Signal Rollout Families
58
67