@numericoach/gskills-admin-cli 0.1.16 → 0.1.18

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
@@ -51,8 +51,13 @@ Use the listed `cache.scopes` with `gskills-admin cache invalidate` after create
51
51
 
52
52
  AI translation is available for content that has native AI translation in the editor:
53
53
 
54
+ Warning: `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.
55
+
56
+ For pages with activities or custom blocks, prefer `--mode patch`. It uses the source page history to update changed text while preserving non-text target block data:
57
+
54
58
  ```bash
55
59
  gskills-admin translate pages <pageId> --to en,es --dry-run --output json
60
+ gskills-admin translate pages <pageId> --from fr --to en,es --mode patch --dry-run --output json
56
61
  gskills-admin translate pages --ids <pageId,pageId> --from fr --to en --dry-run --output json
57
62
  gskills-admin translate pages --all --instance global --from fr --to en --take 100 --dry-run --output json
58
63
  gskills-admin translate quizzes <quizId> --to en --yes --output json
@@ -60,12 +65,19 @@ gskills-admin translate knowledge-video <knowledgeId> --from en --to es --yes --
60
65
  ```
61
66
 
62
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.
63
69
 
64
70
  Operational helpers are available for the admin-only flows agents should not improvise:
65
71
 
66
72
  ```bash
73
+ gskills-admin feedback inspect <feedbackId> --output json
74
+ gskills-admin feedback translation-status <feedbackId> --output json
67
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
68
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
69
81
  gskills-admin instances create-plan --output json
70
82
  gskills-admin instances create --data '{"name":"Client","URL":"client","licenceType":"STARTER","tokensAllowed":50}' --dry-run --output json
71
83
  gskills-admin entities list --instance <instanceId> --output json
@@ -78,6 +90,8 @@ gskills-admin ambassadors label --instance <instanceId> --language fr --output j
78
90
 
