@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.
@@ -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: sync drift diagnosis, page visibility bugs, cache invalidation, page metadata backfills, content assistant lookups, content-news checks, or admin ingest repair.
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 and fixing content state with the CLI, sync logs, cache helpers, and production verification.
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 across 49,338 mapped pages.
20
- - Comparing broken and working synced instances when a quiz exists in editor content but does not render on deploy.
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
- ## Sync Drift Investigation
25
-
26
- Use this when a synced page/resource/quiz/path looks different on clients.
30
+ ## Customer Visibility Investigation
27
31
 
28
- 1. Identify source global row and target instance rows.
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
- Known example:
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
- - Google Contacts page source was `disabled=false`, target copies were still `disabled=true`.
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 data repair or sync leaves old deploy data visible.
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 a `Pages` field changed, invalidate page scopes and menu/app scopes when the page appears in menus or app lists.
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
- ## Page Metadata Backfill
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
- ## Source Link Repair
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 After Sync
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
- - Compare the broken instance against a synced working instance.
178
- - Query embedded ids from EditorJS JSON.
179
- - Query relation tables separately.
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
- - broken page id,
186
- - working page id,
187
- - embedded quiz/resource id,
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 broken syncs, compare the target instance against global and against a working synced sibling when useful.
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
- - Broad content synchronisation from global, often with thousands of items.
26
- - Large diffs with many `SKIPPED_CUSTOMIZED` items. This is normal, not automatically a failure.
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
- - Air Liquide syncs should usually start with `sync logs`, then `sync diff`, then a narrow or preset run.
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 sync visibility issues where disabled or archived state and sync logs mattered.
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 sync issues from the URL alone. Use prod data, the exact sync run, `LogsUser`, and the page or parcours family.
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-only or pages plus parcours synchronisation.
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 style pushes.
140
+ These have appeared as new-client onboardings (historically broad first syncs from global).
139
141
 
140
142
  Common work:
141
143
 
142
- - Broad first synchronisation from global.
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 client-content sync unless the live logs say otherwise.
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, modules, quizzes, parcours, badges, menus, resources, and base de connaissance content.
180
- - Compare global to a client instance before sync.
181
- - Keep client customizations intact unless the user explicitly wants to overwrite or repair them.
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
- - existing knowledge media reference changes: `gskills-admin internal-knowledge sync-media`
64
- - source link repair: `gskills-admin sync repair-source-links`
65
- - page metadata backfill: `gskills-admin pages backfill-field --field headerColor`
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 patching GSkills page content, especially EditorJS Pages.content JSON, custom blocks, nested layouts, imported sheets, quizzes, page/resource tags, and AI-agent page edits.
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
- Use this skill whenever Codex creates or edits `Pages.content`.
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 pages content-schema --output json
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 pages content-schema --output json
23
+ bunx @numericoach/gskills-admin-cli@latest page-authoring content-schema --output json
20
24
  ```
21
25
 
22
26
  ## Rules
23
27
 
24
- - Treat `Pages.content` as EditorJS JSON, not markdown.
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 `pages content-schema`, inspect the app before using it.
28
- - For single-block edits, prefer `pages block ...` commands. They find nested blocks by id, generate guarded JSON Patch, validate against this schema, and reuse `pages patch-content`.
29
- - For multi-path edits, use `pages patch-content` with JSON Patch, `test` operations and version or content SHA guards.
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 pages content-schema --output json
36
- gskills-admin pages get <pageId> --fields id,name,language,currentVersion,updatedAt,content --output json
37
- gskills-admin pages block list <pageId> --output json
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
- Raw JSON Patch is still available for multi-path edits:
45
+ Existing page:
44
46
 
45
47
  ```bash
46
- gskills-admin pages patch-content <pageId> --patch-file ./page.patch.json --dry-run --output json
47
- gskills-admin pages patch-content <pageId> --patch-file ./page.patch.json --expect-version <version> --yes --output json
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 patching nested content, use those paths and include a `test` on the target block type or expected text.
67
+ When editing nested content, walk those paths and check the target block type and expected text before replacing it.
62
68
 
63
- ## Good Patch Shape
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
- "op": "add",
79
- "path": "/blocks/2",
80
- "value": {
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 `importedSheet` only after inspecting or creating the imported sheet with the CLI.
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 preview matched the intended block and text deltas
104
- - `currentVersion` changed after the write
105
- - page history exists through the patch route
106
- - cache scopes are refreshed for visible deploy content
107
- - translated sibling pages keep localized IDs and wording
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>`