@numericoach/gskills-admin-cli 0.1.7 → 0.1.8

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@numericoach/gskills-admin-cli",
3
- "version": "0.1.7",
3
+ "version": "0.1.8",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Admin-only CLI for GSkills super-admin operations.",
@@ -1,132 +1,148 @@
1
1
  ---
2
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.
3
+ description: Use when Codex is asked to maintain GSkills access/auth/session/entity data outside normal dev work: domain auth, Okta/Google relogin, session invalidation, access passes, entities, groups, org units, content restrictions, and user visibility simulation.
4
4
  ---
5
5
 
6
- # GSkills Access And Entity Ops
6
+ # GSkills Access, Auth, Entity Ops
7
7
 
8
- Use this skill for data operations around who can access what in GSkills.
8
+ Use this for Codex-backed access and visibility maintenance.
9
9
 
10
- This is the family behind `console-data`, entities, content restrictions, org units, access passes, project data, and analytics checks.
10
+ This is not UI browsing. It is DB-backed auth/access work where a wrong mutation can lock people out or expose content.
11
11
 
12
- ## Evidence Baseline
12
+ ## What Codex Has Actually Been Used For
13
13
 
14
- Checked on 2026-05-13 over roughly the last 120 days:
14
+ - Adding Air Liquide auth domains by updating `Instance.domainGranular` in prod.
15
+ - Building and using a data-level JWT session invalidation mechanism.
16
+ - Disconnecting all Air Liquide users so they re-auth through Okta without deleting accounts.
17
+ - Simulating affected users for content visibility bugs.
18
+ - Proving when a user sees hidden content in home/search but not navbar.
19
+ - Checking entity and restriction state when content visibility is wrong.
15
20
 
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.
21
+ ## Auth Domain Updates
22
22
 
23
- ## Rules
23
+ Use this when the user asks to add domains to an instance login system.
24
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.
25
+ 1. Identify the instance.
26
+ 2. Read:
27
+ - `Instance.id`
28
+ - `Instance.URL`
29
+ - `Instance.InstanceAddStyle`
30
+ - `Instance.domainGranular`
31
+ - `RunningState`
32
+ 3. Confirm the runtime code path.
33
+ - `src/auth.ts`
34
+ - `src/lib/server/instance-auth.ts`
35
+ 4. Normalize and deduplicate domains.
36
+ 5. Write only `Instance.domainGranular` if that is the intended change.
37
+ 6. Verify:
38
+ - saved count,
39
+ - expected count,
40
+ - missing domains,
41
+ - extra domains.
31
42
 
32
- ## Data Areas
43
+ Known Air Liquide facts from prior Codex operation:
33
44
 
34
- ### Users And Access Passes
45
+ - instance id `cmfwilgzb000404kzmfrkuifm`
46
+ - URL `air-liquide`
47
+ - `InstanceAddStyle = GRANULAR_DOMAIN`
48
+ - auth matching reads `Instance.domainGranular`
35
49
 
36
- Check:
50
+ ## Session Invalidation
37
51
 
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.
52
+ Use this when users need to reconnect through a new provider, especially Google to Okta.
45
53
 
