@numericoach/gskills-admin-cli 0.1.31 → 0.1.32
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +37 -4
- package/dist/gskills-admin.js +8737 -1235
- package/package.json +25 -24
- package/skills/gskills-admin-cli/SKILL.md +218 -272
- package/skills/gskills-admin-cli/references/content-platform-tables.md +1647 -0
- package/skills/gskills-admin-cli/references/content-platform.md +146 -0
- package/skills/gskills-content-sync-cache-ops/SKILL.md +36 -89
- package/skills/gskills-customer-playbooks/SKILL.md +18 -19
- package/skills/gskills-ops-db-audit/SKILL.md +5 -5
- package/skills/gskills-page-content-blocks/SKILL.md +40 -47
- package/skills/gskills-source-id-repair/SKILL.md +11 -30
|
@@ -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,
|
|
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
|
|
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 --
|
|
52
|
-
gskills-admin
|
|
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
|
|
59
|
-
gskills-admin
|
|
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.
|
|
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
|
-
|
|
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
|
-
|
|
94
|
+
## Page authoring
|
|
76
95
|
|
|
77
|
-
|
|
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
|
|
81
|
-
gskills-admin
|
|
82
|
-
gskills-admin
|
|
83
|
-
gskills-admin
|
|
84
|
-
gskills-admin
|
|
85
|
-
gskills-admin
|
|
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
|
-
|
|
110
|
+
Semantics:
|
|
89
111
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
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
|
-
|
|
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
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
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
|
-
|
|
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
|
-
`
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
144
|
-
|
|
145
|
-
|
|
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
|
-
`
|
|
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
|
-
|
|
186
|
+
Workflow for every change:
|
|
154
187
|
|
|
155
|
-
|
|
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
|
|
159
|
-
gskills-admin
|
|
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
|
-
|
|
203
|
+
Rules:
|
|
163
204
|
|
|
164
|
-
|
|
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
|
-
|
|
|
203
|
-
|
|
|
204
|
-
|
|
|
205
|
-
|
|
|
206
|
-
|
|
|
207
|
-
|
|
|
208
|
-
|
|
|
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
|
-
|
|
328
|
+
Canonical ownership replaces per-instance copies:
|
|
261
329
|
|
|
262
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
293
|
-
gskills-admin workflows
|
|
294
|
-
gskills-admin workflows
|
|
295
|
-
gskills-admin workflows
|
|
296
|
-
gskills-admin workflows
|
|
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
|
|
300
|
-
|
|
301
|
-
`
|
|
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
|
-
|
|
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
|
-
-
|
|
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 '{"
|
|
337
|
-
gskills-admin
|
|
338
|
-
gskills-admin
|
|
339
|
-
gskills-admin
|
|
340
|
-
gskills-admin
|
|
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,
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
|
|
352
|
-
-
|
|
353
|
-
-
|
|
354
|
-
-
|
|
355
|
-
-
|
|
356
|
-
-
|
|
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
|
-
|
|
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
|
-
|
|
423
|
+
Placement:
|
|
376
424
|
|
|
377
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
435
|
+
## AI Translation
|
|
386
436
|
|
|
387
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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"`,
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
496
|
+
## Making content visible to a customer
|
|
553
497
|
|
|
554
|
-
|
|
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
|
-
-
|
|
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 `
|
|
816
|
-
- Use `--dry-run` before create,
|
|
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
|