@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.
@@ -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,31 +325,44 @@ 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`
336
+ Always pass the instance explicitly. Never guess a client instance from a name if the CLI can list it:
276
337
 
277
- Still pass `--instance <instanceId>` when the user explicitly targets a client instance.
338
+ ```bash
339
+ gskills-admin instances list --where '{"name":{"contains":"Air Liquide","mode":"insensitive"}}' --output json
340
+ ```
341
+
342
+ ## Workflow Authoring
278
343
 
279
- Never guess a client instance from a name if the CLI can list it:
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.
280
345
 
281
346
  ```bash
282
- gskills-admin instances list --where '{"name":{"contains":"Air Liquide","mode":"insensitive"}}' --output json
347
+ gskills-admin workflows schema --trigger LEARNING_PATH_NOT_STARTED --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
283
355
  ```
284
356
 
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.
363
+
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.
365
+
285
366
  ## Auth Model
286
367
 
287
368
  - Login happens in the browser on `https://g-skills.fr`
@@ -294,7 +375,7 @@ If `whoami` fails, stop and login again. Do not work around auth with copied bro
294
375
 
295
376
  ## Content Authoring
296
377
 
297
- 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`.
298
379
 
299
380
  Good GSkills content usually has:
300
381
 
@@ -304,77 +385,81 @@ Good GSkills content usually has:
304
385
  - accordions for step-by-step instructions
305
386
  - sections for bigger modules
306
387
  - images only when they teach something
307
- - quizzes when the page family uses quizzes
308
- - a category connection
309
- - 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)
310
391
 
311
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.
312
393
 
313
394
  Typical create flow:
314
395
 
315
396
  ```bash
316
- gskills-admin pages list --where '{"language":"fr","slug":{"contains":"gmail"}}' --fields id,name,slug,language,instanceId,contentType --output json
317
- gskills-admin topics list --where '{"language":"fr"}' --fields id,name,slug,instanceId --output json
318
- gskills-admin menus list --where '{"instanceId":"global"}' --fields id,name,parentId,pageId,url,instanceId --output json
319
- gskills-admin pages create --data-file ./page.json --dry-run --output json
320
- 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
321
405
  ```
322
406
 
323
- 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.
324
408
 
325
- ## AI Translation
326
-
327
- Use `translate` when content already has AI translation in its editor and the same operation is needed from the CLI.
409
+ ## Pedagogical Activities
328
410
 
329
- 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).
330
412
 
331
- - `pages`
332
- - `quizzes`
333
- - `topics`
334
- - `badges`
335
- - `menus`
336
- - `menu-sections`
337
- - `internal-knowledge`
338
- - `knowledge-video`
339
- - `learning-paths`
340
- - `chromebook-exercises`
341
-
342
- Selection can be one source row, several source rows, or all matching rows:
343
-
344
- ```bash
345
- gskills-admin translate pages <pageId> --to en,es --dry-run --output json
346
- gskills-admin translate pages <pageId> --from fr --to en,es --mode patch --dry-run --output json
347
- gskills-admin translate pages --ids <pageId,pageId> --from fr --to en --dry-run --output json
348
- gskills-admin translate pages --all --instance global --from fr --to en --take 100 --dry-run --output json
349
- gskills-admin translate quizzes <quizId> --to en --yes --output json
350
- 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
351
419
  ```
352
420
 
353
- 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.
354
422
 
355
- Never use `--to all`. The CLI rejects it because target languages must be explicit.
423
+ Placement:
356
424
 
357
- 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.
358
428
 
359
- 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`.
360
430
 
361
- 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.
362
432
 
363
- 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.
364
434
 
365
- 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
366
436
 
367
- 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.
368
438
 
369
- 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
+ ```
370
445
 
371
- 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.
372
451
 
373
- 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.
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`.
374
453
 
375
- 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.
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.
376
455
 
377
- After visible content translation, read the cache hint in the response and invalidate the narrow scope before checking the deploy UI.
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.
457
+
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.
461
+
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.
378
463
 
379
464
  ## Imported Sheets
380
465
 
