@numericoach/gskills-admin-cli 0.1.31 → 0.1.33

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.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: gskills-admin-cli
3
- description: Use when an AI agent needs to operate GSkills through the authenticated super-admin CLI, install the CLI skill, inspect schema, list or mutate content, sync global content to an instance, or create GSkills courses with the normal authoring standards.
3
+ description: Use when an AI agent needs to operate GSkills through the authenticated super-admin CLI, install the CLI skill, inspect schema, read content, create, edit or publish canonical pages with page-authoring, or create GSkills courses with the normal authoring standards.
4
4
  ---
5
5
 
6
6
  # GSkills Admin CLI
@@ -13,9 +13,29 @@ Also install and use the companion skills:
13
13
 
14
14
  - `gskills-vocabulary` when explaining work to admins or writing user-facing summaries.
15
15
  - `gskills-customer-playbooks` when the task names a recurring GSkills customer.
16
- - `gskills-page-content-blocks` before creating or patching `Pages.content`.
16
+ - `gskills-page-content-blocks` before composing or editing a page's EditorJS document.
17
17
  - `gskills-admin-cli-publishing` when publishing the npm package or sharing the publish recipe with another teammate.
18
18
 
19
+ ## Since the content migration (Sept 2026)
20
+
21
+ Every instance and every content family is canonical-primary. Legacy content storage no longer accepts CLI writes.
22
+
23
+ - Never write content through Legacy commands. `pages create/update/delete`, `pages block <write>`, `pages patch-content`, `pages activity <write>`, `pages backfill-field`, raw create/update/delete/set-icon/sync-media on topics, resources, internal-knowledge, learning-paths (items, groups), chromebook-*, quizzes (questions, options), badges, menus, menu-sections and workflows (actions, `create-configured`), `pedagogical-activities attach-page/add-to-page/attach-learning-path`, `imported-sheets attach-page`, `sync run`, `sync repair-source-links` and `translate quizzes|menus|menu-sections` are refused with `LEGACY_CONTENT_WRITE_RETIRED`.
24
+ - Pages: author them with `gskills-admin page-authoring` (see [Page authoring](#page-authoring)).
25
+ - Every other family (quizzes, learning paths, categories, menus, knowledge, resources, badges, Chromebook, activities, workflows, availability, tags): `gskills-admin admin` operations, which run the exact admin UI code (see [Admin operations](#admin-operations)). Workflow: `admin ops --family <f>` → `admin describe <op>` → read state → `admin run <op> --dry-run` → `--yes` → re-read.
26
+ - Reads (`list`, `get`, `help`, `content-schema`, `pages block list|get`) still answer, but Legacy `pages` rows are stale. Read page content with `page-authoring editor`.
27
+ - If a command returns `LEGACY_CONTENT_WRITE_RETIRED`, follow its `details.nextAction` (it names the `admin ops --family` to use). Never work around it with direct DB, Prisma, SQL or a repo script.
28
+ - Sync is gone: shared canonical content is inherited by every instance (ADR-003). A customer opts out only through `admin run catalogue.hide` (and back with `catalogue.restore`).
29
+ - `page-authoring` and `admin` need the next npm release (> 0.1.31) and the matching app deployment. Until both are out they return 404: say so and hand the change to the admin UI, never a Legacy fallback.
30
+
31
+ ## Content platform migration and ADRs
32
+
33
+ Before operating migrated content, run `gskills-admin content-platform help --output json`. The same directives are included in `schema --output json`. Read the [migration operations guide](references/content-platform.md) before using the examples below on a migrated instance.
34
+
35
+ Use `content-platform tables` to browse every migration table, `content-platform explain <resource>` for its purpose and example, or the [complete table reference](references/content-platform-tables.md). The same entry is included in each resource's `help` and in `schema`.
36
+
37
+ Raw canonical resources are read-only. Pages are written through `page-authoring`, and every other admin UI write through `admin run <op>`; both run the exact admin code paths.
38
+
19
39
  ## Install
20
40
 
21
41
  ```bash
@@ -48,62 +68,84 @@ gskills-admin resources --output table
48
68
  3. Use JSON for scripts and JSONL for pipelines.
49
69
 
50
70
  ```bash
51
- gskills-admin pages list --fields id,name,slug,language,instanceId --output json
52
- gskills-admin pages list --take 100 --output jsonl
71
+ gskills-admin canonical-pages list --where '{"ownerInstanceId":null}' --output json
72
+ gskills-admin page-authoring editor <pageId> --instance global --output json
73
+ gskills-admin instances list --take 100 --output jsonl
53
74
  ```
54
75
 
55
76
  4. Dry-run writes first.
56
77
 
57
78
  ```bash
58
- gskills-admin pages create --data '{"name":"Draft","slug":"draft","language":"fr","disabled":true,"archived":false}' --dry-run --output json
59
- gskills-admin pages update <id> --data '{"disabled":false}' --dry-run --output json
60
- gskills-admin pages create --data-file ./page.json --dry-run --output json
79
+ gskills-admin page-authoring create --instance global --locale fr --title "Brouillon" --content-file ./page.fr.json --dry-run --output json
80
+ gskills-admin page-authoring draft <pageId> --instance global --locale fr --content-file ./page.fr.json --lock-version <n> --dry-run --output json
61
81
  ```
62
82
 
63
83
  5. Apply the exact same command with `--yes` only after the payload is correct.
64
84
 
65
- 6. For visible content changes, check the resource cache hint and refresh cache when needed.
85
+ 6. Re-read what you changed. Canonical publication advances the content scope versions itself; manual cache invalidation is not publication. Invalidate cache only when a visible surface is still stale after a verified write.
66
86
 
67
87
  ```bash
68
- gskills-admin pages help --output json
69
88
  gskills-admin cache invalidate --instance <instanceId> --scope pages --dry-run --output json
70
89
  gskills-admin cache invalidate --instance <instanceId> --scope pages --yes --output json
71
90
  ```
72
91
 
73
- CRUD help exposes `cache.scopes` for resources that are known to feed deploy caches. After create, update, or delete, the database can be correct while the end-user view is still stale. Use the narrowest listed scope first. Use `all` only when the changed setting affects many deploy surfaces or when the narrow scope did not clear the visible stale state.
92
+ Every write requires `--dry-run` or `--yes`. Use `--content-file` / `--data-file` for large JSON payloads. Do not inline full EditorJS content in shell strings.
74
93
 
75
- Generic `create` and `update` require `--dry-run` or `--yes`. Use `--data-file` for large JSON payloads. Do not ask agents to inline full EditorJS content in shell strings.
94
+ ## Page authoring
76
95
 
77
- For page body edits, prefer the granular block helpers when a stable block id exists:
96
+ `page-authoring` runs the same repository commands as the admin page editor, with the CLI super admin as actor. It is the only CLI write path for pages (`Page`, `PageLocale`, `PageRevision`). `gskills-admin page-authoring help --output json` is the live contract.
78
97
 
79
98
  ```bash
80
- gskills-admin pages content-schema --output json
81
- gskills-admin pages get <pageId> --fields id,name,language,currentVersion,updatedAt,content --output json
82
- gskills-admin pages block list <pageId> --output json
83
- gskills-admin pages block replace-text <pageId> --block-id <blockId> --text-file ./block.txt --dry-run --output json
84
- gskills-admin pages block insert-before <pageId> --block-id <anchorBlockId> --block-file ./block.json --dry-run --output json
85
- gskills-admin pages block replace-text <pageId> --block-id <blockId> --text-file ./block.txt --reason "Fix wording" --yes --output json
99
+ gskills-admin page-authoring help --output json
100
+ gskills-admin page-authoring content-schema --output json
101
+ gskills-admin page-authoring editor <pageId> --instance global --locale fr --include-content --output json
102
+ gskills-admin page-authoring readiness <pageId> --instance global --output json
103
+ gskills-admin page-authoring upload-image --instance global --file ./capture.png --yes --output json
104
+ gskills-admin page-authoring create --instance global --locale fr --title "Gemini dans Meet" --slug gemini-dans-meet --content-file ./page.fr.json --data-file ./spec.json --dry-run --output json
105
+ gskills-admin page-authoring draft <pageId> --instance global --locale fr --content-file ./page.fr.json --lock-version <n> --dry-run --output json
106
+ gskills-admin page-authoring draft <pageId> --instance global --locale en --title "Gemini in Meet" --content-file ./page.en.json --yes --output json
107
+ gskills-admin page-authoring publish <pageId> --instance global --lock-version <n> --note "Première version" --dry-run --output json
86
108
  ```
87
109
 
88
- Use raw `pages patch-content` only when the edit really needs multiple JSON paths:
110
+ Semantics:
89
111
 
90
- ```bash
91
- gskills-admin pages patch-content <pageId> --patch-file ./page.patch.json --dry-run --output json
92
- gskills-admin pages patch-content <pageId> --patch-file ./page.patch.json --expect-version 7 --expect-content-sha1 <sha1> --reason "Fix wording" --yes --output json
112
+ - `--instance` is required. Use `global` for Numericoach content. A customer instance authors only pages it owns; it cannot edit shared pages.
113
+ - `create` makes the page family and its first private draft. Nothing is visible until `publish`, or `create --publish` when the user explicitly asked for publication. The old "`disabled` on global = draft" convention is obsolete.
114
+ - On `--instance global` the page is shared with every instance (`ownerInstanceId = null`). Add `--dedicated` only when it must stay on global.
115
+ - Retrying `create` with the same instance, locale and slug replays the existing page (`replayed: true`) instead of duplicating it. Still pick an explicit slug and check it first with `page-route-claims list --where '{"locale":"fr","slug":"<slug>"}'`.
116
+ - `--content-file` is one EditorJS document `{ "blocks": [...] }` for `--locale` (create defaults to `fr`) and replaces that locale's whole body.
117
+ - `--data-file` is the full spec; flags override it. Settings fields: `contentType` (`COURSES`, `TUTORIALS`, `LEARNING_PATHS`), `headerColor`, `pageIcon`, `necessaryPlans`, `frenchOnly`, `alphaProgramIds`, `sharedSettings`, `categories` (canonical category family ids from `content-family-identities`), `manualReadingTimeMinutes`.
118
+
119
+ ```json
120
+ {
121
+ "locales": {
122
+ "fr": { "title": "Gemini dans Meet", "slug": "gemini-dans-meet", "description": "…", "publicationRequirement": "REQUIRED" }
123
+ },
124
+ "settings": {
125
+ "contentType": "TUTORIALS",
126
+ "categories": [{ "categoryFamilyId": "<familyId>", "order": 0 }]
127
+ },
128
+ "note": "Création depuis le brief"
129
+ }
93
130
  ```
94
131
 
95
- Patch files are RFC 6902 JSON Patch arrays:
132
+ - Body edits: read `editor --include-content`, modify the EditorJS document locally, send it back with `draft --content-file` and the `--lock-version` read from `editor` (`draft.lockVersion`). A stale lock version is refused instead of overwriting someone else's change.
133
+ - A new locale added through `draft` is `OPTIONAL` for publication.
134
+ - Drafts never change the live page. `readiness` lists publication blockers. `publish` validates the persisted draft and creates the next immutable version, or refuses with the blocker list.
135
+ - Restore, archive, unpublish, audience and locale add/retire/validate are `admin` operations of the `pages` family (`pages.restore-revision`, `pages.archive`, `pages.unpublish`, `pages.audience.save`, `pages.locale.*`).
96
136
 
97
- ```json
98
- [
99
- { "op": "test", "path": "/blocks/0/type", "value": "paragraph" },
100
- { "op": "replace", "path": "/blocks/0/data/text", "value": "Updated paragraph text" }
101
- ]
137
+ Verify every page write, then publish only if the user asked for publication:
138
+
139
+ ```bash
140
+ gskills-admin page-authoring editor <pageId> --instance global --output json
141
+ gskills-admin page-authoring readiness <pageId> --instance global --output json
102
142
  ```
103
143
 
104
- The block helpers read the full page content, find nested blocks by id, generate guarded JSON Patch, validate the predicted full content against `pages content-schema`, call `pages patch-content`, then reread and validate the page after real writes. The patch route previews block/text deltas, stores page history, refreshes the page vector, invalidates `pages` and `pages-knowledge`, logs the write, and rejects stale `updatedAt`, version, or content SHA guards. Keep full-content `pages update --data '{"content": ...}'` for expert migrations only.
144
+ Check draft locales, titles, slugs, block counts and lock version, then readiness. After a publish, re-read `editor` and confirm the new published revision.
145
+
146
+ `page-authoring content-schema` is the machine-readable source of truth for supported EditorJS/GSkills blocks, nested child-block paths, immutable reference fields and examples. Read it before generating page content, and use `gskills-page-content-blocks` for block authoring.
105
147
 
106
- `pages content-schema` is the machine-readable source of truth for supported EditorJS/GSkills blocks, nested child-block paths, immutable reference fields and examples. Agents should call it before generating or patching page content.
148
+ Page images go through `page-authoring upload-image`: it streams the local file to GSkills storage through a signed URL and returns `fileUrl` plus a ready EditorJS `image` block (`editorJsBlock`). Use `--mime-type` when the extension is ambiguous and `--upload-name` when the stored name should differ. Knowledge and resource media are referenced by URL in `knowledge.create` / `resources.create`: upload the file first with `gskills-admin upload --instance <id> --for knowledge|resource --file <path> --yes` (PDF, video, any file; `--for page-image` for images) and pass the returned `fileUrl`. `internal-knowledge` / `resources` create and update with `--upload-file` are retired.
107
149
 
108
150
  Content governance and page comments use the same data and write paths as the super-admin governance UI:
109
151
 
@@ -127,41 +169,67 @@ gskills-admin page-comments resolve <commentId> --dry-run --output json
127
169
 
128
170
  Governance and page-comment writes require `--dry-run` or `--yes`. Task deletion also requires `--force --confirm-delete governance:<entryId>`.
129
171
 
130
- Internal knowledge and resources support direct local file uploads through signed GCS URLs. The CLI gets a signed URL from the authenticated app API, streams the local file directly to storage, then writes the normal row with the returned URL. This avoids routing large videos through a Next.js API body.
172
+ Learning path icons are set with `admin run learning-paths.update` (`data.iconUrl`); `learning-paths set-icon` is retired like every other Legacy learning path write. `learning-paths generate-icon` still generates an icon image. `learning-paths icons --query Gmail --output json` still lists the French global category app icons for reference.
131
173
 
132
- ```bash
133
- gskills-admin internal-knowledge create --instance dev-numericoach --upload-file ./capsule.mp4 --data '{"title":"Capsule test","language":"fr","isActive":true,"isAIAllowed":false}' --dry-run --output json
134
- gskills-admin internal-knowledge update <knowledgeId> --instance dev-numericoach --upload-file ./capsule-v2.mp4 --data '{}' --dry-run --output json
135
- gskills-admin resources create --instance dev-numericoach --upload-file ./webinar.mp4 --data '{"title":"Webinar test","type":"WEBINAR","language":"fr","isActive":true}' --dry-run --output json
136
- gskills-admin resources update <resourceId> --instance dev-numericoach --upload-file ./webinar-v2.mp4 --data '{}' --dry-run --output json
137
- ```
174
+ Do not use an app logo as a parcours icon unless the user explicitly asks for it. Most parcours icons should be symbolic; repeating app logos across every learning path gets visually heavy.
138
175
 
139
- Use `--mime-type` when the extension is ambiguous and `--upload-name` when the stored file name should differ from the local basename. Always pass `--instance` for client-specific content; otherwise content-like creates default to `global`.
176
+ Raw content deletes (`pages delete` and every other content resource) are retired: use the family's `admin` operation (`pages.archive`, `pages.unpublish`, `quizzes.set-archive`, `learning-paths.set-archived`, `knowledge.set-archived`, `<family>.delete` …) after reading the target and only when the user asked. For the remaining non-content resources, delete commands are soft-only: they need `--force` and an exact `--confirm-delete <resource>:<id>` token, write the safest inactive field, and must be followed by a re-read that verifies it.
140
177
 
141
- Learning path icons support the same sources as the super-admin editor:
178
+ Never add `--confirm-delete` unless the user explicitly asked to remove something from visibility and the target row was read first. The CLI must not permanently delete production data.
142
179
 
143
- ```bash
144
- gskills-admin learning-paths icons --query Gmail --output json
145
- gskills-admin learning-paths set-icon <learningPathId> --app Gmail --dry-run --output json
146
- gskills-admin learning-paths set-icon <learningPathId> --upload-file ./icon.png --instance dev-numericoach --dry-run --output json
147
- gskills-admin learning-paths generate-icon <learningPathId> --prompt "flat central handshake, transparent background" --dry-run --output json
148
- gskills-admin learning-paths generate-icon <learningPathId> --prompt-file ./icon-prompt.txt --yes --output json
149
- ```
180
+ CLI create, update, and delete operations are written to the GSkills admin logs with the authenticated user, entity snapshots, and CLI metadata. When Codex runs the CLI, the log metadata includes `actorType = "cli"` and `agent = "codex"`.
181
+
182
+ ## Admin operations
150
183
 
151
- `icons` reads only French global category app icons. `set-icon --upload-file` streams the local image through the signed upload path and writes `LearningPath.iconUrl`. `generate-icon` calls the same server-side image generator used by the editor, including the same prompt and post-processing.
184
+ `gskills-admin admin` runs, by name, the exact use case or admin server action the admin UI calls, as the authenticated super admin: same validation, authority fences, identity bridging, cache invalidation and audit logs. It covers every content family except page bodies (those go through `page-authoring`).
152
185
 
153
- Do not pass `--use-app-icon` unless the user explicitly asks for the app logo to appear. It is off by default because most parcours icons should be symbolic. Repeating app logos across every learning path gets visually heavy and often produces cluttered, low-quality icons.
186
+ Workflow for every change:
154
187
 
155
- Delete commands are soft-only. They require both `--force` and an exact confirmation token, then write the safest inactive field available, preferring `archived: true` when the resource supports it and otherwise falling back to fields such as `disabled: true`, `isActive: false`, or `active: false`. If a resource cannot be safely disabled, the CLI refuses the delete command. After a real delete, re-read the row and verify the inactive field was written.
188
+ 1. Find the operation: `admin ops --family <family>`.
189
+ 2. Read its contract: `admin describe <op>` (use-case operations also return the input JSON Schema).
190
+ 3. Read the current state with the family's read operation (`*.list`, `*.read`, `*.editor`, `*.revisions`) or resource `list`/`get` to get real ids, lock versions and authority epochs.
191
+ 4. `admin run <op> --data-file ./input.json --dry-run`.
192
+ 5. `admin run <op> --data-file ./input.json --yes`.
193
+ 6. Re-read with the read operation and verify the visible result.
156
194
 
157
195
  ```bash
158
- gskills-admin pages delete <id> --force --confirm-delete pages:<id> --dry-run --output json
159
- gskills-admin pages delete <id> --force --confirm-delete pages:<id> --output json
196
+ gskills-admin admin ops --family quizzes --output json
197
+ gskills-admin admin describe quizzes.publish --output json
198
+ gskills-admin admin run quizzes.list --data '{"instanceId":"global"}' --yes --output json
199
+ gskills-admin admin run learning-paths.update --data-file ./lp.json --dry-run --output json
200
+ gskills-admin admin run learning-paths.update --data-file ./lp.json --yes --output json
160
201
  ```
161
202
 
162
- Never add `--confirm-delete` unless the user explicitly asked to remove something from visibility and the target row was read first. The CLI must not permanently delete production data.
203
+ Rules:
163
204
 
164
- CLI create, update, and delete operations are written to the GSkills admin logs with the authenticated user, entity snapshots, and CLI metadata. When Codex runs the CLI, the log metadata includes `actorType = "cli"` and `agent = "codex"`.
205
+ - `admin run` always needs `--dry-run` or `--yes`, read operations included (a read with `--yes` writes nothing).
206
+ - On use-case operations, `--dry-run` runs identity, validation and authorization without writing. On action operations it only checks the input shape, so read the state first.
207
+ - Action operations take their named parameters as one JSON object, for example `{"instanceId":"global","data":{...}}` for `learning-paths.create` or `{"learningPathId":"…","data":{...}}` for `learning-paths.update`. Use-case operations take the payload shown by `describe`.
208
+ - Errors carry `details.code`, `retryable` and `nextAction`; `INVALID_INPUT` also lists field issues. On `CONFLICT`, re-read and retry with the fresh lock version or epoch. Never force.
209
+ - Shared Numericoach content is owned by `global`. A customer instance only hides/restores inherited content (`catalogue.hide|restore`) or authors its own content.
210
+ - `learning-paths.update` takes the COMPLETE item/group list: omitted items are retired, existing items keep `id` and `stableIdentityId`. If it refuses with a structural impact, rerun with `structuralImpactAcknowledgement` from the refusal only after the user agreed.
211
+ - Learning path activity placement = an `ACTIVITY` item added through `learning-paths.update`. Page activity placement = the `pedagogicalActivity` block through `page-authoring draft`.
212
+ - Quizzes: `quizzes.create` / `quizzes.update` change the content, `quizzes.publish` creates the immutable revision learners see.
213
+ - Workflows: `workflows.create` → `workflows.save-draft` → `workflows.publish` → `workflows.activation.update` per instance (or `workflows.rollout.*` across customers). Publishing never activates.
214
+
215
+ | Family (`--family`) | Operations |
216
+ | --- | --- |
217
+ | `pages` | `pages.list`, `versions`, `diff-revisions`, `audience.read|save`, `unpublish`, `archive`, `recover-archived`, `restore-revision`, `locale.add|retire|reactivate|validate|validate-others`, `translate-draft-locale`, `queue-draft-translations` (drafts and publish: `page-authoring`) |
218
+ | `quizzes` | `quizzes.list`, `revisions`, `revision`, `learning-path-usage`, `create` (locale = `parentId`), `update`, `publish`, `set-publication`, `set-archive`, `delete` |
219
+ | `learning-paths` | `learning-paths.create`, `update`, `create-translation`, `set-disabled`, `set-archived`, `duplicate`, `delete` |
220
+ | `categories` | `categories.create`, `toggle-active`, `upsert-translation`, `set-disabled`, `set-archived`, `set-icon`, `delete`, `delete-family`, `thematic-activation`, `thematic-archive` |
221
+ | `menus` | customer overlay: `menus.read`, `preview-mode`, `change-mode`, `create-node`, `update-node`, `archive-node`, `restore-node`, `place-node`, `hide-inherited`, `restore-inherited`, `enable-category`, `enable-page`; shared global menu: `menus.global.create|update|delete-section`, `create|update|delete-item`, `reorder-items`, `reorder-sections` |
222
+ | `knowledge` | `knowledge.list`, `change` (settings / promote), `create`, `update`, `create-translation`, `update-translation`, `localize-video`, `remove-localization-job`, `toggle-active`, `set-disabled`, `set-archived`, `bulk-set-archived`, `bulk-set-active`, `delete`, `delete-translation`, `bulk-delete` |
223
+ | `resources` | `resources.create` (locale = same title and type in another language), `update`, `toggle-active`, `set-disabled`, `set-archived`, `delete` |
224
+ | `badges` | `badges.create`, `update`, `upsert-translation`, `set-disabled`, `set-archived`, `delete` |
225
+ | `chromebook` | `chromebook.create` (locale = `parentId`), `update`, `delete` |
226
+ | `activities` | `activities.save`, `quick-create`, `set-archived`, `delete` |
227
+ | `workflows` | `workflows.list`, `editor`, `versions`, `revision`, `activation`, `activation-detail`, `dry-run`, `simulate`, `preview-email`, `create`, `ensure-draft`, `save-draft`, `publish`, `restore-revision`, `archive`, `activation.update`, `list-administration`, `rollout.candidates|preview|apply`, `deploy-shared` |
228
+ | `availability` | `catalogue.list`, `catalogue.hide`, `catalogue.restore` |
229
+ | `content` | `content.replace-tags`, `replace-alpha`, `create-tag`, `migration-status` |
230
+ | `integrations` | `gemini-embed.save` |
231
+
232
+ `src/lib/server/cli-admin-operations.ts` in the app is the source of truth; `admin ops` always reflects the deployed catalogue.
165
233
 
166
234
  ## CLI Plus Code Rule
167
235
 
@@ -199,13 +267,13 @@ These recurring historical DB-only jobs now have CLI paths:
199
267
  | Import client email into feedback rows | `gskills-admin feedback import-email --data-file ./feedback-email.json --dry-run --output json` |
200
268
  | Customer reply from a resolved ticket | `gskills-admin feedback send-reply <feedbackId> --subject "..." --body-file ./reply.txt --dry-run --output json` |
201
269
  | Access-pass truth for a user | `gskills-admin access diagnose --email user@example.com --instance <instanceId> --output json` |
202
- | Existing global knowledge video URL changed | `gskills-admin internal-knowledge sync-media --source global --since today --languages fr --all-targets --dry-run --output json` |
203
- | Source-link drift after sync | `gskills-admin sync repair-source-links --target <instanceId> --dry-run --output json` |
204
- | Page metadata backfill from global copies | `gskills-admin pages backfill-field --field headerColor --all-targets --dry-run --output json` |
205
- | Page block schema for agents | `gskills-admin pages content-schema --output json` |
206
- | Single page block edit by id | `gskills-admin pages block replace-text <pageId> --block-id <blockId> --text-file ./block.txt --dry-run --output json` |
207
- | Insert a page block near another block | `gskills-admin pages block insert-before <pageId> --block-id <anchorBlockId> --block-file ./block.json --dry-run --output json` |
208
- | Page body patch with history/vector/cache | `gskills-admin pages patch-content <pageId> --patch-file ./page.patch.json --dry-run --output json` |
270
+ | Page block schema for agents | `gskills-admin page-authoring content-schema --output json` |
271
+ | Read a page (draft, published, locales, body) | `gskills-admin page-authoring editor <pageId> --instance global --include-content --output json` |
272
+ | Create a page | `gskills-admin page-authoring create --instance global --locale fr --title "..." --content-file ./page.fr.json --dry-run --output json` |
273
+ | Edit a page body or add a locale | `gskills-admin page-authoring draft <pageId> --instance global --locale fr --content-file ./page.fr.json --lock-version <n> --dry-run --output json` |
274
+ | Publish a page | `gskills-admin page-authoring publish <pageId> --instance global --lock-version <n> --dry-run --output json` |
275
+ | Upload a page image | `gskills-admin page-authoring upload-image --instance global --file ./capture.png --yes --output json` |
276
+ | Any other content change (quiz, parcours, menu, knowledge, resource, badge, Chromebook, workflow, category, availability) | `gskills-admin admin ops --family <family>` then `admin run <op> --data-file ./input.json --dry-run --output json` |
209
277
  | Passed quiz did not complete a page/course | `gskills-admin progress embedded-course --user <userId> --quiz <quizId> --page <pageId> --dry-run --output json` |
210
278
  | Passed learning-path quiz missing completion row | `gskills-admin progress learning-path-quiz-mismatches --instance <instanceId> --output json` then `gskills-admin progress repair-learning-path-quiz-mismatches --instance <instanceId> --dry-run --output json` |
211
279
  | Force relogin after access/auth data change | `gskills-admin sessions invalidate --email user@example.com --dry-run --output json` |
@@ -213,7 +281,7 @@ These recurring historical DB-only jobs now have CLI paths:
213
281
  | Admin ingest incomplete sync repair | `gskills-admin admin-ingest repair-state --instance <instanceId> --output json` then `gskills-admin admin-ingest repair --instance <instanceId> --dry-run --output json` |
214
282
  | Imported-sheet row-cell repair or media enrichment | `gskills-admin imported-sheets patch-cells <sheetId> --instance <instanceId> --data-file ./cell-patches.json --dry-run --output json` |
215
283
 
216
- If a job is not in this table, first try `gskills-admin schema --output json` and resource CRUD. If the route is still missing and the job is recurring, add the CLI route before reaching for direct DB access.
284
+ Retired content jobs (knowledge `sync-media`, `sync repair-source-links`, `pages backfill-field`, `pages block`, `pages patch-content`) have no one-to-one replacement: canonical content is edited once (`page-authoring` or `admin run <family>.*`) and inherited. If a job is not in this table, first try `gskills-admin schema --output json` and resource CRUD on non-content resources. If the route is still missing and the job is recurring, add the CLI route before reaching for direct DB access.
217
285
 
218
286
  `gskills-admin skills install`, `skills path`, and `skills help` are for bundled Codex skills. `skills list`, `skills get`, `skills create`, `skills update`, and `skills delete` operate on the app skill catalog. Use `skill-content-links` when associating pages, quizzes, parcours items, knowledge, or resources to skills.
219
287
 
@@ -257,26 +325,15 @@ Rules:
257
325
 
258
326
  ## Instance Rules
259
327
 
260
- If `--instance` is omitted, content-like resources default to `instanceId = "global"`.
328
+ Canonical ownership replaces per-instance copies:
261
329
 
262
- On `global`, `disabled: true` means draft for newly created content. The CLI create path defaults to `disabled: true` on global resources that support it unless the payload explicitly says otherwise. On client instances, `disabled: true` means hidden or disabled.
330
+ - `ownerInstanceId = null`: shared content, authored on `global` and inherited by every instance.
331
+ - `ownerInstanceId = "global"`: dedicated to global (`page-authoring create --dedicated`), not shared.
332
+ - `ownerInstanceId = <customerId>`: owned by that customer and authored with that instance id.
263
333
 
264
- This applies to:
334
+ `disabled` is not a draft flag anymore. Unpublished work lives in the private draft until it is published. A customer hides inherited content with `admin run catalogue.hide` (and shows it again with `catalogue.restore`), never by editing a copy. Read the effective catalogue with `admin run catalogue.list --yes`, or diagnose with `instance-content-availability` and `instance-content-locale-availability` (a missing row means inherited, not hidden).
265
335
 
266
- - `pages`
267
- - `topics`
268
- - `resources`
269
- - `internal-knowledge`
270
- - `learning-paths`
271
- - `quizzes`
272
- - `badges`
273
- - `menus`
274
- - `menu-sections`
275
- - `workflows`
276
-
277
- Still pass `--instance <instanceId>` when the user explicitly targets a client instance.
278
-
279
- Never guess a client instance from a name if the CLI can list it:
336
+ Always pass the instance explicitly. Never guess a client instance from a name if the CLI can list it:
280
337
 
281
338
  ```bash
282
339
  gskills-admin instances list --where '{"name":{"contains":"Air Liquide","mode":"insensitive"}}' --output json
@@ -284,23 +341,27 @@ gskills-admin instances list --where '{"name":{"contains":"Air Liquide","mode":"
284
341
 
285
342
  ## Workflow Authoring
286
343
 
287
- Use the guided workflow commands before raw `workflows` and `workflow-actions` CRUD.
344
+ Workflows are canonical definitions with numbered revisions and per-instance activations. Author them with the `workflows` admin operations (`admin ops --family workflows`); `workflows create-configured` and raw `workflows` / `workflow-actions` writes are retired.
288
345
 
289
346
  ```bash
290
- gskills-admin workflows schema --output json
291
347
  gskills-admin workflows schema --trigger LEARNING_PATH_NOT_STARTED --output json
292
- gskills-admin workflows example --trigger LEARNING_PATH_NOT_STARTED --output json
293
- gskills-admin workflows preview-email --data-file ./workflow.json --fake --language fr --output json
294
- gskills-admin workflows preview-email --data-file ./workflow.json --user user@example.com --language fr --output json
295
- gskills-admin workflows create-configured --instance global --data-file ./workflow.json --inactive --dry-run --output json
296
- gskills-admin workflows create-configured --instance global --data-file ./workflow.json --active --yes --output json
348
+ gskills-admin admin describe workflows.save-draft --output json
349
+ gskills-admin admin run workflows.create --data-file ./wf-create.json --dry-run --output json
350
+ gskills-admin admin run workflows.editor --data-file ./wf-ref.json --yes --output json
351
+ gskills-admin admin run workflows.save-draft --data-file ./wf-draft.json --dry-run --output json
352
+ gskills-admin admin run workflows.dry-run --data-file ./wf-sample.json --yes --output json
353
+ gskills-admin admin run workflows.publish --data-file ./wf-publish.json --dry-run --output json
354
+ gskills-admin admin run workflows.activation.update --data-file ./wf-activate.json --dry-run --output json
297
355
  ```
298
356
 
299
- `workflows schema` is the machine-readable source of truth for supported workflow triggers, actions, trigger config, trigger payloads, email variables, button placeholders and examples.
300
-
301
- `create-configured` creates the workflow and all actions in one operation. It requires an activation decision. Ask the human whether to enable the workflow now, then pass `--active` or `--inactive`. Prefer `--inactive` until trigger ids, recipients, translations and preview email are approved.
357
+ 1. `workflows.create` (`{ instanceId, definitionScope: GLOBAL|INSTANCE, name, description }`) creates the definition and its first draft.
358
+ 2. `workflows.editor` returns the draft revision id and `expectedLockVersion`.
359
+ 3. `workflows.save-draft` saves the trigger and the COMPLETE action list.
360
+ 4. `workflows.dry-run` / `workflows.simulate` check it against sample data; `workflows.preview-email` sends a real preview email, so only to an address the user approved.
361
+ 5. `workflows.publish` creates the next revision. It does not activate anything.
362
+ 6. `workflows.activation.update` activates or pins a revision per instance (`SAVE_BINDINGS`, `ACTIVATE`, `UPDATE_REVISION`, `DISABLE`, `REACTIVATE`); `workflows.rollout.candidates|preview|apply` pins a global revision across customers.
302
363
 
303
- Email actions use `config.templates`, a map of language code to `{ subject, body }`. Keep variables unchanged across translations. `preview-email` renders the exact subject and body without sending anything. Use `--fake` for sample trigger data, or `--user` / `--email` to preview with a real user.
364
+ Ask the human before activating. `workflows schema` / `workflows example` still describe the triggers, actions, variables and placeholders. Email templates are a map of language code to `{ subject, body }`; keep variables unchanged across translations.
304
365
 
305
366
  ## Auth Model
306
367
 
@@ -314,7 +375,7 @@ If `whoami` fails, stop and login again. Do not work around auth with copied bro
314
375
 
315
376
  ## Content Authoring
316
377
 
317
- Before creating or updating course content, inspect nearby examples.
378
+ Before creating or updating course content, inspect nearby examples with `page-authoring editor --include-content`.
318
379
 
319
380
  Good GSkills content usually has:
320
381
 
@@ -324,77 +385,81 @@ Good GSkills content usually has:
324
385
  - accordions for step-by-step instructions
325
386
  - sections for bigger modules
326
387
  - images only when they teach something
327
- - quizzes when the page family uses quizzes
328
- - a category connection
329
- - a menu item under the right parent
388
+ - quizzes when the page family uses quizzes (`admin run quizzes.create`, then `quizzes.publish`, then embed the quiz by id)
389
+ - a category connection (`settings.categories`)
390
+ - no menu item unless the user explicitly asks for navigation, publishing placement, or a visible deploy entry (then `menus.*` operations)
330
391
 
331
392
  For French content, write real French with accents. Avoid generic AI filler. Match the tone of the strongest current exemplar, not the most recent half-finished page.
332
393
 
333
394
  Typical create flow:
334
395
 
335
396
  ```bash
336
- gskills-admin pages list --where '{"language":"fr","slug":{"contains":"gmail"}}' --fields id,name,slug,language,instanceId,contentType --output json
337
- gskills-admin topics list --where '{"language":"fr"}' --fields id,name,slug,instanceId --output json
338
- gskills-admin menus list --where '{"instanceId":"global"}' --fields id,name,parentId,pageId,url,instanceId --output json
339
- gskills-admin pages create --data-file ./page.json --dry-run --output json
340
- gskills-admin pages create --data-file ./page.json --yes --output json
397
+ gskills-admin canonical-pages list --where '{"ownerInstanceId":null}' --output json
398
+ gskills-admin page-authoring editor <exemplarPageId> --instance global --locale fr --include-content --output json
399
+ gskills-admin content-family-identities list --where '{"contentType":"CATEGORY"}' --output json
400
+ gskills-admin page-route-claims list --where '{"locale":"fr","slug":"<candidate-slug>"}' --output json
401
+ gskills-admin page-authoring create --instance global --locale fr --title "..." --slug <candidate-slug> --content-file ./page.fr.json --data-file ./spec.json --dry-run --output json
402
+ gskills-admin page-authoring create --instance global --locale fr --title "..." --slug <candidate-slug> --content-file ./page.fr.json --data-file ./spec.json --yes --output json
403
+ gskills-admin page-authoring editor <pageId> --instance global --output json
404
+ gskills-admin page-authoring readiness <pageId> --instance global --output json
341
405
  ```
342
406
 
343
- For edits to an existing page body, use `pages block ...` when targeting one stable block id. Use `pages patch-content` for reviewed multi-path patches. Avoid rewriting the whole `content` JSON unless you are doing a reviewed migration.
407
+ For edits to an existing page body, read the draft with `editor --include-content`, edit the document locally, and send it back with `draft --content-file --lock-version <n>`. Keep block ids, nested blocks and embedded ids intact.
344
408
 
345
- ## AI Translation
346
-
347
- Use `translate` when content already has AI translation in its editor and the same operation is needed from the CLI.
409
+ ## Pedagogical Activities
348
410
 
349
- Supported content kinds:
411
+ Use the dedicated activity commands to create, update and translate a pedagogical activity (`admin run activities.save|quick-create|set-archived|delete` are the admin UI equivalents).
350
412
 
351
- - `pages`
352
- - `quizzes`
353
- - `topics`
354
- - `badges`
355
- - `menus`
356
- - `menu-sections`
357
- - `internal-knowledge`
358
- - `knowledge-video`
359
- - `learning-paths`
360
- - `chromebook-exercises`
361
-
362
- Selection can be one source row, several source rows, or all matching rows:
363
-
364
- ```bash
365
- gskills-admin translate pages <pageId> --to en,es --dry-run --output json
366
- gskills-admin translate pages <pageId> --from fr --to en,es --mode patch --dry-run --output json
367
- gskills-admin translate pages --ids <pageId,pageId> --from fr --to en --dry-run --output json
368
- gskills-admin translate pages --all --instance global --from fr --to en --take 100 --dry-run --output json
369
- gskills-admin translate quizzes <quizId> --to en --yes --output json
370
- gskills-admin translate knowledge-video <knowledgeId> --from en --to es --yes --output json
413
+ ```bash
414
+ gskills-admin pedagogical-activities schema --output json
415
+ gskills-admin pedagogical-activities example --type choice_question --instance global --language fr --output json
416
+ gskills-admin pedagogical-activities create --data-file ./activity.json --dry-run --output json
417
+ gskills-admin pedagogical-activities update <activityId> --data-file ./activity.patch.json --dry-run --output json
418
+ gskills-admin pedagogical-activities translate <activityId> --from fr --to en,es --mode full --dry-run --output json
371
419
  ```
372
420
 
373
- Always dry-run first. Dry-run lists planned rows and target languages without calling AI or writing data. Real runs require `--yes`.
421
+ `schema` is the source for every live activity kind, starter template, translatable content path and page block shape. `create` and `update` use the same editor payload contract and publish validation as the super-admin editor. `translate --mode full` preserves technical IDs, URLs, answer keys, coordinates, and activity logic while translating only declared human-readable strings.
374
422
 
375
- Never use `--to all`. The CLI rejects it because target languages must be explicit.
423
+ Placement:
376
424
 
377
- Warning for pages: `translate pages` rewrites each translated page from the source page. It is not a diff update. Recreating translated pages this way can lose activity-specific fields, quiz ids, embedded ids, or future custom block data if the translator does not preserve them. Prefer the app diff update flow for pages with activities or custom blocks.
425
+ - Page: insert the `pedagogicalActivity` block (shape from `schema`, rewards on the block) into the EditorJS document and save it with `page-authoring draft`, then publish when asked.
426
+ - Learning path: add an `ACTIVITY` item (`activityId`, `order`, group, `successRewards`) to the COMPLETE item list and send it with `admin run learning-paths.update`.
427
+ - `pedagogical-activities attach-page|add-to-page|attach-learning-path`, `pages activity ...` and `learning-paths activity ...` are retired.
378
428
 
379
- For pages with activities or custom blocks, prefer `--mode patch`. It uses the source page history to update changed translatable text while preserving target non-text block data such as activity ids, quiz ids, embedded ids, files, and future custom fields. It updates existing translations only and fails when no previous source history exists.
429
+ Rewards belong to the page block or learning-path item where the activity is placed. Reward items need stable unique IDs and use `ONCE_PER_PLACEMENT`.
380
430
 
381
- For quizzes, the CLI mirrors the quiz thematic through `categoryId` across translations.
431
+ Placement does not publish the activity. A learner-ready activity must be `PUBLISHED`, enabled, not archived, and translated for the target page or parcours language. After every write, use `pedagogical-activities get` to verify translations, placements, whole-activity skill links, and per-step skill links before checking the page or parcours.
382
432
 
383
- Everything translated by the CLI and stored in the DB works as a family. A page is still one page, even when the DB stores one row per language. Do not tell a non-technical user that one page became 40 pages, unless they explicitly ask for DB-level detail.
433
+ For `off_platform_challenge`, agents may put `skillIds` on `translations[].content.steps[]`. The CLI save route strips those ids from stored content and writes proper `SkillContentLink` rows for each interaction.
384
434
 
385
- When a translated thing has relations, translate or relink those relations too. A translated page, quiz, badge, resource, knowledge item, menu entry, or learning path should not quietly point back to the French-only relation when a same-language relation exists.
435
+ ## AI Translation
386
436
 
387
- For learning paths, a complete translation includes the parcours itself, its groups, its items, same-language page, quiz, resource, and knowledge references when available, the awarded badge family, and each translated parcours linked to the badge in the same language. This exact trap has happened: the parcours translated correctly but every translated parcours still pointed to the French badge.
437
+ Pages: `translate pages` writes canonical drafts. It adds each missing locale as `OPTIONAL`, saves the translated documents into the private draft, and never publishes. Pass an explicit `--instance` and canonical page id, dry-run, then apply.
388
438
 
389
- When explaining CLI work to the user, use `gskills-vocabulary`. Speak like a GSkills admin or end user, not like a database. Use words like page, quiz, parcours, badge, menu, resource, and knowledge base. Do not lead with ids, row counts, parent ids, or schema terms unless the user asks for them.
439
+ ```bash
440
+ gskills-admin translate pages <pageId> --instance global --from fr --to en,es --dry-run --output json
441
+ gskills-admin translate pages <pageId> --instance global --from fr --to en,es --yes --output json
442
+ gskills-admin translate pages --all --instance global --from fr --to en --take 100 --dry-run --output json
443
+ gskills-admin pedagogical-activities translate <activityId> --from fr --to en,es --mode full --dry-run --output json
444
+ ```
390
445
 
391
- Users could do most of these content tasks in the GSkills UI. The reason they ask Codex is speed. Keep the answer simple: what changed, what stays hidden or visible, and what was verified.
446
+ - `--where` is unsupported for canonical `--all`. On a customer instance, `--all` selects owned pages only, not inherited shared pages.
447
+ - Retired locales need explicit reactivation (`admin run pages.locale.reactivate`). `pages.translate-draft-locale` re-translates one draft locale from the source.
448
+ - Translation does not replace human validation: check the draft with `page-authoring editor` / `readiness`, then `page-authoring publish` only when publication was asked.
449
+ - `translate quizzes|menus|menu-sections` are retired (`LEGACY_CONTENT_WRITE_RETIRED`). Other families get a locale through their `admin` operations: `quizzes.create` with `parentId`, `learning-paths.create-translation`, `knowledge.create-translation` / `knowledge.localize-video`, `badges.upsert-translation`, `categories.upsert-translation`, `resources.create` (same title and type in the new language), `chromebook.create` with `parentId`. Do not use the other `translate <kind>` commands to write Legacy families.
450
+ - Use `pedagogical-activities translate` for activity content because it preserves per-type JSON and activity ids. Avoid translating an activity through a full page rewrite.
451
+
452
+ Always dry-run first. Dry-run lists planned locales without calling AI or writing data. Real runs require `--yes`. `--to all` is allowed; inspect the target language list before running with `--yes`.
453
+
454
+ A page is one page with several locales. Do not tell a non-technical user that one page became 40 pages, unless they explicitly ask for DB-level detail.
392
455
 
393
- After translating content, use CLI output to prove there are no missing languages, no unexpected active content, no missing related content, and no language mismatch between connected things.
456
+ When translated content has relations, the translated locale should point to same-language relations when they exist (quiz, resource, knowledge, badge). Check embedded ids in each locale document.
394
457
 
395
- For internal knowledge videos, use `knowledge-video`. It queues the same native video localization workflow as the editor, so it creates a localization job instead of copying the original media.
458
+ When explaining CLI work to the user, use `gskills-vocabulary`. Speak like a GSkills admin or end user, not like a database. Use words like page, quiz, parcours, badge, menu, resource, and knowledge base. Do not lead with ids, row counts, parent ids, or schema terms unless the user asks for them.
459
+
460
+ Users could do most of these content tasks in the GSkills UI. The reason they ask Codex is speed. Keep the answer simple: what changed, what stays hidden or visible, and what was verified.
396
461
 
397
- After visible content translation, read the cache hint in the response and invalidate the narrow scope before checking the deploy UI.
462
+ After translating a page, run a language-leak audit from CLI-read content: read `page-authoring editor <pageId> --instance <id> --include-content --output json`, then inspect each locale's title, description and EditorJS text fields for French or English prose left inside other languages. Use judgment for false positives: product names, app names, URLs, brand terms, code-like strings, file names, storage URLs, image captions that are product labels, and short headings that are mostly proper nouns. If a product-only heading trips validation, rewrite the source into a translatable phrase before rerunning translation. Do not use direct DB reads for this audit.
398
463
 
399
464
  ## Imported Sheets
400
465
 
@@ -413,151 +478,30 @@ gskills-admin imported-sheets replace-grid <sheetId> --instance <instanceId> --l
413
478
  gskills-admin imported-sheets vectorize <sheetId> --instance <instanceId> --locales fr,en --dry-run --output json
414
479
  gskills-admin imported-sheets repair-french <sheetId> --instance <instanceId> --locales es,it --revectorize --dry-run --output json
415
480
  gskills-admin imported-sheets copy-to <sheetId> --instance global --target <instanceId> --display-name "Use cases" --dry-run --output json
416
- gskills-admin imported-sheets attach-page <sheetId> --instance <instanceId> --page <pageId> --locale fr --dry-run --output json
417
481
  gskills-admin imported-sheets set-source <sheetId> --instance <instanceId> --locale en --source <sheet-url> --tab EN --resync --dry-run --output json
418
482
  ```
419
483
 
420
484
  Create supports either flags or `--data-file`. Use `--data-file` for `SHEET_PER_LANGUAGE` because locale sources are easier to audit as JSON.
421
485
 
422
- For the Gemini use-case list plugin flow, copy the global sheet to the client instance with `--display-name "Use cases"`, attach it to a page if the customer needs a page embed, then use `set-source --resync` when a locale tab has to be replaced.
486
+ For the Gemini use-case list plugin flow, copy the global sheet to the client instance with `--display-name "Use cases"`, then use `set-source --resync` when a locale tab has to be replaced. If the customer needs a page embed, add an `importedSheet` block (shape from `page-authoring content-schema`) to the page document with `page-authoring draft`. Do not use `imported-sheets attach-page`: it still edits Legacy `Pages.content`.
423
487
 
424
488
  Dry-run first. Imported sheet writes can create rows, variants, cells, sync runs, translations, embeddings, page blocks, deploy cache bumps, or permanent deletes depending on the command.
425
489
 
426
- ## Sync
490
+ ## Sync (retired)
427
491
 
428
- Global is the source by default.
492
+ Sync is gone for content. Shared canonical content is stored once and inherited by every instance (ADR-003). Publishing shared content on `global` makes it available everywhere it is not hidden; there is nothing to push. `sync run` and `sync repair-source-links` are refused with `LEGACY_CONTENT_WRITE_RETIRED`, and `internal-knowledge sync-media` is retired too.
429
493
 
430
- ```bash
431
- gskills-admin sync run --target <instanceId> --only pages,quizzes,learningPaths --dry-run --output json
432
- gskills-admin sync run --target <instanceId> --only pages,quizzes,learningPaths --yes --output json
433
- ```
434
-
435
- Use selectors for narrow syncs:
436
-
437
- ```bash
438
- gskills-admin sync run --target <instanceId> --pages <pageId,pageId> --languages fr,en --dry-run --output json
439
- ```
440
-
441
- Language-limited menu sync writes are blocked from the CLI. Run the diff first, sync the language-limited content without `menus`, or sync menus without `--languages` after the backend non-destructive sync patch is deployed.
442
-
443
- Use `sync diff` before a real run when the user wants to inspect what would change. It uses the same shared diff-preview system as the super-admin sync UI.
444
-
445
- ```bash
446
- gskills-admin sync presets --output json
447
- gskills-admin sync logs --target <instanceId> --take 10 --output json
448
- gskills-admin sync diff --target <instanceId> --only pages,menus --pages <pageId,pageId> --languages fr,en --output json
449
- gskills-admin sync diff --target <instanceId> --preset client-content --output json
450
- gskills-admin sync run --targets <instanceId,instanceId> --only pages,quizzes --dry-run --output json
451
- ```
452
-
453
- Common presets:
454
-
455
- - `client-content`: categories, pages, menus, quizzes, learning paths, resources, badges. This matches the most common Marina-correlated client sync shape.
456
- - `full-content`: broad global content push including languages, knowledge, and workflows.
457
- - `pages-only`: page-only correction or syncing-pages style checks.
458
- - `pages-learning-paths`: refinement pass after broad syncs.
459
- - `knowledge-resources-paths`: narrow asset and learning path rerun.
460
-
461
- ## Knowledge Media Sync
462
-
463
- Use this when existing internal knowledge copies already exist on client instances and only the referenced media changed on global.
464
-
465
- Default behavior changes only `url` on existing target copies matched by `sourceKnowledgeId`. It does not create knowledge rows and does not change activities, metadata, tags, categories, active state, parent links, or AI flags.
466
-
467
- ```bash
468
- gskills-admin internal-knowledge sync-media --source global --since today --languages fr --all-targets --dry-run --output json
469
- gskills-admin internal-knowledge sync-media --source global --since today --languages fr --all-targets --yes --output json
470
- ```
471
-
472
- Use `--target <instanceId>` or `--targets <id,id>` instead of `--all-targets` for a smaller run.
473
-
474
- Use `--fields url,updatedAt` only when the visible update date must mirror the source. The safer default is `url` only.
475
-
476
- The command invalidates `pages-knowledge` for touched instances unless `--no-cache` is passed.
477
-
478
- ## Marina Sync Playbook
479
-
480
- This section is based on prod admin logs and sync runs checked on 2026-05-13 for the period 2026-03-13 to 2026-05-13.
481
-
482
- Important evidence note: old `SyncRun` rows do not store the user who clicked run. Marina attribution here comes from her admin visit logs near sync runs on the same target instance. Treat close matches as strong operational evidence, but not a hard audit identity. New CLI `sync run` operations are logged with `slug = "cli.sync.run"`, `entityType = "sync"`, `entityId = runId`, and metadata containing `actorType = "cli"`, `agent`, source, target, options, and summary totals.
483
-
484
- Marina's current pattern:
485
-
486
- - She mostly uses `/super-admin/<instance>/synchro-content`.
487
- - In the last two months, Marina had 33 sync-related visits, 31 on `synchro-content` and 2 on `syncing-pages`.
488
- - She often checks the global sync page first, then one or more target instances.
489
- - Frequent targets were Air Liquide, V&B, HASAP, Actual, Seine Yonne, plus one-off onboarding or update pushes for Divonne, LGCF, FM Logistic, Terega, AS de Pic, Nickel Banque, 360 Courtage, Euromaster.
490
- - The common broad client run shape is categories, pages, menus, quizzes, learning paths, resources, and badges.
491
- - A broader full-content shape appears often too, adding internal knowledge.
492
- - Refinement runs after a broad pass are usually pages-only or pages plus learning paths.
493
- - Air Liquide is the heavy target. Expect thousands of items and many `SKIPPED_CUSTOMIZED` entries, so always inspect diff and summary before applying.
494
-
495
- Direct examples from recent logs:
496
-
497
- - 2026-04-10, Air Liquide: Marina visited the Air Liquide sync page and a run started 5 minutes earlier. Shape was full-content with 5,545 sync items: 3,087 pages, 701 quizzes, 477 categories, 836 badges, 248 learning paths, 67 knowledge items, 71 resources, menus. Most were skipped identical, with 585 skipped customized and 27 updates.
498
- - 2026-04-09, Air Liquide: repeated full-content attempts around the same sync session, including failed broad runs, then a completed full-content run, then page-only runs with around 2,918 page items. For CLI agents, this means do not retry blindly. Use `sync logs`, inspect failures, run `sync diff`, then narrow the next run if the broad run already mostly applied.
499
- - 2026-04-27, HASAP: two very close `synchro-content` visits matched narrow client-content style runs. One had 208 items with categories, pages, quizzes, menu, resources, badges, learning paths. Another had 200 items with very few pages and knowledge. This is a good model for targeted client maintenance after content changes.
500
- - 2026-04-14, Euromaster: Marina used `syncing-pages`; nearby runs were page-only and pages plus learning paths. Use `pages-learning-paths` for this pattern, not a full sync.
501
- - 2026-04-14, LGCF: a broad run was followed by page-only and pages plus learning paths passes. This is common after a content batch needs correction.
502
- - 2026-04-15, Commune de Divonne-les-Bains: a new target push created most of the content, 647 created out of 723 items. For new client onboarding, expect high created counts and run the broad `client-content` diff first.
503
- - 2026-04-03, AS de Pic and 2026-03-27, 360 Courtage: new-client style pushes created nearly everything. These are not casual maintenance runs. Use diff, then `client-content`, then verify menus and deploy cache.
504
-
505
- When the user says content was created this week and asks to push it to a client:
506
-
507
- 1. Resolve the target instance id.
508
-
509
- ```bash
510
- gskills-admin instances list --where '{"name":{"contains":"Air Liquide","mode":"insensitive"}}' --fields id,name,URL --output json
511
- ```
512
-
513
- 2. Look at recent sync history before touching anything.
514
-
515
- ```bash
516
- gskills-admin sync logs --target cmfwilgzb000404kzmfrkuifm --take 10 --output json
517
- ```
518
-
519
- 3. Start with the Marina-style diff.
520
-
521
- ```bash
522
- gskills-admin sync diff --target cmfwilgzb000404kzmfrkuifm --preset client-content --output json
523
- ```
524
-
525
- 4. If the new content includes internal knowledge or workflows, use full content.
526
-
527
- ```bash
528
- gskills-admin sync diff --target cmfwilgzb000404kzmfrkuifm --preset full-content --output json
529
- ```
530
-
531
- 5. If the diff is only pages or only a page family, narrow it.
532
-
533
- ```bash
534
- gskills-admin sync diff --target cmfwilgzb000404kzmfrkuifm --preset pages-only --pages <pageId,pageId> --output json
535
- gskills-admin sync run --target cmfwilgzb000404kzmfrkuifm --preset pages-only --pages <pageId,pageId> --yes --output json
536
- ```
537
-
538
- 6. If the diff looks like a normal broad content push, run the same preset you diffed.
539
-
540
- ```bash
541
- gskills-admin sync run --target cmfwilgzb000404kzmfrkuifm --preset client-content --yes --output json
542
- ```
543
-
544
- 7. After the run, check logs and reset only the needed deploy cache scope.
545
-
546
- ```bash
547
- gskills-admin sync logs --target cmfwilgzb000404kzmfrkuifm --take 3 --output json
548
- gskills-admin cache invalidate --instance cmfwilgzb000404kzmfrkuifm --scope pages --dry-run --output json
549
- gskills-admin cache invalidate --instance cmfwilgzb000404kzmfrkuifm --scope pages --yes --output json
550
- ```
494
+ `sync logs`, `sync diff` and `sync presets` stay readable for history only.
551
495
 
552
- For Air Liquide specifically, expect large diffs and customized skips. Do not treat `SKIPPED_CUSTOMIZED` as an error. It usually means the client instance deliberately diverged after a previous sync.
496
+ ## Making content visible to a customer
553
497
 
554
- Preset choice from Marina patterns:
498
+ 1. Resolve the customer instance (`instances list --where ...`). Never guess an id.
499
+ 2. Publish the shared content on `global` (`page-authoring publish`, `quizzes.publish`, `workflows.publish` then activation), only when asked.
500
+ 3. Check the customer's effective catalogue: `admin run catalogue.list --data '{"instanceId":"<id>"}' --yes` (see `admin describe catalogue.list` for filters). Hidden inherited content is a deliberate customer choice; restore it with `catalogue.restore` only when the user asks.
501
+ 4. Check the page locale exists for the customer's languages (`page-authoring editor`), and that `alphaProgramIds` / `frenchOnly` match the intent. Audience restrictions: `pages.audience.read`. Menu placement: `menus.read` (customer overlay) or `menus.global.*` (shared menu).
502
+ 5. Verify the visible result on the customer deploy. Invalidate cache only if a verified change is still stale.
555
503
 
556
- - Use `client-content` for normal client content pushes.
557
- - Use `full-content` when the request mentions internal knowledge, workflows, language setup, or a broad global refresh.
558
- - Use `pages-only` when she would have used `syncing-pages`, or when only page content changed.
559
- - Use `pages-learning-paths` when pages are part of learning paths, especially after a broad sync.
560
- - Use `knowledge-resources-paths` when assets, internal knowledge, webinars, or learning path references changed without normal page content.
504
+ Customer-owned content is authored with the customer instance id and is not shared with other instances.
561
505
 
562
506
  ## Cache
563
507
 
@@ -570,7 +514,7 @@ gskills-admin cache invalidate --instance <instanceId> --scope menu-bundle --yes
570
514
  gskills-admin cache invalidate --instance <instanceId> --scope all --yes --output json
571
515
  ```
572
516
 
573
- CRUD resources that expose `cache.scopes` in `gskills-admin <resource> help --output json` should be treated as cached. After a raw write on one of those resources, dry-run the cache invalidation plan, apply it with `--yes`, then re-check the visible product surface.
517
+ CRUD resources that expose `cache.scopes` in `gskills-admin <resource> help --output json` should be treated as cached. After a raw write on one of those (non-content) resources, or when a verified canonical change is still stale on deploy, dry-run the cache invalidation plan, apply it with `--yes`, then re-check the visible product surface.
574
518
 
575
519
  Typical mapping:
576
520
 
@@ -812,10 +756,12 @@ Prefer the narrowest scope:
812
756
 
813
757
  ## Safety
814
758
 
815
- - Prefer `list` and `get` before writes
816
- - Use `--dry-run` before create, update, delete, and sync
759
+ - Prefer `list`, `get` and `page-authoring editor` before writes
760
+ - Use `--dry-run` before every create, draft, publish, delete and `admin run` write
761
+ - Never write content through Legacy commands; use `page-authoring` or `admin run`, follow `nextAction` on `LEGACY_CONTENT_WRITE_RETIRED`, never bypass it with direct DB, Prisma or SQL
762
+ - Pass `--lock-version` from `editor` on page drafts and publishes
763
+ - Publish only when the user asked for publication
817
764
  - Use `--force --confirm-delete <resource>:<id>` only for archive/delete flows the user explicitly requested
818
- - Use `sync diff` before `sync run --yes`
819
765
  - Use cache `--dry-run` before cache `--yes`
820
766
  - Re-read changed rows after writes
821
767
  - Keep output structured so another agent can parse it