79
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.
80
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
+
81
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`.
82
96
 
83
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,10 +1375,14 @@ 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
  }
1297
- return requestApi(`/api/cli/translate/${kind}`, {
1384
+ const mode = getStringFlag(ctx, "mode") ?? "upsert";
1385
+ const result = await requestApi(`/api/cli/translate/${kind}`, {
1298
1386
  method: "POST",
1299
1387
  body: JSON.stringify({
1300
1388
  id,
@@ -1305,10 +1393,12 @@ var runTranslateCommand = async (kind, id, ctx) => {
1305
1393
  take: getNumberFlag(ctx, "take"),
1306
1394
  targetLanguages,
1307
1395
  sourceLanguage: getStringFlag(ctx, "from") ?? getStringFlag(ctx, "source-language"),
1308
- mode: getStringFlag(ctx, "mode") ?? "upsert",
1396
+ sourceHistoryEntryId: getStringFlag(ctx, "source-history") ?? getStringFlag(ctx, "source-history-entry"),
1397
+ mode,
1309
1398
  dryRun: hasFlag(ctx, "dry-run")
1310
1399
  })
1311
1400
  });
1401
+ return addTranslatePagesWarning(kind, mode, result);
1312
1402
  };
1313
1403
  var syncLogs = (ctx) => {
1314
1404
  const searchParams = new URLSearchParams;
@@ -1551,7 +1641,8 @@ var rootHelp = () => ({
1551
1641
  `gskills-admin pages update <id> --data '{"disabled":true}'`,
1552
1642
  "gskills-admin pages delete <id> --force --confirm-delete pages:<id> # soft-disables only",
1553
1643
  "gskills-admin sync run --target <instanceId> --only pages,quizzes --yes",
1554
- "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"
1555
1646
  ],
1556
1647
  resources: resources.map((resource) => resource.name),
1557
1648
  output: "Use --output json, --output jsonl, --output table, or --output markdown. Piped output defaults to JSON.",
@@ -1583,12 +1674,18 @@ var schemaHelp = () => ({
1583
1674
  { name: "sync presets", writes: false },
1584
1675
  { name: "cache scopes", writes: false },
1585
1676
  { name: "cache invalidate", required: ["--instance"], flags: ["--scope", "--languages", "--yes", "--dry-run"], writes: true },
1586
- { name: "translate", args: ["kind", "id?"], required: ["--to"], flags: ["--ids", "--all", "--instance", "--from", "--where", "--take", "--mode", "--yes", "--dry-run"], writes: true },
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 },
1587
1681
  { name: "feedback claim", args: ["feedbackId"], flags: ["--dry-run"], writes: true },
1588
1682
  { name: "feedback send-claim", args: ["feedbackId"], flags: ["--recipient-email", "--recipient-name", "--cc", "--subject", "--body", "--yes", "--dry-run"], writes: true },
1589
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 },
1590
1685
  { name: "access grant", required: ["--user"], flags: ["--type", "--start-at", "--custom-duration-days", "--preferred-language", "--yes", "--dry-run"], writes: true },
1591
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 },
1592
1689
  { name: "instances create-plan", writes: false },
1593
1690
  { name: "instances create", flags: ["--data", "--yes", "--dry-run"], writes: true },
1594
1691
  { name: "entities list", required: ["--instance"], flags: ["--language"], writes: false },
@@ -1690,12 +1787,30 @@ var translateHelp = () => ({
1690
1787
  "learning-paths",
1691
1788
  "chromebook-exercises"
1692
1789
  ],
1693
- modes: ["upsert", "create", "update"],
1790
+ modes: ["upsert", "create", "update", "patch"],
1694
1791
  selection: "Pass one id, --ids for several source rows, or --all with optional --instance, --from, --where and --take.",
1695
- note: "Uses the same AI translation helpers as the editors. Dry-run plans the write without calling AI."
1792
+ warning: PAGE_TRANSLATION_REWRITE_WARNING,
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.",
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."
1696
1795
  });
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.";
1797
+ var addTranslatePagesWarning = (kind, mode, result) => {
1798
+ if (kind !== "pages" && kind !== "page")
1799
+ return result;
1800
+ if (mode !== "update" && mode !== "upsert")
1801
+ return result;
1802
+ if (!result || typeof result !== "object" || Array.isArray(result))
1803
+ return result;
1804
+ return {
1805
+ ...result,
1806
+ warning: PAGE_TRANSLATION_REWRITE_WARNING
1807
+ };
1808
+ };
1697
1809
  var feedbackHelp = () => ({
1698
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>",
1699
1814
  "gskills-admin feedback send-reply <feedbackId> --subject 'GSkills - ...' --body-file ./reply.fr.txt --dry-run",
1700
1815
  "gskills-admin feedback send-reply <feedbackId> --subject 'GSkills - ...' --body-file ./reply.fr.txt --yes",
1701
1816
  "gskills-admin feedback claim <feedbackId> --dry-run",
@@ -1704,6 +1819,14 @@ var feedbackHelp = () => ({
1704
1819
  ],
1705
1820
  note: "send-reply is the normal feedback detail email template flow. claim/send-claim is only the SLA ticket-taken-in-charge flow."
1706
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
+ });
1707
1830
  var instanceCreateHelp = () => ({
1708
1831
  usage: [
1709
1832
  "gskills-admin instances create-plan --output json",
@@ -1735,6 +1858,8 @@ var instanceCreateHelp = () => ({
1735
1858
  });
1736
1859
  var accessHelp = () => ({
1737
1860
  usage: [
1861
+ "gskills-admin access diagnose --email user@example.com --instance <instanceId>",
1862
+ "gskills-admin access diagnose --user <userId>",
1738
1863
  "gskills-admin access grant --user <userId> --type DEFAULT --dry-run",
1739
1864
  "gskills-admin access grant --user <userId> --type PASS_90_DAYS --preferred-language fr --yes",
1740
1865
  "gskills-admin access revoke-active --user <userId> --yes"
@@ -1770,7 +1895,8 @@ var resourceHelp = (resource) => ({
1770
1895
  `gskills-admin ${resource.name} get <id>`,
1771
1896
  `gskills-admin ${resource.name} create --data '{"instanceId":"global"}'`,
1772
1897
  `gskills-admin ${resource.name} update <id> --data '{"disabled":true}'`,
1773
- `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`] : []
1774
1900
  ],
1775
1901
  defaultFields: resource.defaultFields,
1776
1902
  cache: {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@numericoach/gskills-admin-cli",
3
- "version": "0.1.16",
3
+ "version": "0.1.18",
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"`.
@@ -166,6 +180,7 @@ Selection can be one source row, several source rows, or all matching rows:
166
180
 