@@ -393,151 +478,30 @@ gskills-admin imported-sheets replace-grid <sheetId> --instance <instanceId> --l
393
478
  gskills-admin imported-sheets vectorize <sheetId> --instance <instanceId> --locales fr,en --dry-run --output json
394
479
  gskills-admin imported-sheets repair-french <sheetId> --instance <instanceId> --locales es,it --revectorize --dry-run --output json
395
480
  gskills-admin imported-sheets copy-to <sheetId> --instance global --target <instanceId> --display-name "Use cases" --dry-run --output json
396
- gskills-admin imported-sheets attach-page <sheetId> --instance <instanceId> --page <pageId> --locale fr --dry-run --output json
397
481
  gskills-admin imported-sheets set-source <sheetId> --instance <instanceId> --locale en --source <sheet-url> --tab EN --resync --dry-run --output json
398
482
  ```
399
483
 
400
484
  Create supports either flags or `--data-file`. Use `--data-file` for `SHEET_PER_LANGUAGE` because locale sources are easier to audit as JSON.
401
485
 
402
- 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`.
403
487
 
404
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.
405
489
 
406
- ## Sync
407
-
408
- Global is the source by default.
409
-
410
- ```bash
411
- gskills-admin sync run --target <instanceId> --only pages,quizzes,learningPaths --dry-run --output json
412
- gskills-admin sync run --target <instanceId> --only pages,quizzes,learningPaths --yes --output json
413
- ```
490
+ ## Sync (retired)
414
491
 
415
- Use selectors for narrow syncs:
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.
416
493
 