46
- CLI examples:
54
+ Rules:
47
55
 
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
- ```
56
+ - Never delete accounts to disconnect users.
57
+ - This app uses JWT cookies, not DB `Session` rows.
58
+ - Invalidation is done through `User.sessionVersion`.
59
+ - Audit fields are `sessionInvalidatedAt` and `sessionInvalidationReason`.
60
+ - Provider state is `lastAuthProvider`.
53
61
 
54
- ### Entities And Groups
62
+ Preferred operation:
55
63
 
56
- Check all entity sources:
64
+ 1. Query target users.
65
+ 2. Dry-run count.
66
+ 3. Use Prisma/TypeScript through `src/lib/db.ts`.
67
+ 4. Increment `sessionVersion`.
68
+ 5. Set invalidation audit fields.
69
+ 6. Re-count affected rows.
57
70
 
58
- - manual groups,
59
- - legacy groups,
60
- - Google groups,
61
- - org units,
62
- - synced Google Admin data.
71
+ Known Air Liquide operation:
63
72
 
64
- CLI examples:
73
+ - 52 users were invalidated.
74
+ - Updated `User.sessionVersion`.
75
+ - No accounts, access passes, or provider rows were deleted.
65
76
 
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
77
+ Use the existing repo skill too:
78
+
79
+ ```text
80
+ $gskills-user-session-invalidation
71
81
  ```
72
82
 
73
- ### Content Restrictions
83
+ ## Visibility And Entity Simulation
74
84
 
75
- Content visibility can be controlled from multiple places:
85
+ Use this when the user says a person can or cannot see a page/resource/path.
76
86
 
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.
87
+ 1. Query affected user.
88
+ 2. Query a working comparison user when available.
89
+ 3. Query:
90
+ - access pass,
91
+ - legacy groups,
92
+ - manual groups,
93
+ - Google groups,
94
+ - org units,
95
+ - page `visibleEntityIds`,
96
+ - category and learning-path restrictions,
97
+ - inactive/reverted category flags.
98
+ 4. Simulate each user-visible surface separately:
99
+ - home cards,
100
+ - search,
101
+ - menu/navbar,
102
+ - direct page route.
103
+ 5. If the fix is code, verify with the same prod-shaped simulation.
104
+ 6. If the fix is data, write the narrowest possible change and invalidate relevant cache.
83
105
 
84
- CLI examples:
106
+ Known failure mode:
85
107
 
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
- ```
108
+ - A user can see cards or search results for pages that later 404 because home/search filtering is looser than the page route guard.
109
+ - A clean navbar simulation does not prove home/search are clean.
90
110
 
91
- ## Runtime Proof Pattern
111
+ ## Access Pass Work
92
112
 
93
- For "user should see X" or "user should not see X":
113
+ Use this when the issue is login/access rather than content visibility.
94
114
 
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.
115
+ Check:
101
116
 
102
- Do not stop at "the DB row exists". Visibility is a runtime decision.
117
+ - `User.instanceID`
118
+ - active `AccessPass`
119
+ - pass type and dates,
120
+ - workflow logs for access start/expiry,
121
+ - login logs.
103
122
 
104
- ## Console Data And Project Data
123
+ Do not grant broad pass access to hide a content-restriction bug.
105
124
 
106
- Use `console-data` and `project-data` work to answer:
125
+ ## Entity And Org Unit Work
107
126
 
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.
127
+ Use existing CLI/API paths where possible:
113
128
 
114
- If analytics parity is requested:
129
+ ```bash
130
+ gskills-admin entities list --instance <instanceId> --language fr --output json
131
+ gskills-admin entities access-summary --instance <instanceId> --output json
132
+ gskills-admin entities sync-google-groups --instance <instanceId> --output json
133
+ gskills-admin org-units-sync google --instance <instanceId> --dry-run --output json
134
+ ```
115
135
 
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.
136
+ For writes, dry-run first and report the exact target entities.
120
137
 
121
- ## Evidence To Return
138
+ ## Done Criteria
122
139
 
123
140
  Return:
124
141
 
125
142
  - 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.
143
+ - exact user/entity ids,
144
+ - before state,
145
+ - mutation performed,
146
+ - after state,
147
+ - whether cache was invalidated,
148
+ - whether users need to log in again.
@@ -1,114 +1,154 @@
1
1
  ---
2
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.
3
+ description: Use when Codex is asked to maintain GSkills content data outside normal dev work: sync drift diagnosis, page visibility bugs, cache invalidation, page metadata backfills, content assistant lookups, content-news checks, or admin ingest repair.
4
4
  ---
5
5
 
6
- # GSkills Content, Sync, And Cache Ops
6
+ # GSkills Content, Sync, Cache Ops
7
7
 
8
- Use this skill for non-code GSkills content operations that depend on prod data.
8
+ Use this for Codex-backed maintenance of GSkills content data.
9
9
 
10
- This covers the work behind global pages/quizzes, Air Liquide content-news, content assistant outputs, sync checks, and cache resets.
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
- ## Evidence Baseline
12
+ ## What Codex Has Actually Been Used For
13
13
 
14
- Checked on 2026-05-13 over roughly the last 120 days:
14
+ - Investigating a Google Contacts page sync issue where source global content was published but client copies stayed disabled.
15
+ - Proving stale deploy cache after sync/direct data repair and invalidating the right page/menu/app scopes.
16
+ - Repairing incomplete admin ingest syncs for `global` with the production repair workflow.
17
+ - Backfilling `Pages.headerColor` from global pages to client copies across 49,338 mapped pages.
18
+ - Comparing broken and working synced instances when a quiz exists in editor content but does not render on deploy.
19
+ - Finding content-assistant artifacts from `Chat` and `ChatMessage` metadata.
20
+ - Using Gmail/docs/source material to understand webinar/resource ingestion before writing GSkills data.
15
21
 
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
+ ## Sync Drift Investigation
22
23
 