167
181
  ```bash
168
182
  gskills-admin translate pages <pageId> --to en,es --dry-run --output json
183
+ gskills-admin translate pages <pageId> --from fr --to en,es --mode patch --dry-run --output json
169
184
  gskills-admin translate pages --ids <pageId,pageId> --from fr --to en --dry-run --output json
170
185
  gskills-admin translate pages --all --instance global --from fr --to en --take 100 --dry-run --output json
171
186
  gskills-admin translate quizzes <quizId> --to en --yes --output json
@@ -174,8 +189,26 @@ gskills-admin translate knowledge-video <knowledgeId> --from en --to es --yes --
174
189
 
175
190
  Always dry-run first. Dry-run lists planned rows and target languages without calling AI or writing data. Real runs require `--yes`.
176
191
 
192
+ Never use `--to all`. The CLI rejects it because target languages must be explicit.
193
+
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.
195
+
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.
197
+
177
198
  For quizzes, the CLI mirrors the quiz thematic through `categoryId` across translations.
178
199
 
200
+ Everything translated by the CLI and stored in the DB works as a family. A page is still one page, even when the DB stores one row per language. Do not tell a non-technical user that one page became 40 pages, unless they explicitly ask for DB-level detail.
201
+
202
+ When a translated thing has relations, translate or relink those relations too. A translated page, quiz, badge, resource, knowledge item, menu entry, or learning path should not quietly point back to the French-only relation when a same-language relation exists.
203
+
204
+ For learning paths, a complete translation includes the parcours itself, its groups, its items, same-language page, quiz, resource, and knowledge references when available, the awarded badge family, and each translated parcours linked to the badge in the same language. This exact trap has happened: the parcours translated correctly but every translated parcours still pointed to the French badge.
205
+
206
+ When explaining CLI work to the user, use `gskills-vocabulary`. Speak like a GSkills admin or end user, not like a database. Use words like page, quiz, parcours, badge, menu, resource, and knowledge base. Do not lead with ids, row counts, parent ids, or schema terms unless the user asks for them.
207
+
208
+ Users could do most of these content tasks in the GSkills UI. The reason they ask Codex is speed. Keep the answer simple: what changed, what stays hidden or visible, and what was verified.
209
+
210
+ After translating content, query the DB or CLI output to prove there are no missing languages, no unexpected active content, no missing related content, and no language mismatch between connected things.
211
+
179
212
  For internal knowledge videos, use `knowledge-video`. It queues the same native video localization workflow as the editor, so it creates a localization job instead of copying the original media.
180
213
 
181
214
  After visible content translation, read the cache hint in the response and invalidate the narrow scope before checking the deploy UI.
@@ -215,6 +248,23 @@ Common presets:
215
248
  - `pages-learning-paths`: refinement pass after broad syncs.
216
249
  - `knowledge-resources-paths`: narrow asset and learning path rerun.
217
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
+
218
268
  ## Marina Sync Playbook
219
269
 
220
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.
@@ -323,6 +373,16 @@ Typical mapping:
323
373
 
324
374
  ## Feedback Emails
325
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
+
326
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.
327
387
 
328
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.
@@ -390,6 +450,15 @@ Use dry-run to inspect the full plan and warnings. The real run creates the inst
390
450
 
391
451
  ## Accesses
392
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
+
393
462
  Use `access grant` and `access revoke-active` instead of raw `access-passes` writes when the operation should trigger workflows and admin logs.
394
463
 
395
464
  ```bash
@@ -401,6 +470,18 @@ gskills-admin access revoke-active --user <userId> --yes --output json
401
470
 
402
471
  Types are `DEFAULT`, `PASS_90_DAYS`, `PASS_12_MONTHS`, `CUSTOM`, and `UNLIMITED`.
403
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
+
404
485
  ## Entities And Restrictions
405
486
 
406
487
  Entities are the shared segmentation layer for manual groups, Google groups, and Google Admin OUs.
@@ -537,4 +618,4 @@ Prefer the narrowest scope:
537
618
  - `--take 100` when inventory matters
538
619
  - explicit `--fields` to avoid dumping huge content JSON
539
620
  - explicit `--where` instead of fuzzy reasoning in prose
540
- - 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.