417
- ```bash
418
- gskills-admin sync run --target <instanceId> --pages <pageId,pageId> --languages fr,en --dry-run --output json
419
- ```
420
-
421
- 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.
422
-
423
- 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.
424
-
425
- ```bash
426
- gskills-admin sync presets --output json
427
- gskills-admin sync logs --target <instanceId> --take 10 --output json
428
- gskills-admin sync diff --target <instanceId> --only pages,menus --pages <pageId,pageId> --languages fr,en --output json
429
- gskills-admin sync diff --target <instanceId> --preset client-content --output json
430
- gskills-admin sync run --targets <instanceId,instanceId> --only pages,quizzes --dry-run --output json
431
- ```
432
-
433
- Common presets:
434
-
435
- - `client-content`: categories, pages, menus, quizzes, learning paths, resources, badges. This matches the most common Marina-correlated client sync shape.
436
- - `full-content`: broad global content push including languages, knowledge, and workflows.
437
- - `pages-only`: page-only correction or syncing-pages style checks.
438
- - `pages-learning-paths`: refinement pass after broad syncs.
439
- - `knowledge-resources-paths`: narrow asset and learning path rerun.
440
-
441
- ## Knowledge Media Sync
442
-
443
- Use this when existing internal knowledge copies already exist on client instances and only the referenced media changed on global.
444
-
445
- 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.
446
-
447
- ```bash
448
- gskills-admin internal-knowledge sync-media --source global --since today --languages fr --all-targets --dry-run --output json
449
- gskills-admin internal-knowledge sync-media --source global --since today --languages fr --all-targets --yes --output json
450
- ```
451
-
452
- Use `--target <instanceId>` or `--targets <id,id>` instead of `--all-targets` for a smaller run.
453
-
454
- Use `--fields url,updatedAt` only when the visible update date must mirror the source. The safer default is `url` only.
455
-
456
- The command invalidates `pages-knowledge` for touched instances unless `--no-cache` is passed.
457
-
458
- ## Marina Sync Playbook
459
-
460
- 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.
461
-
462
- 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.
463
-
464
- Marina's current pattern:
465
-
466
- - She mostly uses `/super-admin/<instance>/synchro-content`.
467
- - In the last two months, Marina had 33 sync-related visits, 31 on `synchro-content` and 2 on `syncing-pages`.
468
- - She often checks the global sync page first, then one or more target instances.
469
- - 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.
470
- - The common broad client run shape is categories, pages, menus, quizzes, learning paths, resources, and badges.
471
- - A broader full-content shape appears often too, adding internal knowledge.
472
- - Refinement runs after a broad pass are usually pages-only or pages plus learning paths.
473
- - Air Liquide is the heavy target. Expect thousands of items and many `SKIPPED_CUSTOMIZED` entries, so always inspect diff and summary before applying.
474
-
475
- Direct examples from recent logs:
476
-
477
- - 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.
478
- - 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.
479
- - 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.
480
- - 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.
481
- - 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.
482
- - 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.
483
- - 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.
484
-
485
- When the user says content was created this week and asks to push it to a client:
486
-
487
- 1. Resolve the target instance id.
488
-
489
- ```bash
490
- gskills-admin instances list --where '{"name":{"contains":"Air Liquide","mode":"insensitive"}}' --fields id,name,URL --output json
491
- ```
492
-
493
- 2. Look at recent sync history before touching anything.
494
-
495
- ```bash
496
- gskills-admin sync logs --target cmfwilgzb000404kzmfrkuifm --take 10 --output json
497
- ```
498
-
499
- 3. Start with the Marina-style diff.
500
-
501
- ```bash
502
- gskills-admin sync diff --target cmfwilgzb000404kzmfrkuifm --preset client-content --output json
503
- ```
504
-
505
- 4. If the new content includes internal knowledge or workflows, use full content.
506
-
507
- ```bash
508
- gskills-admin sync diff --target cmfwilgzb000404kzmfrkuifm --preset full-content --output json
509
- ```
510
-
511
- 5. If the diff is only pages or only a page family, narrow it.
512
-
513
- ```bash
514
- gskills-admin sync diff --target cmfwilgzb000404kzmfrkuifm --preset pages-only --pages <pageId,pageId> --output json
515
- gskills-admin sync run --target cmfwilgzb000404kzmfrkuifm --preset pages-only --pages <pageId,pageId> --yes --output json
516
- ```
517
-
518
- 6. If the diff looks like a normal broad content push, run the same preset you diffed.
519
-
520
- ```bash
521
- gskills-admin sync run --target cmfwilgzb000404kzmfrkuifm --preset client-content --yes --output json
522
- ```
523
-
524
- 7. After the run, check logs and reset only the needed deploy cache scope.
525
-
526
- ```bash
527
- gskills-admin sync logs --target cmfwilgzb000404kzmfrkuifm --take 3 --output json
528
- gskills-admin cache invalidate --instance cmfwilgzb000404kzmfrkuifm --scope pages --dry-run --output json
529
- gskills-admin cache invalidate --instance cmfwilgzb000404kzmfrkuifm --scope pages --yes --output json
530
- ```
494
+ `sync logs`, `sync diff` and `sync presets` stay readable for history only.
531
495
 
532
- 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
533
497
 
534
- 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.
535
503
 
536
- - Use `client-content` for normal client content pushes.
537
- - Use `full-content` when the request mentions internal knowledge, workflows, language setup, or a broad global refresh.
538
- - Use `pages-only` when she would have used `syncing-pages`, or when only page content changed.
539
- - Use `pages-learning-paths` when pages are part of learning paths, especially after a broad sync.
540
- - 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.
541
505
 
542
506
  ## Cache
543
507
 
@@ -550,7 +514,7 @@ gskills-admin cache invalidate --instance <instanceId> --scope menu-bundle --yes
550
514
  gskills-admin cache invalidate --instance <instanceId> --scope all --yes --output json
551
515
  ```
552
516
 
553
- 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.
554
518
 
555
519
  Typical mapping:
556
520
 
@@ -792,10 +756,12 @@ Prefer the narrowest scope:
792
756
 
793
757
  ## Safety
794
758
 
795
- - Prefer `list` and `get` before writes
796
- - 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
797
764
  - Use `--force --confirm-delete <resource>:<id>` only for archive/delete flows the user explicitly requested
798
- - Use `sync diff` before `sync run --yes`
799
765
  - Use cache `--dry-run` before cache `--yes`
800
766
  - Re-read changed rows after writes
801
767
  - Keep output structured so another agent can parse it