@numericoach/gskills-admin-cli 0.1.5 → 0.1.7
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 +4 -1
- package/dist/gskills-admin.js +41 -11
- package/package.json +1 -1
- package/skills/gskills-access-entity-ops/SKILL.md +132 -0
- package/skills/gskills-admin-cli/SKILL.md +3 -1
- package/skills/gskills-content-sync-cache-ops/SKILL.md +114 -0
- package/skills/gskills-feedback-db-ops/SKILL.md +129 -0
- package/skills/gskills-ops-db-audit/SKILL.md +118 -0
package/README.md
CHANGED
|
@@ -51,14 +51,17 @@ gskills-admin org-units-sync google --instance <instanceId> --yes --output json
|
|
|
51
51
|
gskills-admin ambassadors label --instance <instanceId> --language fr --output json
|
|
52
52
|
```
|
|
53
53
|
|
|
54
|
+
Feedback reply bodies are file-based on purpose. Production replies are multi-line, and `send-reply` rejects inline body text to avoid shell parsing surprises.
|
|
55
|
+
|
|
54
56
|
Raw project and analytics data can be read through resources such as `project-data`, `ticket-sla-rules`, `analytics`, `quiz-attempts`, `user-paths`, `chromebook-progress`, and `user-learning-paths`.
|
|
55
57
|
|
|
56
58
|
## Agent skill
|
|
57
59
|
|
|
58
|
-
Install the bundled
|
|
60
|
+
Install the bundled skills so AI agents know the auth model, resource map, output modes, sync workflow, content-authoring standards, and recurring DB-backed ops runbooks.
|
|
59
61
|
|
|
60
62
|
```bash
|
|
61
63
|
gskills-admin skills install --target ~/.codex/skills
|
|
64
|
+
gskills-admin skills install --name gskills-feedback-db-ops --target ~/.codex/skills
|
|
62
65
|
```
|
|
63
66
|
|
|
64
67
|
## Output
|
package/dist/gskills-admin.js
CHANGED
|
@@ -690,7 +690,7 @@ var resourceHelpRows = () => resources.map((resource) => ({
|
|
|
690
690
|
aliases: resource.aliases.join(", ")
|
|
691
691
|
}));
|
|
692
692
|
// ../../src/cli/commands.ts
|
|
693
|
-
import { cp, mkdir as mkdir2, readFile as readFile2, stat } from "node:fs/promises";
|
|
693
|
+
import { cp, mkdir as mkdir2, readFile as readFile2, readdir, stat } from "node:fs/promises";
|
|
694
694
|
import { dirname as dirname2, join as join2 } from "node:path";
|
|
695
695
|
import { fileURLToPath } from "node:url";
|
|
696
696
|
var runCommand = async (ctx) => {
|
|
@@ -907,12 +907,20 @@ var runFeedbackCommand = async (action, feedbackId, ctx) => {
|
|
|
907
907
|
if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
|
|
908
908
|
throw new CliError("Sending feedback reply email requires --yes or --dry-run", 2);
|
|
909
909
|
}
|
|
910
|
+
const bodyFilePath = getStringFlag(ctx, "body-file");
|
|
911
|
+
const translatedBodyFilePath = getStringFlag(ctx, "translated-body-file");
|
|
912
|
+
if (!bodyFilePath) {
|
|
913
|
+
throw new CliError("Feedback reply emails are multi-line. Use --body-file instead of inline --body.", 2);
|
|
914
|
+
}
|
|
915
|
+
if (getStringFlag(ctx, "translated-body") && !translatedBodyFilePath) {
|
|
916
|
+
throw new CliError("Translated feedback reply emails are multi-line. Use --translated-body-file instead of inline --translated-body.", 2);
|
|
917
|
+
}
|
|
910
918
|
const subject = await getTextFlag(ctx, "subject", "subject-file");
|
|
911
919
|
const body = await getTextFlag(ctx, "body", "body-file");
|
|
912
920
|
const translatedSubject = await getTextFlag(ctx, "translated-subject", "translated-subject-file");
|
|
913
921
|
const translatedBody = await getTextFlag(ctx, "translated-body", "translated-body-file");
|
|
914
922
|
if (!subject || !body)
|
|
915
|
-
throw new CliError("Missing --subject or --body", 2);
|
|
923
|
+
throw new CliError("Missing --subject or --body-file", 2);
|
|
916
924
|
return requestApi("/api/cli/feedback/send-reply", {
|
|
917
925
|
method: "POST",
|
|
918
926
|
body: JSON.stringify({
|
|
@@ -1218,10 +1226,18 @@ var runSkillsCommand = async (action, ctx) => {
|
|
|
1218
1226
|
return { path: await skillsSourceDir() };
|
|
1219
1227
|
if (action === "install") {
|
|
1220
1228
|
const target = getStringFlag(ctx, "target") ?? join2(process.cwd(), ".codex", "skills");
|
|
1221
|
-
const
|
|
1229
|
+
const root = await skillsSourceRootDir();
|
|
1230
|
+
const requestedName = getStringFlag(ctx, "name");
|
|
1231
|
+
const skillNames = requestedName ? [requestedName] : await bundledSkillNames(root);
|
|
1222
1232
|
await mkdir2(target, { recursive: true });
|
|
1223
|
-
|
|
1224
|
-
|
|
1233
|
+
const installed = [];
|
|
1234
|
+
for (const skillName of skillNames) {
|
|
1235
|
+
const source = await skillsSourceDir(skillName);
|
|
1236
|
+
const destination = join2(target, skillName);
|
|
1237
|
+
await cp(source, destination, { recursive: true, force: true });
|
|
1238
|
+
installed.push({ name: skillName, destination });
|
|
1239
|
+
}
|
|
1240
|
+
return { installed: true, target, skills: installed };
|
|
1225
1241
|
}
|
|
1226
1242
|
throw new CliError(`Unknown skills command "${action}"`, 2);
|
|
1227
1243
|
};
|
|
@@ -1330,12 +1346,12 @@ var GLOBAL_DEFAULT_RESOURCES = new Set([
|
|
|
1330
1346
|
"chromebook-exercises"
|
|
1331
1347
|
]);
|
|
1332
1348
|
var defaultInstanceId = (resource) => GLOBAL_DEFAULT_RESOURCES.has(resource.name) ? "global" : undefined;
|
|
1333
|
-
var
|
|
1349
|
+
var skillsSourceRootDir = async () => {
|
|
1334
1350
|
const currentDir = dirname2(fileURLToPath(import.meta.url));
|
|
1335
1351
|
const candidates = [
|
|
1336
|
-
join2(currentDir, "..", "skills"
|
|
1337
|
-
join2(process.cwd(), "packages", "gskills-admin-cli", "skills"
|
|
1338
|
-
join2(process.cwd(), ".codex", "skills"
|
|
1352
|
+
join2(currentDir, "..", "skills"),
|
|
1353
|
+
join2(process.cwd(), "packages", "gskills-admin-cli", "skills"),
|
|
1354
|
+
join2(process.cwd(), ".codex", "skills")
|
|
1339
1355
|
];
|
|
1340
1356
|
for (const candidate of candidates) {
|
|
1341
1357
|
try {
|
|
@@ -1345,6 +1361,19 @@ var skillsSourceDir = async () => {
|
|
|
1345
1361
|
continue;
|
|
1346
1362
|
}
|
|
1347
1363
|
}
|
|
1364
|
+
throw new CliError("Bundled GSkills Admin CLI skills were not found", 1);
|
|
1365
|
+
};
|
|
1366
|
+
var bundledSkillNames = async (root) => {
|
|
1367
|
+
const entries = await readdir(root, { withFileTypes: true });
|
|
1368
|
+
return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).filter((name) => name.startsWith("gskills-")).sort();
|
|
1369
|
+
};
|
|
1370
|
+
var skillsSourceDir = async (skillName = "gskills-admin-cli") => {
|
|
1371
|
+
const root = await skillsSourceRootDir();
|
|
1372
|
+
const candidate = join2(root, skillName);
|
|
1373
|
+
try {
|
|
1374
|
+
if ((await stat(candidate)).isDirectory())
|
|
1375
|
+
return candidate;
|
|
1376
|
+
} catch {}
|
|
1348
1377
|
throw new CliError("Bundled GSkills Admin CLI skill was not found", 1);
|
|
1349
1378
|
};
|
|
1350
1379
|
var hasFlag = (ctx, name) => ctx.flags[name] === true;
|
|
@@ -1414,7 +1443,7 @@ var schemaHelp = () => ({
|
|
|
1414
1443
|
{ name: "cache invalidate", required: ["--instance"], flags: ["--scope", "--languages", "--yes", "--dry-run"], writes: true },
|
|
1415
1444
|
{ name: "feedback claim", args: ["feedbackId"], flags: ["--dry-run"], writes: true },
|
|
1416
1445
|
{ name: "feedback send-claim", args: ["feedbackId"], flags: ["--recipient-email", "--recipient-name", "--cc", "--subject", "--body", "--yes", "--dry-run"], writes: true },
|
|
1417
|
-
{ name: "feedback send-reply", args: ["feedbackId"], flags: ["--subject", "--subject-file", "--body
|
|
1446
|
+
{ 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 },
|
|
1418
1447
|
{ name: "access grant", required: ["--user"], flags: ["--type", "--start-at", "--custom-duration-days", "--preferred-language", "--yes", "--dry-run"], writes: true },
|
|
1419
1448
|
{ name: "access revoke-active", required: ["--user"], flags: ["--yes", "--dry-run"], writes: true },
|
|
1420
1449
|
{ name: "instances create-plan", writes: false },
|
|
@@ -1455,10 +1484,11 @@ var skillsHelp = () => ({
|
|
|
1455
1484
|
usage: [
|
|
1456
1485
|
"gskills-admin skills install",
|
|
1457
1486
|
"gskills-admin skills install --target ~/.codex/skills",
|
|
1487
|
+
"gskills-admin skills install --name gskills-feedback-db-ops",
|
|
1458
1488
|
"gskills-admin skills path"
|
|
1459
1489
|
],
|
|
1460
1490
|
defaultTarget: "./.codex/skills",
|
|
1461
|
-
note: "Installs
|
|
1491
|
+
note: "Installs bundled GSkills skills for AI agents. Pass --name to install one skill only."
|
|
1462
1492
|
});
|
|
1463
1493
|
var syncHelp = () => ({
|
|
1464
1494
|
usage: [
|
package/package.json
CHANGED
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: gskills-access-entity-ops
|
|
3
|
+
description: Use when operating or auditing GSkills access data: console-data, users, access passes, entities, groups, org units, Google group sync, content restrictions, page visibility, project data, and analytics parity.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# GSkills Access And Entity Ops
|
|
7
|
+
|
|
8
|
+
Use this skill for data operations around who can access what in GSkills.
|
|
9
|
+
|
|
10
|
+
This is the family behind `console-data`, entities, content restrictions, org units, access passes, project data, and analytics checks.
|
|
11
|
+
|
|
12
|
+
## Evidence Baseline
|
|
13
|
+
|
|
14
|
+
Checked on 2026-05-13 over roughly the last 120 days:
|
|
15
|
+
|
|
16
|
+
- Theo visited `/fr/admin/console-data` 123 times.
|
|
17
|
+
- Theo visited content restrictions 70 times.
|
|
18
|
+
- Theo visited entities 58 times.
|
|
19
|
+
- Theo visited project data 44 times.
|
|
20
|
+
- Theo visited org-units routes in deploy admin.
|
|
21
|
+
- Chronicle and previous CLI work show recurring Air Liquide/entity/cache/visibility checks.
|
|
22
|
+
|
|
23
|
+
## Rules
|
|
24
|
+
|
|
25
|
+
1. Identify the instance first.
|
|
26
|
+
2. Identify the user or entity from prod data, not a label in the UI.
|
|
27
|
+
3. Separate access passes, role/admin rights, entity membership, page visibility, and content restrictions.
|
|
28
|
+
4. Compare the broken user against a working user when possible.
|
|
29
|
+
5. For mutations, prefer CLI/API flows and log the operation.
|
|
30
|
+
6. Never grant broad access as a shortcut for a visibility bug.
|
|
31
|
+
|
|
32
|
+
## Data Areas
|
|
33
|
+
|
|
34
|
+
### Users And Access Passes
|
|
35
|
+
|
|
36
|
+
Check:
|
|
37
|
+
|
|
38
|
+
- `User.instanceID`
|
|
39
|
+
- email and provider identity,
|
|
40
|
+
- active `AccessPass`,
|
|
41
|
+
- start/end dates,
|
|
42
|
+
- pass type,
|
|
43
|
+
- access workflow logs,
|
|
44
|
+
- login logs.
|
|
45
|
+
|
|
46
|
+
CLI examples:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
gskills-admin users list --where '{"email":{"contains":"user@example.com","mode":"insensitive"}}' --output json
|
|
50
|
+
gskills-admin access grant --user <userId> --type DEFAULT --dry-run --output json
|
|
51
|
+
gskills-admin access revoke-active --user <userId> --dry-run --output json
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
### Entities And Groups
|
|
55
|
+
|
|
56
|
+
Check all entity sources:
|
|
57
|
+
|
|
58
|
+
- manual groups,
|
|
59
|
+
- legacy groups,
|
|
60
|
+
- Google groups,
|
|
61
|
+
- org units,
|
|
62
|
+
- synced Google Admin data.
|
|
63
|
+
|
|
64
|
+
CLI examples:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
gskills-admin entities list --instance <instanceId> --language fr --output json
|
|
68
|
+
gskills-admin entities access-summary --instance <instanceId> --output json
|
|
69
|
+
gskills-admin entities sync-google-groups --instance <instanceId> --output json
|
|
70
|
+
gskills-admin org-units-sync google --instance <instanceId> --dry-run --output json
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### Content Restrictions
|
|
74
|
+
|
|
75
|
+
Content visibility can be controlled from multiple places:
|
|
76
|
+
|
|
77
|
+
- entity content restrictions,
|
|
78
|
+
- page visibility entity ids,
|
|
79
|
+
- category restrictions,
|
|
80
|
+
- learning path restrictions,
|
|
81
|
+
- old group fields,
|
|
82
|
+
- runtime filtering and cache.
|
|
83
|
+
|
|
84
|
+
CLI examples:
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
gskills-admin entities set-restrictions <entityId> --instance <instanceId> --category-ids <categoryId> --learning-path-ids <pathId> --dry-run --output json
|
|
88
|
+
gskills-admin entities set-page-visibility --instance <instanceId> --page <pageId> --entity-ids google-group:team@example.com --dry-run --output json
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
## Runtime Proof Pattern
|
|
92
|
+
|
|
93
|
+
For "user should see X" or "user should not see X":
|
|
94
|
+
|
|
95
|
+
1. Query the user and their entity matches.
|
|
96
|
+
2. Query the content item, page, menu item, category, or learning path.
|
|
97
|
+
3. Query restrictions and source ids.
|
|
98
|
+
4. Simulate the same runtime filter used by the deploy page.
|
|
99
|
+
5. Compare with a working user in the same instance.
|
|
100
|
+
6. Check whether cache can rebuild stale visibility.
|
|
101
|
+
|
|
102
|
+
Do not stop at "the DB row exists". Visibility is a runtime decision.
|
|
103
|
+
|
|
104
|
+
## Console Data And Project Data
|
|
105
|
+
|
|
106
|
+
Use `console-data` and `project-data` work to answer:
|
|
107
|
+
|
|
108
|
+
- which Google Workspace data was imported,
|
|
109
|
+
- whether groups/OUs/users are present,
|
|
110
|
+
- whether analytics inputs exist,
|
|
111
|
+
- whether project metadata matches the instance,
|
|
112
|
+
- whether client-specific settings changed.
|
|
113
|
+
|
|
114
|
+
If analytics parity is requested:
|
|
115
|
+
|
|
116
|
+
- identify the exact UI metric,
|
|
117
|
+
- find its source query or table,
|
|
118
|
+
- compare native DB rows with derived analytics rows,
|
|
119
|
+
- report whether the gap is data ingestion, transformation, or UI filtering.
|
|
120
|
+
|
|
121
|
+
## Evidence To Return
|
|
122
|
+
|
|
123
|
+
Return:
|
|
124
|
+
|
|
125
|
+
- instance id/name,
|
|
126
|
+
- affected user/entity ids,
|
|
127
|
+
- access pass state,
|
|
128
|
+
- matched entities,
|
|
129
|
+
- relevant restrictions,
|
|
130
|
+
- runtime visibility result,
|
|
131
|
+
- exact CLI/API mutation if applied,
|
|
132
|
+
- admin log slug created or expected.
|
|
@@ -262,6 +262,8 @@ gskills-admin cache invalidate --instance <instanceId> --scope all --yes --outpu
|
|
|
262
262
|
|
|
263
263
|
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.
|
|
264
264
|
|
|
265
|
+
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.
|
|
266
|
+
|
|
265
267
|
```bash
|
|
266
268
|
gskills-admin feedback send-reply <feedbackId> --subject "GSkills - ..." --body-file ./reply.txt --dry-run --output json
|
|
267
269
|
gskills-admin feedback send-reply <feedbackId> --subject "GSkills - ..." --body-file ./reply.txt --yes --output json
|
|
@@ -293,7 +295,7 @@ gskills-admin feedback send-claim <feedbackId> --recipient-email user@example.co
|
|
|
293
295
|
Rules:
|
|
294
296
|
|
|
295
297
|
- For normal feedback responses, use `send-reply`.
|
|
296
|
-
- For
|
|
298
|
+
- For feedback reply bodies, use `--body-file` and `--translated-body-file`; the CLI rejects inline body text for `send-reply`.
|
|
297
299
|
- Dry-run claim first to inspect recipient, CC recipients and draft.
|
|
298
300
|
- Send only after the ticket is claimed by the same CLI user.
|
|
299
301
|
- CC recipients must be allowed by instance SLA flags.
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: gskills-content-sync-cache-ops
|
|
3
|
+
description: Use when operating GSkills content through DB/CLI: pages, quizzes, learning paths, content news, content assistant outputs, sync diffs/runs, deploy cache resets, menu translation cache issues, or stale content checks.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# GSkills Content, Sync, And Cache Ops
|
|
7
|
+
|
|
8
|
+
Use this skill for non-code GSkills content operations that depend on prod data.
|
|
9
|
+
|
|
10
|
+
This covers the work behind global pages/quizzes, Air Liquide content-news, content assistant outputs, sync checks, and cache resets.
|
|
11
|
+
|
|
12
|
+
## Evidence Baseline
|
|
13
|
+
|
|
14
|
+
Checked on 2026-05-13 over roughly the last 120 days:
|
|
15
|
+
|
|
16
|
+
- Theo/coach2 visited page list/edit routes 180 times.
|
|
17
|
+
- `coach2@numericoach.fr` wrote 43 global page updates and 7 quiz updates.
|
|
18
|
+
- Theo visited `/fr/admin/content-news` 83 times, all on Air Liquide in the recent sample.
|
|
19
|
+
- Theo visited settings 47 times, project data 44 times, and content assistant detail pages repeatedly.
|
|
20
|
+
- Chronicle shows repeated GSkills content admin, EditorJS JSON, Content Assistant, content-news, and Air Liquide cache/translation validation work.
|
|
21
|
+
- Air Liquide menu/cache translation work showed the failure mode: DB translation and cached deploy menu can drift, so compare source data, runtime loader, and cache invalidation.
|
|
22
|
+
|
|
23
|
+
## Rules
|
|
24
|
+
|
|
25
|
+
1. Prefer `gskills-admin` CLI for content reads, sync, and cache invalidation.
|
|
26
|
+
2. Use DB reads to prove current state and history.
|
|
27
|
+
3. Use raw DB writes only for deliberate data repair, and only with a matching admin log.
|
|
28
|
+
4. Never assume global content is deployed to a client. Check sync state or compare source ids.
|
|
29
|
+
5. For cache issues, prove whether data is wrong or cache is stale before invalidating everything.
|
|
30
|
+
|
|
31
|
+
## Read Content State
|
|
32
|
+
|
|
33
|
+
Useful CLI reads:
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
gskills-admin pages list --where '{"language":"fr","slug":{"contains":"gemini"}}' --fields id,name,slug,language,instanceId,disabled --output json
|
|
37
|
+
gskills-admin quizzes list --where '{"language":"fr"}' --fields id,name,language,instanceId --output json
|
|
38
|
+
gskills-admin learning-paths list --instance global --output json
|
|
39
|
+
gskills-admin menus list --instance global --output json
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Useful DB checks:
|
|
43
|
+
|
|
44
|
+
- current page or quiz row,
|
|
45
|
+
- translations via parent/root/source ids,
|
|
46
|
+
- last `LogsUser` entries for the entity,
|
|
47
|
+
- client copy by `sourcePageId`, `sourceQuizId`, or equivalent source field,
|
|
48
|
+
- menu item pointing to the page,
|
|
49
|
+
- deploy cache version rows or settings.
|
|
50
|
+
|
|
51
|
+
## Sync Runbook
|
|
52
|
+
|
|
53
|
+
Before pushing global content to a client:
|
|
54
|
+
|
|
55
|
+
1. Identify source global items.
|
|
56
|
+
2. Identify target instance.
|
|
57
|
+
3. Run a diff.
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
gskills-admin sync diff --target <instanceId> --preset client-content --output json
|
|
61
|
+
gskills-admin sync diff --target <instanceId> --preset pages-only --pages <pageId,pageId> --output json
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
4. Check whether the diff includes only the intended items.
|
|
65
|
+
5. Apply with `--yes` only after a clean diff.
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
gskills-admin sync run --target <instanceId> --preset pages-only --pages <pageId,pageId> --yes --output json
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
6. Reset cache narrowly.
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
gskills-admin cache invalidate --instance <instanceId> --scope pages --languages fr,en --dry-run --output json
|
|
75
|
+
gskills-admin cache invalidate --instance <instanceId> --scope pages --languages fr,en --yes --output json
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
## Cache And Translation Bugs
|
|
79
|
+
|
|
80
|
+
When the user says a menu, page title, card, or learning path label shows the wrong language:
|
|
81
|
+
|
|
82
|
+
1. Capture the exact instance, language, route, and label.
|
|
83
|
+
2. Query source rows and translated target rows.
|
|
84
|
+
3. Query menu items and learning path items that display the label.
|
|
85
|
+
4. Inspect last admin logs touching that entity.
|
|
86
|
+
5. Check cache invalidation scope.
|
|
87
|
+
6. Simulate the runtime loader when possible.
|
|
88
|
+
7. Invalidate only the relevant scope:
|
|
89
|
+
- `pages`
|
|
90
|
+
- `pages-knowledge`
|
|
91
|
+
- `menu-bundle`
|
|
92
|
+
- `applications`
|
|
93
|
+
- `all` only when the broken surface spans multiple bundles.
|
|
94
|
+
|
|
95
|
+
## Content Assistant And Content News
|
|
96
|
+
|
|
97
|
+
For content assistant/content-news work:
|
|
98
|
+
|
|
99
|
+
- Check the generated draft record and destination type.
|
|
100
|
+
- Confirm whether the content is a page, internal knowledge, content news item, or source material.
|
|
101
|
+
- Keep EditorJS JSON intact. Use structured JSON parsing, not regex surgery.
|
|
102
|
+
- Check image/topic enrichment from the existing helpers before inventing a new content path.
|
|
103
|
+
- After creating content, verify the destination row and any linked page/menu/category records.
|
|
104
|
+
|
|
105
|
+
## Evidence To Return
|
|
106
|
+
|
|
107
|
+
Return:
|
|
108
|
+
|
|
109
|
+
- source item ids,
|
|
110
|
+
- target instance ids,
|
|
111
|
+
- diff summary,
|
|
112
|
+
- cache scope invalidated,
|
|
113
|
+
- last admin log touching the item,
|
|
114
|
+
- any remaining deploy/cache uncertainty.
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: gskills-feedback-db-ops
|
|
3
|
+
description: Use when doing recurring GSkills feedback operations from prod data: triage, assign, categorize, resolve, bulk stale pending-validation cleanup, reply email checks, or auditing feedback admin logs.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# GSkills Feedback DB Ops
|
|
7
|
+
|
|
8
|
+
Use this skill for feedback work that is operational and data-heavy.
|
|
9
|
+
|
|
10
|
+
For deep root-cause investigations, also use `$gskills-feedback-resolving`. This skill focuses on the repeated admin ops Theo actually does.
|
|
11
|
+
|
|
12
|
+
## Evidence Baseline
|
|
13
|
+
|
|
14
|
+
Checked on 2026-05-13 over roughly the last 120 days:
|
|
15
|
+
|
|
16
|
+
- Theo visited feedback list/detail pages 196 times.
|
|
17
|
+
- Theo changed feedback status 45 times.
|
|
18
|
+
- Theo assigned feedbacks 29 times.
|
|
19
|
+
- Theo bulk-resolved stale pending-validation feedbacks 29 times.
|
|
20
|
+
- Theo changed feedback categories 10 times.
|
|
21
|
+
- Feedback reply sends are fewer but high-risk because they email real users.
|
|
22
|
+
- Recent DB reply bodies are all multi-line, so `send-reply` must use `--body-file`.
|
|
23
|
+
|
|
24
|
+
## Rules
|
|
25
|
+
|
|
26
|
+
1. Start from prod DB data, not the AI summary.
|
|
27
|
+
2. Read the feedback row, user, instance, URL, screenshot fields, category, status, assignee, and admin logs before changing anything.
|
|
28
|
+
3. For customer-visible email, preserve the language of the feedback or user UI.
|
|
29
|
+
4. Use the authenticated CLI or existing server action path for writes when available.
|
|
30
|
+
5. Never raw-update feedback status without logging the admin event shape.
|
|
31
|
+
6. Bulk cleanup needs a dry-run list and a cutoff reason.
|
|
32
|
+
|
|
33
|
+
## Read The Ticket
|
|
34
|
+
|
|
35
|
+
Use this shape first:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
bun - <<'EOF'
|
|
39
|
+
import { db } from "./src/lib/db"
|
|
40
|
+
|
|
41
|
+
const feedbackId = process.argv[2]
|
|
42
|
+
const feedback = await db.feedback.findUnique({
|
|
43
|
+
where: { id: feedbackId },
|
|
44
|
+
include: {
|
|
45
|
+
user: { select: { id: true, email: true, name: true, language: true, instanceID: true } },
|
|
46
|
+
instance: { select: { id: true, name: true, URL: true } },
|
|
47
|
+
assignedTo: { select: { id: true, email: true, name: true } },
|
|
48
|
+
replies: { orderBy: { createdAt: "desc" }, take: 5 },
|
|
49
|
+
},
|
|
50
|
+
})
|
|
51
|
+
|
|
52
|
+
const logs = await db.logsUser.findMany({
|
|
53
|
+
where: { entityType: "feedback", entityId: feedbackId },
|
|
54
|
+
orderBy: { createdAt: "desc" },
|
|
55
|
+
take: 20,
|
|
56
|
+
select: { createdAt: true, userEmail: true, typeLog: true, slug: true, detailLog: true, metadata: true },
|
|
57
|
+
})
|
|
58
|
+
|
|
59
|
+
console.log(JSON.stringify({ feedback, logs }, null, 2))
|
|
60
|
+
await db.$disconnect()
|
|
61
|
+
EOF
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Common Operations
|
|
65
|
+
|
|
66
|
+
### Assign Or Reassign
|
|
67
|
+
|
|
68
|
+
- Confirm the feedback exists.
|
|
69
|
+
- Confirm the assignee user id.
|
|
70
|
+
- Check if there is already an assignee.
|
|
71
|
+
- Prefer the CLI/API flow if available.
|
|
72
|
+
- If doing a DB repair, create a matching `LogsUser` entry with `slug = "feedback.assignee.assign"` or `feedback.assignee.unassign`.
|
|
73
|
+
|
|
74
|
+
### Categorize
|
|
75
|
+
|
|
76
|
+
- Read current category and AI category.
|
|
77
|
+
- Use the human category as the source of truth after review.
|
|
78
|
+
- Log with `feedback.category.update`.
|
|
79
|
+
- Do not categorize from the title only. Read screenshot and URL.
|
|
80
|
+
|
|
81
|
+
### Resolve
|
|
82
|
+
|
|
83
|
+
- Resolve only after root cause or expected behavior is clear.
|
|
84
|
+
- If a reply email is needed, use:
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
gskills-admin feedback send-reply <feedbackId> --subject "..." --body-file ./reply.txt --dry-run --output json
|
|
88
|
+
gskills-admin feedback send-reply <feedbackId> --subject "..." --body-file ./reply.txt --yes --output json
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
- Real email body must be file-based.
|
|
92
|
+
- After email send, verify `FeedbackReply`, `repliedAt`, `repliedById`, status, and `feedback.email.sent` or `feedback.resolve.with-email` log.
|
|
93
|
+
|
|
94
|
+
### Bulk Resolve Stale Pending Validation
|
|
95
|
+
|
|
96
|
+
This is the pattern behind `feedback.status.bulk-resolve-stale-validation`.
|
|
97
|
+
|
|
98
|
+
Dry-run first:
|
|
99
|
+
|
|
100
|
+
- query all `PENDING_VALIDATION` rows older than the cutoff,
|
|
101
|
+
- exclude recently updated rows,
|
|
102
|
+
- group by instance and category,
|
|
103
|
+
- print ids, user emails, titles, updatedAt, and last admin log,
|
|
104
|
+
- ask whether the cutoff is intentional if not supplied by the user.
|
|
105
|
+
|
|
106
|
+
Apply only when the user asked for the cleanup:
|
|
107
|
+
|
|
108
|
+
- set status to `RESOLVED`,
|
|
109
|
+
- set `treatedAt` if the app expects it,
|
|
110
|
+
- keep `repliedAt` untouched,
|
|
111
|
+
- create one admin log per feedback with metadata:
|
|
112
|
+
- `actorType`
|
|
113
|
+
- `reason`
|
|
114
|
+
- `cutoff`
|
|
115
|
+
- `previousUpdatedAt`
|
|
116
|
+
|
|
117
|
+
## Evidence To Return
|
|
118
|
+
|
|
119
|
+
For every feedback operation, report:
|
|
120
|
+
|
|
121
|
+
- feedback id,
|
|
122
|
+
- instance name/id,
|
|
123
|
+
- user email,
|
|
124
|
+
- old state,
|
|
125
|
+
- new state,
|
|
126
|
+
- admin log slug,
|
|
127
|
+
- whether an email was sent.
|
|
128
|
+
|
|
129
|
+
For bulk operations, include counts by instance and a short sample of ids.
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: gskills-ops-db-audit
|
|
3
|
+
description: Use when asked to inspect what happens operationally in GSkills from prod DB, admin logs, Chronicle, CLI logs, or to discover repeated non-code work patterns before creating or refining agent runbooks.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# GSkills Ops DB Audit
|
|
7
|
+
|
|
8
|
+
Use this skill when the user asks what they, Marina, or Codex often do in GSkills outside pure code work.
|
|
9
|
+
|
|
10
|
+
The job is to turn logs into a practical runbook, not a dashboard screenshot vibe.
|
|
11
|
+
|
|
12
|
+
## Evidence Baseline
|
|
13
|
+
|
|
14
|
+
Checked on 2026-05-13 over roughly the last 120 days:
|
|
15
|
+
|
|
16
|
+
- Theo/non-dev operational logs: 202 non-visit admin log rows.
|
|
17
|
+
- Theo visits: 1716 visit rows.
|
|
18
|
+
- Frequent Theo routes:
|
|
19
|
+
- `/fr/admin/console-data`: 123 visits.
|
|
20
|
+
- feedback detail/list: 196 visits.
|
|
21
|
+
- pages/list/editor: 180 visits.
|
|
22
|
+
- `/fr/admin/content-news`: 83 visits, mostly Air Liquide.
|
|
23
|
+
- content restrictions: 70 visits.
|
|
24
|
+
- entities: 58 visits.
|
|
25
|
+
- settings: 47 visits.
|
|
26
|
+
- project data: 44 visits.
|
|
27
|
+
- Frequent non-visit operations:
|
|
28
|
+
- feedback status updates: 45.
|
|
29
|
+
- global page updates through `coach2@numericoach.fr`: 43.
|
|
30
|
+
- bulk stale pending-validation feedback cleanup: 29.
|
|
31
|
+
- feedback assignee updates: 29.
|
|
32
|
+
- feedback category updates: 10.
|
|
33
|
+
- feedback reply emails: 4 including the newer resolve-with-email path.
|
|
34
|
+
- instance create/delete/settings/AI toggles exist but are sensitive and rarer.
|
|
35
|
+
- Chronicle corroborates:
|
|
36
|
+
- GSkills content administration and content assistant work.
|
|
37
|
+
- Air Liquide menu/cache translation investigations.
|
|
38
|
+
- GSkills admin CLI publishing and skill docs.
|
|
39
|
+
- content-news and EditorJS/content model decisions.
|
|
40
|
+
|
|
41
|
+
## Default Workflow
|
|
42
|
+
|
|
43
|
+
1. Start with prod DB logs.
|
|
44
|
+
- Query `LogsUser`, grouped by `typeLog`, `slug`, `entityType`, user, instance, and date.
|
|
45
|
+
- Include `metadata.actorType`, `metadata.agent`, and `slug LIKE 'cli.%'` for Codex/CLI actions.
|
|
46
|
+
- Exclude `LOGIN` noise unless auth is the question.
|
|
47
|
+
2. Separate visits from writes.
|
|
48
|
+
- Visits tell you where work happens.
|
|
49
|
+
- Writes tell you what actually changed.
|
|
50
|
+
3. Normalize dynamic routes.
|
|
51
|
+
- Collapse page ids, feedback ids, instance ids, and content assistant ids into route families.
|
|
52
|
+
- Keep the raw examples for proof.
|
|
53
|
+
4. Cross-check Chronicle only for context.
|
|
54
|
+
- Use Chronicle to understand the surrounding workstream.
|
|
55
|
+
- Do not use OCR as the source of ids or DB truth.
|
|
56
|
+
5. Convert repeated patterns into skills or CLI improvements.
|
|
57
|
+
- If it happened once and was risky, write a safety rule.
|
|
58
|
+
- If it happened often, write a workflow.
|
|
59
|
+
- If it requires a mutation, prefer the authenticated CLI or app action path over raw DB.
|
|
60
|
+
|
|
61
|
+
## Useful Query Shape
|
|
62
|
+
|
|
63
|
+
Use a read-only Bun query from the repo root:
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
bun - <<'EOF'
|
|
67
|
+
import { db } from "./src/lib/db"
|
|
68
|
+
|
|
69
|
+
const since = new Date(Date.now() - 1000 * 60 * 60 * 24 * 120)
|
|
70
|
+
const rows = await db.logsUser.findMany({
|
|
71
|
+
where: {
|
|
72
|
+
createdAt: { gte: since },
|
|
73
|
+
typeLog: { notIn: ["LOGIN", "LOGIN_ATTEMPT"] },
|
|
74
|
+
},
|
|
75
|
+
orderBy: { createdAt: "desc" },
|
|
76
|
+
take: 5000,
|
|
77
|
+
select: {
|
|
78
|
+
createdAt: true,
|
|
79
|
+
userEmail: true,
|
|
80
|
+
typeLog: true,
|
|
81
|
+
slug: true,
|
|
82
|
+
detailLog: true,
|
|
83
|
+
entityType: true,
|
|
84
|
+
entityId: true,
|
|
85
|
+
instanceId: true,
|
|
86
|
+
metadata: true,
|
|
87
|
+
user: { select: { email: true, name: true } },
|
|
88
|
+
},
|
|
89
|
+
})
|
|
90
|
+
|
|
91
|
+
console.log(rows.length)
|
|
92
|
+
await db.$disconnect()
|
|
93
|
+
EOF
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## What To Look For
|
|
97
|
+
|
|
98
|
+
- `feedback.status.update`, `feedback.assignee.assign`, `feedback.category.update`.
|
|
99
|
+
- `feedback.status.bulk-resolve-stale-validation`.
|
|
100
|
+
- `feedback.email.sent`, `feedback.resolve.with-email`.
|
|
101
|
+
- `pages.update`, `quizzes.update`, `pages.toggle-disabled`.
|
|
102
|
+
- `instance.settings.update`, `instance.ai.toggle`, `instance.branding.patch`.
|
|
103
|
+
- `instance.create`, `instance.delete`.
|
|
104
|
+
- `workflows.action.email-sent`, `workflows.action.deliver-badge`, but treat these as automation output, not Theo doing manual ops.
|
|
105
|
+
- Route visits around `console-data`, `content-news`, `content-restrictions`, `entities`, `settings`, `project-data`, `sync`, and `feedbacks`.
|
|
106
|
+
|
|
107
|
+
## Output Style
|
|
108
|
+
|
|
109
|
+
When reporting, give:
|
|
110
|
+
|
|
111
|
+
- the date window,
|
|
112
|
+
- counts by operation,
|
|
113
|
+
- the top route families,
|
|
114
|
+
- 3-5 concrete examples,
|
|
115
|
+
- what should become a CLI command or skill,
|
|
116
|
+
- what remains too sensitive for automation.
|
|
117
|
+
|
|
118
|
+
No corporate mist. The point is to find the actual repeat work.
|