23
- ## Rules
24
+ Use this when a synced page/resource/quiz/path looks different on clients.
24
25
 
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.
26
+ 1. Identify source global row and target instance rows.
27
+ 2. Query target copies by source linkage, not slug only.
28
+ - For pages, prefer `crossInstanceID` when relevant.
29
+ 3. Compare:
30
+ - `disabled`
31
+ - `archived`
32
+ - title/slug/language
33
+ - `headerColor`
34
+ - category/app links
35
+ - embedded quiz ids
36
+ - relation tables
37
+ 4. Check sync logs and admin logs around the event.
38
+ 5. Inspect the sync engine only after prod data proves the drift.
39
+ 6. Separate code fix from prod data repair.
30
40
 
31
- ## Read Content State
41
+ Known example:
32
42
 
33
- Useful CLI reads:
43
+ - Google Contacts page source was `disabled=false`, target copies were still `disabled=true`.
44
+ - The sync rule preserved target disabled state through `resolveSyncedDisabled`.
45
+ - Admin logs showed manual `pages.toggle-disabled` after the sync.
34
46
 
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
- ```
47
+ ## Cache Invalidation After Data Repair
41
48
 
42
- Useful DB checks:
49
+ Use this when a direct DB fix or sync leaves old deploy data visible.
43
50
 
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.
51
+ Rules:
50
52
 
51
- ## Sync Runbook
53
+ - Identify the edited entity first.
54
+ - Invalidate scopes for the entity, not only the visible symptom.
55
+ - If a `Pages` field changed, invalidate page scopes and menu/app scopes when the page appears in menus or app lists.
52
56
 
53
- Before pushing global content to a client:
57
+ Known page repair scopes:
54
58
 
55
- 1. Identify source global items.
56
- 2. Identify target instance.
57
- 3. Run a diff.
59
+ - `pages`
60
+ - `pages-count`
61
+ - `pages-lite`
62
+ - `page-minimal`
63
+ - `pages-knowledge`
64
+ - `deploy-home-static`
65
+ - `applications`
66
+ - `menu-bundle`
58
67
 
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
- ```
68
+ Use version bumps from:
63
69
 
64
- 4. Check whether the diff includes only the intended items.
65
- 5. Apply with `--yes` only after a clean diff.
70
+ - `src/lib/deploy-cache.ts`
71
+ - `src/lib/sync-engine/cache-invalidation.ts`
66
72
 
67
- ```bash
68
- gskills-admin sync run --target <instanceId> --preset pages-only --pages <pageId,pageId> --yes --output json
69
- ```
73
+ Verify current cache keys disappear or versions increase for sample instances.
74
+
75
+ ## Page Metadata Backfill
76
+
77
+ Use this for scoped prod backfills like `Pages.headerColor`.
78
+
79
+ Pattern:
80
+
81
+ 1. Count mapped rows.
82
+ 2. Count mismatches before.
83
+ 3. Write only the intended column.
84
+ 4. Count mismatches after.
85
+ 5. Tell the user the exact write scope.
86
+
87
+ Known validated shape:
70
88
 
71
- 6. Reset cache narrowly.
89
+ - `UPDATE "Pages" SET "headerColor" = global_page."headerColor"` only.
90
+ - Target rows where `crossInstanceID` points to global page.
91
+ - Before: 49,338 mapped pages, 25,611 mismatches.
92
+ - After: 0 mismatches.
93
+
94
+ ## Admin Ingest Repair
95
+
96
+ Use this when the UI says synchronisations incomplètes or admin console data has repair tasks.
97
+
98
+ Preferred path:
72
99
 
73
100
  ```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
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"; ...'
76
103
  ```
77
104
 
78
- ## Cache And Translation Bugs
105
+ Then run the existing repair workflow, not ad hoc writes:
106
+
107
+ - `getAdminIngestRepairState(instanceId)`
108
+ - `adminIngestRepairWorkflow(instanceId, { maxConcurrentDays: 1 })`
109
+
110
+ Verify the queue is empty:
111
+
112
+ - `canLaunch=false`
113
+ - `blockedReason="no_repairs_needed"`
114
+ - `affectedDayCount=0`
115
+ - `repairTargetCount=0`
79
116
 
