@numericoach/gskills-admin-cli 0.1.30 → 0.1.32
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 +53 -4
- package/dist/gskills-admin.js +22904 -756
- package/package.json +25 -24
- package/skills/gskills-admin-cli/SKILL.md +226 -260
- package/skills/gskills-admin-cli/references/content-platform-tables.md +1647 -0
- package/skills/gskills-admin-cli/references/content-platform.md +146 -0
- package/skills/gskills-content-sync-cache-ops/SKILL.md +36 -89
- package/skills/gskills-customer-playbooks/SKILL.md +18 -19
- package/skills/gskills-ops-db-audit/SKILL.md +5 -5
- package/skills/gskills-page-content-blocks/SKILL.md +40 -47
- package/skills/gskills-source-id-repair/SKILL.md +11 -30
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
# Content platform operations
|
|
2
|
+
|
|
3
|
+
This guide implements the operating rules from ADR 001 (page revisions), ADR 002 (translations), and ADR 003 (shared content and sync removal) in `plans/content-platform/` in the application repository. Run `gskills-admin content-platform help --output json` for the portable CLI contract. A local CLI build does not prove the server or database has been migrated.
|
|
4
|
+
|
|
5
|
+
## Read this first
|
|
6
|
+
|
|
7
|
+
There are two useful levels of documentation.
|
|
8
|
+
|
|
9
|
+
- This guide explains how the system fits together and which operation to choose.
|
|
10
|
+
- The [table-by-table reference](content-platform-tables.md) explains every migration table individually, including its purpose, key, relationships, writer, inspection scenario, common mistake, and example query.
|
|
11
|
+
|
|
12
|
+
You can read the same reference without opening repository files.
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
gskills-admin content-platform tables --output table
|
|
16
|
+
gskills-admin content-platform explain page-revision-locales --output json
|
|
17
|
+
gskills-admin page-revision-locales help --output json
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
`tables` is the directory. `explain <resource>` is one complete entry. `<resource> help` also includes that entry under `documentation`, and `schema` includes it for each documented resource. Resource aliases work with `explain` too. These commands read local CLI documentation; they do not inspect the connected database.
|
|
21
|
+
|
|
22
|
+
Named writers such as `PublishPageDraft` are internal product operations, not CLI commands. The CLI can inspect all tables in this reference. For pages, `gskills-admin page-authoring` (editor, create, draft, readiness, publish, upload-image) runs the admin editor repository commands. Restore, archive, unpublish, audience and locale operations, and every non-page family, run through `gskills-admin admin` (`admin ops`, `admin describe <op>`, `admin run <op> --dry-run|--yes`), which calls the exact use case or admin action of the UI.
|
|
23
|
+
|
|
24
|
+
## Vocabulary with concrete meanings
|
|
25
|
+
|
|
26
|
+
| Term | Meaning |
|
|
27
|
+
| --- | --- |
|
|
28
|
+
| Family | One logical piece of content across languages. A page or quiz family has a stable ID. |
|
|
29
|
+
| Locale | One language identity, such as the French version of that family. |
|
|
30
|
+
| Revision | Content at a particular draft or published version. Page drafts are mutable; published versions are immutable. |
|
|
31
|
+
| Identity | The stable ID that survives changes to text, order, language content and versions. |
|
|
32
|
+
| Override | One customer's exception to inherited source behavior, such as a hidden item or a different icon. |
|
|
33
|
+
| Projection | A compatibility representation maintained for legacy readers during coexistence. It is not an independently authored customer copy after canonical cutover. |
|
|
34
|
+
| Snapshot | Values preserved at a particular source version or point in time, such as what a learner answered. |
|
|
35
|
+
| Authority fence | Database state deciding which writer is allowed to change a scope and which epoch its request must carry. |
|
|
36
|
+
| Outbox | Persisted work produced by a public-state transaction for workers to process safely afterward. |
|
|
37
|
+
| Lease | A lock with a holder and lifetime/generation, preventing competing migration or workflow execution work. |
|
|
38
|
+
|
|
39
|
+
## Follow one page from identity to learner view
|
|
40
|
+
|
|
41
|
+
Suppose page `p1` has French locale `l-fr` and English locale `l-en`. It currently points to published revision `r1` and draft revision `r2`.
|
|
42
|
+
|
|
43
|
+
1. `canonical-pages` identifies `p1` and its two pointers. It does not contain the body.
|
|
44
|
+
2. `page-locales` identifies `l-fr` and `l-en`. These IDs stay the same when version 2 is published.
|
|
45
|
+
3. `page-revisions` contains the shared settings of `r1` and `r2`. Read `publishedRevisionId` first to know which one is live.
|
|
46
|
+
4. `page-revision-locales` contains the French and English titles, slugs and review status for each revision.
|
|
47
|
+
5. `page-revision-blocks` contains that revision's block structure and shared settings. `page-revision-block-locales` contains the language-specific payloads. `page-revision-block-scopes` matters when a block is restricted to selected languages.
|
|
48
|
+
6. `page-locale-validation-checkpoints` proves which exact content was accepted for each language. Editing `r2` can invalidate that review.
|
|
49
|
+
7. The consumer's availability, audience and presentation rows determine whether and how that customer sees the published content. The menu tables determine navigation, not permission to open a page.
|
|
50
|
+
|
|
51
|
+
Saving `r2` leaves learners on `r1`. Publishing the validated draft makes version 2 live by switching the page's pointer. The stable IDs `p1`, `l-fr` and `l-en` do not change. Restoring version 1 later creates draft content for a future publication; it does not rewrite version 1 or silently roll back the live page.
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
# Read the pointers, then use the returned published revision ID.
|
|
55
|
+
gskills-admin canonical-pages get <pageId> --output json
|
|
56
|
+
gskills-admin page-locales list --where '{"pageId":"<pageId>"}' --output json
|
|
57
|
+
gskills-admin page-revision-locales list --where '{"revisionId":"<publishedRevisionId>"}' --output json
|
|
58
|
+
gskills-admin page-revision-blocks list --where '{"revisionId":"<publishedRevisionId>"}' --output json
|
|
59
|
+
# For one returned block, inspect its language payloads explicitly.
|
|
60
|
+
gskills-admin page-revision-block-locales list --where '{"revisionBlockId":"<revisionBlockId>"}' --fields revisionBlockId,pageLocaleId,localizedPayload,fieldPresence --output json
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Distinctions that prevent wrong conclusions
|
|
64
|
+
|
|
65
|
+
| Observation | Correct interpretation and next check |
|
|
66
|
+
| --- | --- |
|
|
67
|
+
| There is a new draft | The published pointer still decides what learners see. |
|
|
68
|
+
| A locale identity exists | Check its revision locale, content and validation before treating it as publishable. |
|
|
69
|
+
| A customer has no availability override row | Apply inheritance/default rules; absence alone does not mean hidden. |
|
|
70
|
+
| A shared page is missing from the customer's menu | Check menu mode/exclusions/placements separately from page availability and audience. |
|
|
71
|
+
| A workflow definition publishes version 3 | A customer pinned to version 2 stays on version 2 until an explicit activation/rollout changes that pin. |
|
|
72
|
+
| A quiz was edited after an attempt | Inspect the attempt's immutable quiz revision and answer snapshots, not today's quiz definition. |
|
|
73
|
+
| A migration run is completed | Check which phase and mode completed, then inspect current authority and verification evidence. |
|
|
74
|
+
| A legacy row was physically retired | Keep aliases and durable identities; do not recreate the projection to repair an old link. |
|
|
75
|
+
| A workflow event already has a dedupe claim | Inspect the execution and its attempts; deleting the claim can duplicate side effects. |
|
|
76
|
+
|
|
77
|
+
## Start with authority
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
gskills-admin content-migration-states list --instance <instanceId> --output json
|
|
81
|
+
gskills-admin page-migration-states list --where '{"pageId":"<pageId>"}' --output json
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Read `readMode`, `writeMode`, `transitionState`, `authorityEpoch`, and `legacyStorageState`. Page-level authority can be finer than family-level authority. Missing state is not proof of cutover. Additive tables and completed dry-runs do not make canonical operations authoritative.
|
|
85
|
+
|
|
86
|
+
- `LEGACY_PRIMARY` permits only the existing guarded legacy paths for that scope.
|
|
87
|
+
- `CANONICAL_PRIMARY` requires canonical authoring, even when legacy projections are still present.
|
|
88
|
+
- `DRAINING` requires a fresh authority read before retrying. Never force an older epoch.
|
|
89
|
+
- `PRESENT` means the legacy projection still exists, not that it is writable.
|
|
90
|
+
- `RETIRING` and `RETIRED` prohibit legacy projection recreation and normal legacy rollback.
|
|
91
|
+
|
|
92
|
+
Never mutate state, epochs, aliases, outbox rows, leases, dedupe claims, snapshots, or reconciliation evidence to force an operation through. Backfill, cutover, and retirement belong to the reviewed one-shot migration scripts, not generic CRUD or a recurring sync job.
|
|
93
|
+
|
|
94
|
+
## Choose the right resource
|
|
95
|
+
|
|
96
|
+
| Need | CLI resources |
|
|
97
|
+
| --- | --- |
|
|
98
|
+
| Stable canonical page identity | `canonical-pages` (`Page`, distinct from legacy `pages` / `Pages`) |
|
|
99
|
+
| Stable language identity | `page-locales` |
|
|
100
|
+
| Draft/published revision and localized content | `page-revisions`, `page-revision-locales`, `page-revision-blocks`, `page-revision-block-locales` |
|
|
101
|
+
| Revision validation and publication history | `page-locale-validation-checkpoints`, `page-revision-events` |
|
|
102
|
+
| Resolve old IDs and routes | `content-id-aliases`, `page-route-aliases`, `page-route-claims` |
|
|
103
|
+
| Consumer availability | `instance-content-availability`, `instance-content-locale-availability` |
|
|
104
|
+
| Page audience and presentation | `instance-page-audience-policies`, `instance-page-locale-audience-overrides`, `instance-page-presentation-overrides` |
|
|
105
|
+
| Learning path presentation | `instance-learning-path-presentation-overrides` |
|
|
106
|
+
| Retired category/resource presentation | `instance-category-presentation-snapshots`, `resource-presentation-snapshots` |
|
|
107
|
+
| Consumer menus | `instance-menu-configurations`, `instance-menu-node-exclusions`, `instance-menu-placements` |
|
|
108
|
+
| Workflow definitions and publication | `workflow-definitions`, `workflow-revisions` |
|
|
109
|
+
| Workflow consumer activation and deduplication | `instance-workflow-activations`, `workflow-execution-dedupe-claims` |
|
|
110
|
+
| Migration diagnosis | `content-migration-states`, `page-migration-states`, `content-migration-runs`, `content-migration-issues`, `content-reconciliation-ledgers` |
|
|
111
|
+
|
|
112
|
+
Raw canonical/control resources are read-only. Read `schema` or `<resource> help` for the resource's fields and capabilities. Resources marked `listOnly` have no scalar `id`, so filter by their key fields rather than calling `get <id>`.
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
gskills-admin canonical-pages list --where '{"ownerInstanceId":null}' --output json
|
|
116
|
+
gskills-admin page-locales list --where '{"pageId":"<pageId>"}' --output json
|
|
117
|
+
gskills-admin page-revisions list --where '{"pageId":"<pageId>"}' --output json
|
|
118
|
+
gskills-admin page-revision-categories list --where '{"revisionId":"<revisionId>"}' --output json
|
|
119
|
+
gskills-admin workflow-execution-dedupe-claims list --instance <instanceId> --where '{"canonicalDedupeKey":"<key>"}' --output json
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
`ownerInstanceId=null` is universal shared content. `ownerInstanceId="global"` is dedicated content owned by global and is not universal. `--instance` filters the configured owner or consumer field; it is not an effective inherited catalogue query. Inspect shared definitions and consumer availability separately. Progress and durable references use stable canonical page IDs, not revision IDs. Resolve legacy IDs through verified aliases rather than guessing equivalences.
|
|
123
|
+
|
|
124
|
+
## Write through the guarded product operations
|
|
125
|
+
|
|
126
|
+
Every instance and content family is `CANONICAL_PRIMARY`. The CLI refuses every Legacy content write with `LEGACY_CONTENT_WRITE_RETIRED` (`pages create/update/delete`, `pages block`, `pages patch-content`, page activity helpers, raw CRUD on content tables, `sync run`, `sync repair-source-links`); follow the returned `nextAction` and never bypass it with direct DB, Prisma or SQL.
|
|
127
|
+
|
|
128
|
+
Pages are written with `page-authoring`:
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
gskills-admin page-authoring editor <pageId> --instance global --include-content --output json
|
|
132
|
+
gskills-admin page-authoring create --instance global --locale fr --title "..." --content-file ./page.fr.json --data-file ./spec.json --dry-run --output json
|
|
133
|
+
gskills-admin page-authoring draft <pageId> --instance global --locale fr --content-file ./page.fr.json --lock-version <n> --dry-run --output json
|
|
134
|
+
gskills-admin page-authoring readiness <pageId> --instance global --output json
|
|
135
|
+
gskills-admin page-authoring publish <pageId> --instance global --lock-version <n> --note "..." --dry-run --output json
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
`create` and `draft` save the private draft (`--lock-version` from `editor` guards concurrent edits); `readiness` lists blockers; `publish` is the validate-and-publish step. Restore, archive, unpublish and locale operations are `admin run pages.*` operations. Quizzes, learning paths, categories, menus, knowledge, resources, badges, Chromebook, activities, workflows and per-instance availability (`catalogue.hide|restore`) are written with `admin run <op>`: read the state, `--dry-run`, then `--yes`, then re-read.
|
|
139
|
+
|
|
140
|
+
Save updates the private draft. Publish validates the persisted draft and creates the next immutable numbered version in one transaction. Restore fills a draft and does not change the live version. The source locale, active French and English locales, and all required translations must meet validation requirements before publication. Never directly change `publishedRevisionId`, `draftRevisionId`, or immutable revision content.
|
|
141
|
+
|
|
142
|
+
`translate pages` writes canonical drafts whenever the page scope is canonical-primary (new locales are added as `OPTIONAL`). Specify the consumer/owner context with `--instance`, use an explicit canonical page ID, and dry-run before applying. Translation neither publishes nor substitutes for human validation: run `page-authoring readiness` and `publish` afterwards when publication was asked. Retired locales require explicit reactivation. `--all --where` is unsupported and customer `--all` enumerates owned pages, not inherited shared pages. `translate quizzes|menus|menu-sections` are retired.
|
|
143
|
+
|
|
144
|
+
Shared content is stored once. Publication replaces copy synchronization, and `sync run` is refused. Use the guarded admin operations for availability (`catalogue.*`), audience (`pages.audience.*`), menu placement (`menus.*`), and presentation (`knowledge.change`). Do not create customer copies or rebuild retired projections. Workflow publication and consumer activation/rollout are separate operations; publishing must not silently move instance revision pins.
|
|
145
|
+
|
|
146
|
+
Read the changed state again and verify the visible result. Canonical publication advances scope versions and emits outbox events; manual cache invalidation is not publication. A CLI dry-run can validate only the request plan for generic resources, not deployed support, database authority, or the eventual product result.
|
|
@@ -1,60 +1,58 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: gskills-content-sync-cache-ops
|
|
3
|
-
description: Use when Codex is asked to maintain GSkills content data outside normal dev work:
|
|
3
|
+
description: Use when Codex is asked to maintain GSkills content data outside normal dev work: customer visibility diagnosis, page visibility bugs, cache invalidation, content assistant lookups, content-news checks, or admin ingest repair. Legacy sync, backfill and source-link repairs are retired.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# GSkills Content, Sync, Cache Ops
|
|
7
7
|
|
|
8
|
+
## Since the content migration (Sept 2026)
|
|
9
|
+
|
|
10
|
+
Every instance and content family is canonical-primary. Content sync is gone: shared canonical content is inherited by every instance (ADR-003), and customers opt out only by hiding inherited content (`admin run catalogue.hide|restore`). The CLI refuses every Legacy content write with `LEGACY_CONTENT_WRITE_RETIRED`, including `sync run`, `sync repair-source-links`, `pages backfill-field`, `internal-knowledge sync-media` and raw content CRUD. Follow the returned `nextAction`; never work around it with direct DB, Prisma, SQL or a repo script, and never recreate customer copies or retired projections. Pages are fixed with `gskills-admin page-authoring`; other families with `gskills-admin admin run <family>.<op>` (read op → `describe` → `--dry-run` → `--yes` → re-read). Read `gskills-admin content-platform help --output json` and the [content platform operations guide](../gskills-admin-cli/references/content-platform.md) first.
|
|
11
|
+
|
|
8
12
|
Use this for Codex-backed maintenance of GSkills content data.
|
|
9
13
|
|
|
10
|
-
This is not about UI visits. It is about proving
|
|
14
|
+
This is not about UI visits. It is about proving content state with the CLI, cache helpers, and production verification, then fixing it through the canonical path.
|
|
11
15
|
|
|
12
16
|
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
17
|
|
|
14
18
|
## What Codex Has Actually Been Used For
|
|
15
19
|
|
|
20
|
+
Historical (pre-migration) jobs, kept for context:
|
|
21
|
+
|
|
16
22
|
- Investigating a Google Contacts page sync issue where source global content was published but client copies stayed disabled.
|
|
17
23
|
- Proving stale deploy cache after sync/direct data repair and invalidating the right page/menu/app scopes.
|
|
18
24
|
- Repairing incomplete admin ingest syncs for `global` with the production repair workflow.
|
|
19
|
-
- Backfilling `Pages.headerColor` from global pages to client copies
|
|
20
|
-
- Comparing broken and working
|
|
25
|
+
- Backfilling `Pages.headerColor` from global pages to client copies (no longer needed: settings live once on the shared page).
|
|
26
|
+
- Comparing broken and working instances when a quiz exists in editor content but does not render on deploy.
|
|
21
27
|
- Finding content-assistant artifacts from `Chat` and `ChatMessage` metadata.
|
|
22
28
|
- Using Gmail/docs/source material to understand webinar/resource ingestion before writing GSkills data.
|
|
23
29
|
|
|
24
|
-
##
|
|
25
|
-
|
|
26
|
-
Use this when a synced page/resource/quiz/path looks different on clients.
|
|
30
|
+
## Customer Visibility Investigation
|
|
27
31
|
|
|
28
|
-
|
|
29
|
-
2. Query target copies by source linkage, not slug only.
|
|
30
|
-
- For pages, prefer `crossInstanceID` when relevant.
|
|
31
|
-
3. Compare:
|
|
32
|
-
- `disabled`
|
|
33
|
-
- `archived`
|
|
34
|
-
- title/slug/language
|
|
35
|
-
- `headerColor`
|
|
36
|
-
- category/app links
|
|
37
|
-
- embedded quiz ids
|
|
38
|
-
- relation tables
|
|
39
|
-
4. Check sync logs and admin logs around the event.
|
|
40
|
-
5. Inspect the sync engine only after prod data proves the drift.
|
|
41
|
-
6. Separate code fix from prod data repair.
|
|
32
|
+
Use this when shared content looks different or missing on a customer. There are no customer copies to compare anymore.
|
|
42
33
|
|
|
43
|
-
|
|
34
|
+
1. Resolve the canonical page (`canonical-pages`, `content-id-aliases` for old ids) and read it with `page-authoring editor <pageId> --instance global --output json`.
|
|
35
|
+
2. Check what is published: published revision, locales, `alphaProgramIds`, `frenchOnly`, categories. A newer draft is not live.
|
|
36
|
+
3. Check authority: `content-migration-states` for the instance and `page-migration-states` for the page.
|
|
37
|
+
4. Check the customer overlay (`admin run catalogue.list --yes` gives the effective view):
|
|
38
|
+
- `instance-content-availability` and `instance-content-locale-availability` (missing row = inherited)
|
|
39
|
+
- `instance-page-audience-policies`, `instance-page-locale-audience-overrides`
|
|
40
|
+
- `instance-page-presentation-overrides`
|
|
41
|
+
- menu tables (`instance-menu-configurations`, exclusions, placements) for navigation, not access
|
|
42
|
+
5. Check admin logs around the event.
|
|
43
|
+
6. Separate code fix from data fix. Data fixes go through `page-authoring` (page content/settings) or `admin run` (`catalogue.*` availability, `pages.audience.save`, `menus.*`, other families).
|
|
44
44
|
|
|
45
|
-
|
|
46
|
-
- The sync rule preserved target disabled state through `resolveSyncedDisabled`.
|
|
47
|
-
- Admin logs showed manual `pages.toggle-disabled` after the sync.
|
|
45
|
+
Historical example (Legacy era): the Google Contacts page source was `disabled=false` while client copies stayed `disabled=true` because sync preserved the target disabled state and an admin had toggled it manually. The canonical equivalent is a customer availability override.
|
|
48
46
|
|
|
49
47
|
## Cache Invalidation After Data Repair
|
|
50
48
|
|
|
51
|
-
Use this when a
|
|
49
|
+
Use this when a verified change leaves old deploy data visible. Canonical publication advances content scope versions itself, so invalidate only when the published state is proven and the deploy is still stale.
|
|
52
50
|
|
|
53
51
|
Rules:
|
|
54
52
|
|
|
55
53
|
- Identify the edited entity first.
|
|
56
54
|
- Invalidate scopes for the entity, not only the visible symptom.
|
|
57
|
-
- If
|
|
55
|
+
- If page settings changed, invalidate page scopes and menu/app scopes when the page appears in menus or app lists.
|
|
58
56
|
|
|
59
57
|
Known page repair scopes:
|
|
60
58
|
|
|
@@ -74,60 +72,9 @@ Use version bumps from:
|
|
|
74
72
|
|
|
75
73
|
Verify current cache keys disappear or versions increase for sample instances.
|
|
76
74
|
|
|
77
|
-
##
|
|
78
|
-
|
|
79
|
-
Use this for scoped prod backfills like `Pages.headerColor`.
|
|
80
|
-
|
|
81
|
-
Preferred path:
|
|
82
|
-
|
|
83
|
-
```bash
|
|
84
|
-
gskills-admin pages backfill-field --field headerColor --all-targets --dry-run --output json
|
|
85
|
-
gskills-admin pages backfill-field --field headerColor --all-targets --yes --output json
|
|
86
|
-
```
|
|
87
|
-
|
|
88
|
-
Pattern:
|
|
89
|
-
|
|
90
|
-
1. Count mapped rows.
|
|
91
|
-
2. Count mismatches before.
|
|
92
|
-
3. Write only the intended column.
|
|
93
|
-
4. Count mismatches after.
|
|
94
|
-
5. Tell the user the exact write scope.
|
|
95
|
-
|
|
96
|
-
Known validated shape:
|
|
97
|
-
|
|
98
|
-
- the CLI writes only `Pages.headerColor`
|
|
99
|
-
- target rows are matched by `crossInstanceID` pointing to a global page
|
|
100
|
-
- historical before count: 49,338 mapped pages, 25,611 mismatches
|
|
101
|
-
- historical after count: 0 mismatches
|
|
75
|
+
## Retired Legacy Repairs
|
|
102
76
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
Use this when synced content exists but source linkage is missing or stale, especially learning path item/group links, internal knowledge source links, or resource references.
|
|
106
|
-
|
|
107
|
-
```bash
|
|
108
|
-
gskills-admin sync repair-source-links --target <instanceId> --dry-run --output json
|
|
109
|
-
gskills-admin sync repair-source-links --target <instanceId> --yes --output json
|
|
110
|
-
```
|
|
111
|
-
|
|
112
|
-
The command runs a narrow sync-engine pass for learning paths, knowledge and resources, fixes duplicates, keeps normal sync logging, and invalidates deploy cache after a real repair.
|
|
113
|
-
|
|
114
|
-
## Knowledge Media Reference Sync
|
|
115
|
-
|
|
116
|
-
Use this when global internal knowledge videos changed and client copies already exist.
|
|
117
|
-
|
|
118
|
-
```bash
|
|
119
|
-
gskills-admin internal-knowledge sync-media --source global --since today --languages fr --all-targets --dry-run --output json
|
|
120
|
-
gskills-admin internal-knowledge sync-media --source global --since today --languages fr --all-targets --yes --output json
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
Rules:
|
|
124
|
-
|
|
125
|
-
- default `--fields url` changes only the referenced media URL
|
|
126
|
-
- use `--fields url,updatedAt` only when the visible date must mirror global
|
|
127
|
-
- target rows are matched by `sourceKnowledgeId`
|
|
128
|
-
- no rows are created
|
|
129
|
-
- activities, metadata, tags, categories, parent links and active state are not changed
|
|
130
|
-
- `pages-knowledge` cache is invalidated for touched instances unless `--no-cache` is passed
|
|
77
|
+
`pages backfill-field`, `sync repair-source-links` and `internal-knowledge sync-media` are refused with `LEGACY_CONTENT_WRITE_RETIRED`. They repaired per-instance copies that no longer exist: page settings (such as `headerColor`) live once on the shared page and change with `page-authoring draft --data-file` then `publish`; knowledge media and learning path references are edited once with `admin run knowledge.update` / `learning-paths.update` and inherited.
|
|
131
78
|
|
|
132
79
|
## Admin Ingest Repair
|
|
133
80
|
|
|
@@ -170,21 +117,21 @@ https://g-skills.fr/fr/super-admin/global/content-assistant/<chatId>
|
|
|
170
117
|
|
|
171
118
|
Do not browse manually or query `Chat` and `ChatMessage` directly when the CLI lookup can return the artifact metadata.
|
|
172
119
|
|
|
173
|
-
## Broken Deploy Content
|
|
120
|
+
## Broken Deploy Content
|
|
174
121
|
|
|
175
|
-
Use this when a thing exists in editor but not on the deploy page.
|
|
122
|
+
Use this when a thing exists in the editor but not on the deploy page.
|
|
176
123
|
|
|
177
|
-
-
|
|
178
|
-
-
|
|
179
|
-
-
|
|
124
|
+
- Check that the change is published, not only in the draft (`page-authoring editor`).
|
|
125
|
+
- Compare the broken instance against a working instance that inherits the same page, and diff their availability, audience and presentation overrides.
|
|
126
|
+
- Read embedded ids from the published EditorJS document (`editor --include-content`) and check that the referenced quiz, resource or activity is published and available to the instance.
|
|
180
127
|
- Pull production logs when runtime behavior matters.
|
|
181
128
|
- Keep the root cause tentative until the loader/action that returns empty/null is proven.
|
|
182
129
|
|
|
183
130
|
Good proof:
|
|
184
131
|
|
|
185
|
-
-
|
|
186
|
-
-
|
|
187
|
-
-
|
|
188
|
-
- relation count,
|
|
132
|
+
- page id and published revision,
|
|
133
|
+
- embedded quiz/resource/activity id,
|
|
134
|
+
- the customer's availability rows,
|
|
189
135
|
- runtime logs,
|
|
190
136
|
- exact API call or loader result.
|
|
137
|
+
|
|
@@ -7,10 +7,14 @@ description: Use when a GSkills task names a recurring customer and the agent ne
|
|
|
7
7
|
|
|
8
8
|
Use this skill when the user names a recurring GSkills customer. This is operational memory, not live proof. If the answer or action matters in production, re-check current DB rows, admin logs, sync logs, Slack, Gmail, Google Chat, or the app before acting.
|
|
9
9
|
|
|
10
|
+
## Since the content migration (Sept 2026)
|
|
11
|
+
|
|
12
|
+
Content sync is gone. Shared canonical content published on `global` is inherited by every customer (ADR-003); a customer opts out only by hiding inherited content (`admin run catalogue.hide`, back with `catalogue.restore`). `sync run` and Legacy content writes are refused with `LEGACY_CONTENT_WRITE_RETIRED`. Older notes below about sync runs, `SKIPPED_CUSTOMIZED` or customer copies describe history: use them to read old logs, not as a procedure. Pages are authored with `gskills-admin page-authoring`; other families with `gskills-admin admin run <family>.<op>`.
|
|
13
|
+
|
|
10
14
|
## General Defaults
|
|
11
15
|
|
|
12
16
|
- Start from the customer instance, not from a generic global theory.
|
|
13
|
-
- For
|
|
17
|
+
- For content missing on a customer, check the published canonical page (`page-authoring editor`) and the customer's availability overrides (`instance-content-availability`, `instance-content-locale-availability`) before blaming inheritance.
|
|
14
18
|
- For feedbacks, inspect the feedback row, user, instance, and admin logs before explaining the cause.
|
|
15
19
|
- For access issues, check user instance, access passes, auth mode, domain or account allowlists, then logs.
|
|
16
20
|
- For client wording, use the real thread or channel when available.
|
|
@@ -22,9 +26,8 @@ Air Liquide is the heavy recurring customer. Expect large content volume, custom
|
|
|
22
26
|
|
|
23
27
|
Common work:
|
|
24
28
|
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
- Page, quiz, parcours, menu, resource, badge, and internal knowledge parity checks after sync.
|
|
29
|
+
- Large inherited catalogue from global. Historical sync runs showed many `SKIPPED_CUSTOMIZED` items: deliberate customer divergence, now expressed as availability or presentation overrides.
|
|
30
|
+
- Page, quiz, parcours, menu, resource, badge, and internal knowledge visibility checks.
|
|
28
31
|
- Feedback instance attribution and page-family parity repairs.
|
|
29
32
|
- Access-denied work around expired access passes or domain allowlists.
|
|
30
33
|
- Okta setup and auth callback checks.
|
|
@@ -38,7 +41,7 @@ Known context:
|
|
|
38
41
|
- Known Google Chat space: `Air Liquide x Numericoach - GSkills`, `spaces/AAQAc2CT1qI`.
|
|
39
42
|
- Recurring task-tracking Sheet from Audrey: `NC AIR LIQUIDE GSKILLS GDP`, `https://docs.google.com/spreadsheets/d/1qhbvCEae5-3MIDENxEcp708vt_gK8lpRdkSHYEXHSog/edit?gid=0#gid=0`. Use it when the user asks about Air Liquide task ownership or GDP follow-up. Prefer moving actionable work into the app or ClickUp when possible; Google Workspace tracking is tolerated here because the client uses it, not because it is the desired operating model.
|
|
40
43
|
- Harold OUSSET was a known user whose display name required surname-first parsing.
|
|
41
|
-
-
|
|
44
|
+
- To make new global content visible to Air Liquide, publish it (`page-authoring publish`, `quizzes.publish` …) and check their effective catalogue (`admin run catalogue.list`); there is no sync to run.
|
|
42
45
|
|
|
43
46
|
## HASAP
|
|
44
47
|
|
|
@@ -50,13 +53,13 @@ Common work:
|
|
|
50
53
|
- Badge visibility and badge delivery repairs.
|
|
51
54
|
- Google Forms badge issues where the page trigger stayed the same but the badge target changed.
|
|
52
55
|
- Quiz completion and answer submission investigations.
|
|
53
|
-
- Page
|
|
56
|
+
- Page visibility issues (historically disabled/archived copies and sync logs; now published revision, availability overrides and audience).
|
|
54
57
|
|
|
55
58
|
Known context:
|
|
56
59
|
|
|
57
60
|
- Known Google Chat space: `GSkills_Hasap_x_Numericoach`, `spaces/AAQAxJEETeI`.
|
|
58
61
|
- The recurring badge pitfall is workflow deduplication. A same-page `QUIZ_COMPLETED` execution can block a new badge action if only the badge target changed.
|
|
59
|
-
- Do not explain HASAP
|
|
62
|
+
- Do not explain HASAP visibility issues from the URL alone. Use prod data, `LogsUser`, the page or parcours family, its published revision and HASAP's availability overrides.
|
|
60
63
|
|
|
61
64
|
## FM LOGISTIC Google & Co
|
|
62
65
|
|
|
@@ -129,19 +132,16 @@ Euromaster has appeared in sync and broad repair work.
|
|
|
129
132
|
|
|
130
133
|
Common work:
|
|
131
134
|
|
|
132
|
-
- Page
|
|
133
|
-
- Post-sync verification.
|
|
135
|
+
- Page or parcours visibility checks after global publication.
|
|
134
136
|
- Data repair blast-radius checks.
|
|
135
137
|
|
|
136
138
|
## Commune de Divonne-les-Bains, AS de Pic, 360 Courtage
|
|
137
139
|
|
|
138
|
-
These have appeared as new-client
|
|
140
|
+
These have appeared as new-client onboardings (historically broad first syncs from global).
|
|
139
141
|
|
|
140
142
|
Common work:
|
|
141
143
|
|
|
142
|
-
-
|
|
143
|
-
- High created counts are expected.
|
|
144
|
-
- Run `client-content` diff first, then apply, then verify menus and deploy cache.
|
|
144
|
+
- New instances inherit shared content without a sync. Verify the catalogue, menus and deploy cache instead.
|
|
145
145
|
|
|
146
146
|
## Nickel Banque
|
|
147
147
|
|
|
@@ -154,12 +154,11 @@ Common work:
|
|
|
154
154
|
|
|
155
155
|
## Terega
|
|
156
156
|
|
|
157
|
-
Terega has appeared as a one-off client synchronisation target.
|
|
157
|
+
Terega has appeared as a one-off client synchronisation target (before sync was retired).
|
|
158
158
|
|
|
159
159
|
Common work:
|
|
160
160
|
|
|
161
|
-
- Treat as normal
|
|
162
|
-
- Resolve the instance id and check recent sync logs before applying.
|
|
161
|
+
- Treat as a normal inherited catalogue. Resolve the instance id and check availability overrides before explaining missing content.
|
|
163
162
|
|
|
164
163
|
## Euralis, Orqual, Groupe Kiosque, UTT Yarns
|
|
165
164
|
|
|
@@ -176,6 +175,6 @@ Global is the source of truth for shared content.
|
|
|
176
175
|
|
|
177
176
|
Common work:
|
|
178
177
|
|
|
179
|
-
- Create or update global courses, tutorials, granules
|
|
180
|
-
-
|
|
181
|
-
- Keep client
|
|
178
|
+
- Create or update global courses, tutorials, granules and modules with `page-authoring`; quizzes, parcours, badges, menus, resources and base de connaissance content with `admin run <family>.<op>` (`admin ops --family <f>` lists them).
|
|
179
|
+
- Shared content published on global is inherited by clients; there is no push.
|
|
180
|
+
- Keep client availability and presentation overrides intact unless the user explicitly wants them changed (`catalogue.*`, `knowledge.change`, `menus.*`).
|
|
@@ -31,10 +31,10 @@ Common Codex-backed GSkills ops:
|
|
|
31
31
|
- Feedback creation from forwarded client emails into prod `Feedback`, `FeedbackAnalysis`, and `FeedbackAssignee`.
|
|
32
32
|
- Feedback closure after production verification, including assignment, reply row, and Resend email.
|
|
33
33
|
- Course/progress data repair after proving quiz attempts or completion state.
|
|
34
|
-
- Sync/page visibility investigations where prod data and admin logs prove target copies drifted.
|
|
34
|
+
- Sync/page visibility investigations where prod data and admin logs prove target copies drifted (Legacy era; today: published revision plus `catalogue.list`).
|
|
35
35
|
- Cache invalidation after sync or data repairs, especially page/menu/app deploy caches.
|
|
36
36
|
- Admin ingest repair workflows for incomplete Google/Admin console data syncs.
|
|
37
|
-
- Bulk page metadata backfills, such as copying `Pages.headerColor` from global to client copies.
|
|
37
|
+
- Bulk page metadata backfills, such as copying `Pages.headerColor` from global to client copies (Legacy era; settings now live once on the shared page).
|
|
38
38
|
- Auth/access data changes, such as Air Liquide `domainGranular` updates and JWT session invalidation.
|
|
39
39
|
- Content assistant and AI chat lookup by artifact/message metadata to retrieve exact prod links.
|
|
40
40
|
|
|
@@ -60,9 +60,9 @@ Common Codex-backed GSkills ops:
|
|
|
60
60
|
- feedback translation fallback: `gskills-admin feedback translation-status`
|
|
61
61
|
- feedback email import: `gskills-admin feedback import-email`
|
|
62
62
|
- access truth: `gskills-admin access diagnose`
|
|
63
|
-
-
|
|
64
|
-
-
|
|
65
|
-
-
|
|
63
|
+
- page content and settings: `gskills-admin page-authoring` (editor, draft, readiness, publish)
|
|
64
|
+
- every other content family (quizzes, learning paths, knowledge, resources, badges, menus, Chromebook, workflows, categories, availability): `gskills-admin admin ops --family <f>`, `admin describe <op>`, `admin run <op> --dry-run`, then `--yes`, then re-read
|
|
65
|
+
- retired since the content migration (Sept 2026), refused with `LEGACY_CONTENT_WRITE_RETIRED`: `internal-knowledge sync-media`, `sync run`, `sync repair-source-links`, `pages backfill-field` (content is stored once and inherited, so there are no copies to repair)
|
|
66
66
|
- progress repair: `gskills-admin progress embedded-course` or `progress repair-learning-path-quiz-mismatches`
|
|
67
67
|
- session invalidation: `gskills-admin sessions invalidate`
|
|
68
68
|
- content assistant artifact lookup: `gskills-admin content-assistant lookup`
|
|
@@ -1,52 +1,58 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: gskills-page-content-blocks
|
|
3
|
-
description: Use before creating or
|
|
3
|
+
description: Use before creating or editing GSkills page content, especially the EditorJS documents sent through page-authoring, custom blocks, nested layouts, imported sheets, quizzes, page/resource tags, and AI-agent page edits.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# GSkills Page Content Blocks
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
## Since the content migration (Sept 2026)
|
|
9
|
+
|
|
10
|
+
Pages are canonical (`Page`, `PageLocale`, `PageRevision`). The only CLI write path is `gskills-admin page-authoring`. `pages create/update`, `pages block <write>`, `pages patch-content`, `pages activity <write>` and `pedagogical-activities attach-page` are refused with `LEGACY_CONTENT_WRITE_RETIRED`; follow its `nextAction`, never bypass it with direct DB, Prisma or SQL. Legacy `Pages.content` is stale: read content with `page-authoring editor`. See `gskills-admin-cli` for the full command family.
|
|
11
|
+
|
|
12
|
+
Use this skill whenever Codex creates or edits a page's EditorJS document.
|
|
9
13
|
|
|
10
14
|
The source of truth is the CLI block schema. Read it first:
|
|
11
15
|
|
|
12
16
|
```bash
|
|
13
|
-
gskills-admin
|
|
17
|
+
gskills-admin page-authoring content-schema --output json
|
|
14
18
|
```
|
|
15
19
|
|
|
16
20
|
If `gskills-admin` is not installed, use:
|
|
17
21
|
|
|
18
22
|
```bash
|
|
19
|
-
bunx @numericoach/gskills-admin-cli@latest
|
|
23
|
+
bunx @numericoach/gskills-admin-cli@latest page-authoring content-schema --output json
|
|
20
24
|
```
|
|
21
25
|
|
|
22
26
|
## Rules
|
|
23
27
|
|
|
24
|
-
-
|
|
28
|
+
- Each locale has one EditorJS document `{ "blocks": [...] }`, not markdown.
|
|
25
29
|
- Preserve existing block `id`, `type`, nested blocks, IDs, URLs and media metadata.
|
|
26
30
|
- Use real IDs from CLI reads for `quiz`, `pageTag`, `learningPathTag`, `resourceTag`, `importedSheet`, `pointRedemption`, `image`, `video`, `vimeo` and `boardly`.
|
|
27
|
-
- Never invent a block type. If it is not in `
|
|
28
|
-
-
|
|
29
|
-
-
|
|
30
|
-
- Use full `pages update --data '{"content": ...}'` only for reviewed migrations.
|
|
31
|
+
- Never invent a block type. If it is not in `page-authoring content-schema`, inspect the app before using it.
|
|
32
|
+
- A `--content-file` replaces the whole body of its locale. Always start from the current draft document, never from a partial or remembered copy.
|
|
33
|
+
- Pass `--lock-version` from `editor` so a concurrent change is refused instead of overwritten.
|
|
31
34
|
|
|
32
35
|
## Common Flow
|
|
33
36
|
|
|
37
|
+
New page:
|
|
38
|
+
|
|
34
39
|
```bash
|
|
35
|
-
gskills-admin
|
|
36
|
-
gskills-admin
|
|
37
|
-
gskills-admin
|
|
38
|
-
gskills-admin pages block replace-text <pageId> --block-id <blockId> --text-file ./block.txt --dry-run --output json
|
|
39
|
-
gskills-admin pages block insert-before <pageId> --block-id <anchorBlockId> --block-file ./block.json --dry-run --output json
|
|
40
|
-
gskills-admin pages block replace-text <pageId> --block-id <blockId> --text-file ./block.txt --expect-type paragraph --yes --output json
|
|
40
|
+
gskills-admin page-authoring content-schema --output json
|
|
41
|
+
gskills-admin page-authoring create --instance global --locale fr --title "..." --slug <slug> --content-file ./page.fr.json --data-file ./spec.json --dry-run --output json
|
|
42
|
+
gskills-admin page-authoring create --instance global --locale fr --title "..." --slug <slug> --content-file ./page.fr.json --data-file ./spec.json --yes --output json
|
|
41
43
|
```
|
|
42
44
|
|
|
43
|
-
|
|
45
|
+
Existing page:
|
|
44
46
|
|
|
45
47
|
```bash
|
|
46
|
-
gskills-admin
|
|
47
|
-
|
|
48
|
+
gskills-admin page-authoring editor <pageId> --instance global --locale fr --include-content --output json > ./editor.fr.json
|
|
49
|
+
# edit draft (or published, when there is no draft) locale content locally into ./page.fr.json
|
|
50
|
+
gskills-admin page-authoring draft <pageId> --instance global --locale fr --content-file ./page.fr.json --lock-version <draft.lockVersion> --dry-run --output json
|
|
51
|
+
gskills-admin page-authoring draft <pageId> --instance global --locale fr --content-file ./page.fr.json --lock-version <draft.lockVersion> --yes --output json
|
|
48
52
|
```
|
|
49
53
|
|
|
54
|
+
Edit the document with a small local script (`jq`, Bun) that targets blocks by `id`, then diff the before/after documents to prove only the intended blocks changed. Images: `page-authoring upload-image --instance <id> --file ./img.png --yes` returns a ready `image` block.
|
|
55
|
+
|
|
50
56
|
## Nested Blocks
|
|
51
57
|
|
|
52
58
|
The main nested block containers are:
|
|
@@ -58,32 +64,18 @@ The main nested block containers are:
|
|
|
58
64
|
- `tabs`: `data.tabs[].content.blocks`
|
|
59
65
|
- `slider`: `data.slides[].content.blocks`
|
|
60
66
|
|
|
61
|
-
When
|
|
67
|
+
When editing nested content, walk those paths and check the target block type and expected text before replacing it.
|
|
62
68
|
|
|
63
|
-
## Good
|
|
64
|
-
|
|
65
|
-
```json
|
|
66
|
-
[
|
|
67
|
-
{ "op": "test", "path": "/blocks/0/type", "value": "paragraph" },
|
|
68
|
-
{ "op": "test", "path": "/blocks/0/data/text", "value": "Ancien texte" },
|
|
69
|
-
{ "op": "replace", "path": "/blocks/0/data/text", "value": "Nouveau texte" }
|
|
70
|
-
]
|
|
71
|
-
```
|
|
69
|
+
## Good Block Shape
|
|
72
70
|
|
|
73
|
-
For inserted blocks, generate a compact valid EditorJS block:
|
|
71
|
+
For inserted blocks, generate a compact valid EditorJS block with a new unique id:
|
|
74
72
|
|
|
75
73
|
```json
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
"id": "codex-note-1",
|
|
82
|
-
"type": "paragraph",
|
|
83
|
-
"data": { "text": "Texte ajoute." }
|
|
84
|
-
}
|
|
85
|
-
}
|
|
86
|
-
]
|
|
74
|
+
{
|
|
75
|
+
"id": "codex-note-1",
|
|
76
|
+
"type": "paragraph",
|
|
77
|
+
"data": { "text": "Texte ajouté." }
|
|
78
|
+
}
|
|
87
79
|
```
|
|
88
80
|
|
|
89
81
|
## Block Choice
|
|
@@ -92,16 +84,17 @@ For inserted blocks, generate a compact valid EditorJS block:
|
|
|
92
84
|
- Use `accordion_tool` for course modules.
|
|
93
85
|
- Use `section_tool` for visual grouping and Gemini sections.
|
|
94
86
|
- Use `tabs`, `slider` and `columns` only when nearby pages already use them or the user asked for that structure.
|
|
95
|
-
- Use `quiz` only with an existing quiz ID.
|
|
96
|
-
- Use `
|
|
87
|
+
- Use `quiz` only with an existing quiz ID (create it with `admin run quizzes.create`, publish with `quizzes.publish`).
|
|
88
|
+
- Use `pedagogicalActivity` only with an existing activity ID. Insert the block (rewards on the block) in the document and save it with `page-authoring draft`.
|
|
89
|
+
- Use `importedSheet` only after inspecting or creating the imported sheet with the CLI; add the block through `page-authoring draft`, not `imported-sheets attach-page`.
|
|
97
90
|
- Use `pageTag`, `learningPathTag` and `resourceTag` only with real same-language rows when available.
|
|
98
91
|
|
|
99
92
|
## After Writing
|
|
100
93
|
|
|
101
94
|
Verify:
|
|
102
95
|
|
|
103
|
-
- dry-run
|
|
104
|
-
- `
|
|
105
|
-
- page
|
|
106
|
-
-
|
|
107
|
-
-
|
|
96
|
+
- the dry-run returned the intended locale, title and block count
|
|
97
|
+
- `page-authoring editor <pageId> --instance <id> --output json` shows the expected draft locales, slugs, block counts and a new lock version
|
|
98
|
+
- `page-authoring readiness` has no blocker you introduced
|
|
99
|
+
- other locales keep their localized IDs and wording (a draft on one locale does not translate the others)
|
|
100
|
+
- nothing is published unless the user asked; then `page-authoring publish --lock-version <n>`
|