@numericoach/gskills-admin-cli 0.1.17 → 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
|
@@ -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
|
package/dist/gskills-admin.js
CHANGED
|
@@ -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
|
@@ -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
|
|
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
|
-
|
|
102
|
-
|
|
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
|
-
|
|
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 ->
|
|
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.
|