80
- When the user says a menu, page title, card, or learning path label shows the wrong language:
117
+ ## Content Assistant Lookup
81
118
 
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.
119
+ Use this when the user asks for “the artifact” or a content creation thread.
120
+
121
+ Query:
122
+
123
+ - `User`
124
+ - `Chat`
125
+ - `ChatMessage`
126
+ - `metadata.artifact`
127
+ - `CHAT_KINDS.CONTENT_ASSISTANT`
128
+
129
+ Return the exact prod route:
130
+
131
+ ```text
132
+ https://g-skills.fr/fr/super-admin/global/content-assistant/<chatId>
133
+ ```
94
134
 
95
- ## Content Assistant And Content News
135
+ Do not browse manually when the artifact text and metadata are in DB.
96
136
 
97
- For content assistant/content-news work:
137
+ ## Broken Deploy Content After Sync
98
138
 
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.
139
+ Use this when a thing exists in editor but not on the deploy page.
104
140
 
105
- ## Evidence To Return
141
+ - Compare the broken instance against a synced working instance.
142
+ - Query embedded ids from EditorJS JSON.
143
+ - Query relation tables separately.
144
+ - Pull production logs when runtime behavior matters.
145
+ - Keep the root cause tentative until the loader/action that returns empty/null is proven.
106
146
 
107
- Return:
147
+ Good proof:
108
148
 
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.
149
+ - broken page id,
150
+ - working page id,
151
+ - embedded quiz/resource id,
152
+ - relation count,
153
+ - runtime logs,
154
+ - exact API call or loader result.
@@ -1,129 +1,126 @@
1
1
  ---
2
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.
3
+ description: Use when Codex is asked to handle GSkills feedback as an operational DB-backed workflow: investigate from prod rows, import feedback from emails, triage with Slack/Marina context, repair user state, close tickets, assign Theo, or send reply emails.
4
4
  ---
5
5
 
6
6
  # GSkills Feedback DB Ops
7
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:
8
+ Use this for recurring Codex feedback work, not generic UI ticket browsing.
9
+
10
+ The pattern is: source evidence -> prod DB row -> root cause or data repair -> optional code fix -> feedback state/email update.
11
+
12
+ ## What Codex Has Actually Been Used For
13
+
14
+ - Building the feedback resolving skill after mining past Codex sessions and prod schema.
15
+ - Checking recent GSkills tickets with `#g-skills-auto`, prioritizing Marina’s human comments over automatic AI comments.
16
+ - Importing forwarded Gmail issues into prod `Feedback`, `FeedbackAnalysis`, and `FeedbackAssignee`.
17
+ - Investigating a course completion bug from a feedback URL, proving `UserPath.isAchieved = false` despite passed quiz attempts, then applying the prod completion write.
18
+ - Closing feedback after prod deploy verification, assigning it to Theo, creating a `FeedbackReply`, and sending a customer email.
19
+ - Categorizing and resolving stale tickets when the root cause is known.
20
+
21
+ ## Default Workflow
22
+
23
+ 1. Read the source.
24
+ - Feedback URL or id.
25
+ - Slack `#g-skills-auto` thread, especially Marina replies.
26
+ - Gmail thread when the ticket comes from forwarded client mail.
27
+ - Screenshot and client metadata.
28
+ 2. Read prod DB.
29
+ - `Feedback`
30
+ - `FeedbackAnalysis`
31
+ - `CommentFeedback`
32
+ - `FeedbackAssignee`
33
+ - `FeedbackReply`
34
+ - affected `User`, `Instance`, `Pages`, quiz/progress/access rows when relevant.
35
+ 3. Prove the issue.
36
+ - For content/access bugs, simulate the affected runtime path.
37
+ - For quiz/progress bugs, compare attempts with `UserPath` and learning-path completion rows.
38
+ - For imported emails, split separate asks into separate feedbacks.
39
+ 4. Act.
40
+ - Use existing app/CLI action when available.
41
+ - If a direct DB write is requested and safe, write the minimal rows and verify.
42
+ - For customer replies, use file-based body text and preserve the customer/user language.
43
+ 5. Verify.
44
+ - Re-read feedback state.
45
+ - Confirm assignee, status, reply row, email id, and admin log where applicable.
46
+
47
+ ## Email-To-Feedback Import
48
+
49
+ Use this when the user says a client email should become GSkills feedback.
50
+
51
+ Rules:
52
+
53
+ - Search both Theo and developer mailboxes when the user mentions both.
54
+ - Resolve the real Gmail API thread id with `gws`, not the UI fragment.
55
+ - Read the full thread.
56
+ - One email can contain multiple tickets. Split them.
57
+ - If the issue already exists, add context to the existing feedback instead of duplicating.
58
+ - Insert enough context for the feedback detail screen to be useful.
59
+
60
+ Tables:
61
+
62
+ - `Feedback`
63
+ - `FeedbackAnalysis`
64
+ - `FeedbackAssignee`
65
+ - optional `CommentFeedback`
66
+
67
+ Verification:
68
+
69
+ - feedback ids,
70
+ - instance and user pairing,
71
+ - `status = ANALYZED` when imported as actionable,
72
+ - assignee is Theo when requested,
73
+ - original thread ids preserved in context.
74
+
75
+ ## Feedback Closure With Email
76
+
77
+ Use this when the user asks to treat a feedback after a prod fix.
78
+
79
+ 1. Confirm production deployment is live when the fix depends on deploy.
80
+ 2. Re-run the affected-user proof or live state check.
81
+ 3. Draft in the same language as the user/feedback.
82
+ 4. Send with the CLI:
85
83
 
86
84
  ```bash
87
85
  gskills-admin feedback send-reply <feedbackId> --subject "..." --body-file ./reply.txt --dry-run --output json
88
86
  gskills-admin feedback send-reply <feedbackId> --subject "..." --body-file ./reply.txt --yes --output json
89
87
  ```
90
88
 
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.
89
+ 5. Verify:
90
+ - `Feedback.status`
91
+ - `FeedbackAssignee`
92
+ - `FeedbackReply`
93
+ - `repliedAt`
94
+ - email message id
93
95
 
94
- ### Bulk Resolve Stale Pending Validation
96
+ ## Progress Or Course Completion Repair
95
97
 
96
- This is the pattern behind `feedback.status.bulk-resolve-stale-validation`.
98
+ Use this when a user passed a quiz but a page/course/path did not validate.
97
99
 
98
- Dry-run first:
100
+ Proof chain:
99
101
 
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.
102
+ - feedback row,
103
+ - user id,
104
+ - page id,
105
+ - quiz id,
106
+ - quiz attempts with `passed=true`,
107
+ - `UserPath.isAchieved`,
108
+ - learning-path item completion rows,
109
+ - relevant runtime function.
105
110
 
106
- Apply only when the user asked for the cleanup:
111
+ For embedded quiz completion, the known safe dry-run/write path is:
107
112
 
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
113
+ ```ts
114
+ maybeAchieveCourseFromEmbeddedQuizSuccess({ userId, quizId, pageId, commit: false })
115
+ maybeAchieveCourseFromEmbeddedQuizSuccess({ userId, quizId, pageId, commit: true })
116
+ ```
118
117
 
119
- For every feedback operation, report:
118
+ Only write after the dry-run proves eligibility.
120
119
 
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.
120
+ ## Common Pitfalls
128
121
 
129
- For bulk operations, include counts by instance and a short sample of ids.
122
+ - Do not trust the automatic AI comment over Marina’s Slack reply.
123
+ - Do not import forwarded email as one ticket if it contains multiple asks.
124
+ - Do not close a feedback before prod deploy is live when the fix depends on deploy.
125
+ - Do not use inline body strings for real feedback reply emails.
126
+ - Do not say “fixed” until the prod row and customer-visible state are verified.
@@ -1,118 +1,92 @@
1
1
  ---
2
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.
3
+ description: Use when mining Codex history and prod DB evidence to identify recurring non-dev GSkills operations, especially data repairs, cache/sync fixes, feedback handling, auth/access changes, and content knowledge retrieval.
4
4
  ---
5
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.
6
+ # GSkills Codex Ops Audit
7
+
8
+ Use this when the user asks what Codex is often used for on GSkills outside normal development work.
9
+
10
+ Do not count UI visits as work. The signal is Codex-led investigation or mutation:
11
+
12
+ - prod DB reads,
13
+ - prod DB writes,
14
+ - Vercel/prod env checks,
15
+ - Slack/Gmail/Chronicle context that leads to GSkills data work,
16
+ - cache invalidation,
17
+ - feedback import or closure,
18
+ - sync repair,
19
+ - access/auth/session data changes,
20
+ - content assistant or chat data lookup.
21
+
22
+ ## Current Pattern Map
23
+
24
+ This is based on Codex memory and rollout summaries checked on 2026-05-13.
25
+
26
+ Common Codex-backed GSkills ops:
27
+
28
+ - Feedback investigation and resolution from URL, Slack, Gmail, screenshots and prod DB.
29
+ - Feedback creation from forwarded client emails into prod `Feedback`, `FeedbackAnalysis`, and `FeedbackAssignee`.
30
+ - Feedback closure after production verification, including assignment, reply row, and Resend email.
31
+ - Course/progress data repair after proving quiz attempts or completion state.
32
+ - Sync/page visibility investigations where prod data and admin logs prove target copies drifted.
33
+ - Cache invalidation after sync or direct DB fixes, especially page/menu/app deploy caches.
34
+ - Admin ingest repair workflows for incomplete Google/Admin console data syncs.
35
+ - Bulk page metadata backfills, such as copying `Pages.headerColor` from global to client copies.
36
+ - Auth/access data changes, such as Air Liquide `domainGranular` updates and JWT session invalidation.
37
+ - Content assistant and AI chat lookup by artifact/message metadata to retrieve exact prod links.
38
+
39
+ ## Default Audit Workflow
40
+
41
+ 1. Search Codex memory and rollout summaries first.
42
+ - Use `MEMORY.md` to locate relevant summaries.
43
+ - Search `rollout_summaries` for concrete phrases like `prod DB`, `Feedback`, `cache`, `sync`, `backfill`, `domainGranular`, `sessionVersion`, `content-assistant`.
44
+ 2. Then inspect prod DB only for current truth.
45
+ - Do not infer old behavior from current logs if the task is historical.
46
+ - Admin logs usually do not tag old Codex work as Codex.
47
+ 3. Ignore pure code refactors unless the Codex run also included prod data proof or mutation.
48
+ 4. For each recurring workflow, capture:
49
+ - trigger phrase from the user,
50
+ - evidence source,
51
+ - tables touched or read,
52
+ - code path reused,
53
+ - mutation safety rule,
54
+ - verification output,
55
+ - whether an admin log/email/customer effect happened.
56
+
57
+ ## High-Signal Rollout Families
58
+
59
+ - `gskills_feedback_resolving_skill_created`
60
+ - Feedback work should start with prod DB, screenshots, route context and recurrence.
61
+ - `gskills_feedback_triage_slack_marina_comments`
62
+ - For tickets, check `#g-skills-auto` and Marina comments before trusting AI summaries.
63
+ - `gskills_feedback_positioning_quiz_completion_bug`
64
+ - Codex proved quiz attempts passed, repaired `UserPath` completion in prod, and committed the code fix.
65
+ - `fm_visibility_feedback_resolution_and_production_followup`
66
+ - Codex simulated the affected user, waited for prod, then resolved/assigned/replied in DB and email.
67
+ - `email_to_prod_feedback_import_and_var_correction`
68
+ - Codex imported forwarded Gmail tickets into prod feedback rows.
69
+ - `gskills_admin_ingest_repair_global_incomplete_syncs`
70
+ - Codex used prod env and the repair workflow to clear incomplete admin ingest syncs.
71
+ - `gskills_slack_contact_page_cache_investigation`
72
+ - Codex traced a page/sync issue to stale deploy cache and invalidated the right scopes.
73
+ - `gskills_page_header_color_backfill`
74
+ - Codex measured prod drift, backfilled one column only, and proved zero mismatches after.
75
+ - `air_liquide_auth_domaingranular_update`
76
+ - Codex did a targeted prod data update on `Instance.domainGranular`.
77
+ - `gskills_airliquide_session_invalidation_and_skill`
78
+ - Codex used Prisma/TypeScript to invalidate sessions without deleting users.
79
+ - `stefanie_chromebook_content_assistant_prod_link`
80
+ - Codex queried `Chat`/`ChatMessage` metadata to find the exact content assistant artifact link.
81
+
82
+ ## Output
83
+
84
+ When asked for a new skill or workflow, output:
85
+
86
+ - what Codex actually did before,
87
+ - the repeated trigger pattern,
88
+ - what DB tables or APIs matter,
89
+ - how to run it safely now,
90
+ - what proof is required before saying it is done.
91
+
92
+ No visit counts. No “looked at page X” unless that visit led to a concrete data operation.