@se-studio/skills 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @se-studio/skills
 
+## 1.0.5
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.4
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
 ## 1.0.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/skills",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "SE Studio agent skills for marketing site development with Contentful CMS",
   "repository": {
     "type": "git",

package/skills/contentful-cms-core/SKILL.md

@@ -75,6 +75,16 @@ Page: /pricing  [4xKj2abc | published]  ·  om1
 
 Use `snapshot -c` for compact output (types only, no labels).
 
+**Ref cheat sheet:**
+| Ref | Resolves to |
+|-----|-------------|
+| `@root` | Root entry of the current session (works in any session type) |
+| `@p0` | Root entry — alias for `@root` in **page** and **article** sessions only |
+| `@c0` | Same as `@root` (first entry in depth-first traversal order) |
+| `@c1`, `@c2`, … | Child entries in depth-first traversal order |
+
+In **navigation sessions**, use `@root` or `@c0` for the nav root — `@p0` is not valid.
+
 ### Step 3: Read entry fields
 
 ```bash
@@ -108,10 +118,14 @@ Each token is `@ref:fieldName=value`. All values are scalar (string, boolean, nu
 cms-edit set @c0 template 3I0HxGKbUd173wIpFCsbVr --link
 ```
 
-**Content arrays** (topContent, content, bottomContent, contents — replace or append entry links):
+**Entry link arrays** (`--links` works on any field that is an array of entry links — not just the standard page content fields):
 ```bash
+# Standard page content arrays
 cms-edit set @p0 content @c1,@c2,@c3 --links
 cms-edit set @p0 bottomContent @c4 --links --append
+
+# Navigation items array (use @root or @c0 in a nav session)
+cms-edit set @root items <id1>,<id2>,<id3> --links
 ```
 
 **Rich text fields** (body, additionalCopy):
@@ -344,9 +358,16 @@ cms-edit asset set @c0 visual 5xKj2abcDef
 # Open a navigation entry
 cms-edit nav open main-navigation
 
-# Add an item
+# Add a new item
 cms-edit nav add --label "Pricing" --slug /pricing
 cms-edit nav add --label "Docs" --href https://docs.example.com --after @c1
+
+# Link an existing NavigationItem (share items across navigations)
+cms-edit nav add --existing-id <navigationItem-entry-id>
+
+# Clone a navigation (duplicates all items)
+cms-edit nav clone <source-nav-id>
+cms-edit nav clone <source-nav-id> --label "LP Nav" --slug lp-nav
 ```
 
 ## Create New Entries
@@ -436,7 +457,7 @@ cms-edit save
 ### Update an existing article
 ```bash
 cms-edit open /blog/old-title --id  # or by slug
-cms-edit set @p0 title "New Article Title"
+cms-edit set @p0 title "New Article Title"   # @p0 works in article sessions too
 cms-edit set @p0 slug new-article-slug
 cms-edit set @p0 description "Updated description"
 cms-edit save

package/skills/contentful-cms-navigation/SKILL.md

@@ -11,12 +11,73 @@ Use this skill when creating or editing **navigation** entries and their items i
 
 1. **Create** a navigation: `cms-edit create navigation --label 'Main menu'`
 2. **Open** the nav: `cms-edit nav open <slug-or-id>` (or after create, use the printed open command)
-3. **Add** items: `cms-edit nav add --label "Pricing" --slug /pricing` or `--label "Docs" --href https://docs.example.com`; use `--after @cN` to insert after a ref.
-4. **Set** nav item fields (use snapshot refs): `cms-edit set @c1 label "New label"`, `cms-edit set @c1 page <entry-id> --link`, `cms-edit set @c1 externalUrl "https://..."`.
-5. **Remove** an item: `cms-edit remove @cN`
-6. **Save**: `cms-edit save`
+3. **Add items** (new or existing):
+   ```bash
+   # Create a new nav item with a page link
+   cms-edit nav add --label "Pricing" --slug /pricing
 
-Navigation entries are often linked from templates as **menu** or **footer**; set those with `set ... menu <nav-id> --link` from a template session.
+   # Create a new nav item with an external URL
+   cms-edit nav add --label "Docs" --href https://docs.example.com --after @c1
+
+   # Link an EXISTING NavigationItem entry (e.g. to share items across navigations)
+   cms-edit nav add --existing-id <navigationItem-entry-id>
+   cms-edit nav add --existing-id <id> --after @c1
+   ```
+4. **Set** nav item fields (use snapshot refs): `cms-edit set @c1 title "New label"`, `cms-edit set @c1 internal <page-entry-id> --link`, `cms-edit set @c1 link "https://..."`.
+5. **Set the items array directly** (e.g. to replace all items at once):
+   ```bash
+   cms-edit set @root items <id1>,<id2>,<id3> --links
+   ```
+6. **Remove** an item: `cms-edit remove @cN`
+7. **Save**: `cms-edit save`
+
+## Cloning a navigation
+
+To duplicate a navigation and all its items (e.g. for a landing page variant):
+
+```bash
+cms-edit nav clone <source-nav-id>
+# Optional: provide a custom label/slug for the clone
+cms-edit nav clone <source-nav-id> --label "LP Navigation" --slug lp-nav
+```
+
+This creates new copies of every NavigationItem and links them into the new navigation. Prints the new navigation ID and an `open` command.
+
+## Session refs
+
+In a navigation session, the root navigation entry is **`@c0`** (or the universal alias **`@root`**). The `@p0` alias only works in page/article sessions.
+
+```bash
+cms-edit nav open main-navigation
+cms-edit snapshot          # root is @c0; items are @c1, @c2, …
+cms-edit read @root        # same as @c0
+```
+
+## Visual fields (media wrapper)
+
+Visual fields expect a **`media` Entry link**, not a direct Asset ID. `cms-edit asset set` now auto-creates the wrapper:
+
+```bash
+cms-edit asset set @c0 visual <asset-id>
+# → auto-creates a media entry wrapping the asset, then sets visual to that entry
+```
+
+If you need to create the media wrapper manually:
+```bash
+cms-edit create media <asset-id>   # prints the media entry ID
+cms-edit set @c0 visual <media-entry-id> --link
+```
+
+## Linking navigation from a template
+
+Navigation entries are often linked from templates as **menu** or **footer**:
+
+```bash
+cms-edit open <template-id> --id
+cms-edit set @root menu <nav-entry-id> --link
+cms-edit set @root footer <footer-nav-id> --link
+cms-edit save
+```
 
 ## Related skills
 

package/skills/performance-audit/SKILL.md

@@ -117,39 +117,44 @@ Large client-only packages here inflate server cold-start time. Check for missin
 | 20.19+ or 22+ | `lighthouse@13` |
 
 Chrome path:
-- Linux / WSL: `/usr/bin/google-chrome`
+- Linux / WSL: `google-chrome-stable` (binary is `/usr/bin/google-chrome-stable`)
 - macOS: Lighthouse finds it automatically
 
 ### Run against key page types
 
-Substitute `<SITE_URL>` with the production (or preview) domain.
+Use the script-based approach. It spawns one Chrome instance, audits all pages, then prints a delta table vs the previous run.
+
+**Setup — copy the script template:**
+
+```bash
+mkdir -p scripts
+cp node_modules/@se-studio/skills/skills/performance-audit/lighthouse.ts scripts/lighthouse.ts
+```
+
+Or copy from `apps/example-se2026/scripts/lighthouse.ts` in the se-core-product monorepo if you have it available.
+
+**Customise `PAGES` for the project** — edit the `PAGES` array near the top of the script. Choose representative pages: homepage, a list/index page, and a detail page. Use the sitemap to identify good candidates:
+
+```bash
+curl -s <SITE_URL>/sitemap.xml | grep -oP 'https://[^<]+'
+# or for this stack:
+curl -s <SITE_URL>/marketing/sitemap.xml | grep -oP 'https://[^<]+'
+curl -s <SITE_URL>/marketing/sitemap-unindexed.xml | grep -oP 'https://[^<]+'
+```
+
+**Install dependencies (if not present):**
+
+```bash
+pnpm add -D lighthouse tsx
+```
+
+**Run:**
 
 ```bash
-mkdir -p .lighthouse
-
-# Homepage
-npx lighthouse@12 <SITE_URL>/ \
-  --chrome-path /usr/bin/google-chrome \
-  --chrome-flags="--headless=new --no-sandbox --disable-gpu --disable-dev-shm-usage" \
-  --only-categories=performance,accessibility,best-practices,seo \
-  --output json --output-path .lighthouse/home.json --quiet
-
-# A list or index page
-npx lighthouse@12 <SITE_URL>/blog/ \
-  --chrome-path /usr/bin/google-chrome \
-  --chrome-flags="--headless=new --no-sandbox --disable-gpu --disable-dev-shm-usage" \
-  --only-categories=performance,accessibility,best-practices,seo \
-  --output json --output-path .lighthouse/list.json --quiet
-
-# A detail page (pick a URL from the sitemap)
-npx lighthouse@12 <DETAIL_URL> \
-  --chrome-path /usr/bin/google-chrome \
-  --chrome-flags="--headless=new --no-sandbox --disable-gpu --disable-dev-shm-usage" \
-  --only-categories=performance,accessibility,best-practices,seo \
-  --output json --output-path .lighthouse/detail.json --quiet
+npx tsx scripts/lighthouse.ts
 ```
 
-To find page URLs: `curl -s <SITE_URL>/sitemap.xml | grep -oP 'https://[^<]+'`
+The script writes JSON to `.lighthouse/<page>.json`, overwrites each run, and prints a delta table showing score changes vs the previous run.
 
 ### Extract scores from JSON
 
@@ -309,21 +314,20 @@ Verify audience browser share before applying — check analytics for any legacy
 
 ## Tracking baselines
 
-Save Lighthouse JSON to `.lighthouse/<page>.json`. After each round of fixes, save to `.lighthouse/<page>-v2.json`, `v3.json`, etc.
+The script shows score deltas automatically each run — no separate comparison script needed. The delta column (`▲`/`▼`/`·`) reflects the difference from the JSON that existed before the run started.
 
-Compare LCP across versions:
-```bash
-node -e "
-const v1 = JSON.parse(require('fs').readFileSync('.lighthouse/home.json','utf8'));
-const v2 = JSON.parse(require('fs').readFileSync('.lighthouse/home-v2.json','utf8'));
-const lcp = a => (a.audits['largest-contentful-paint'].numericValue/1000).toFixed(2)+'s';
-const perf = a => Math.round(a.categories.performance.score * 100);
-console.log('Home LCP: v1=' + lcp(v1) + ' → v2=' + lcp(v2));
-console.log('Home Perf: v1=' + perf(v1) + ' → v2=' + perf(v2));
-"
+Add `.lighthouse/` to `.gitignore` — committing it adds large JSON files that the script already overwrites each run:
+
+```
+# .gitignore
+.lighthouse/
 ```
 
-Commit `.lighthouse/` to git for team-visible historical baselines.
+To preserve a snapshot before a major deploy, copy it manually:
+
+```bash
+cp -r .lighthouse .lighthouse-pre-deploy
+```
 
 ---
 
@@ -331,7 +335,8 @@ Commit `.lighthouse/` to git for team-visible historical baselines.
 
 | Error | Cause | Fix |
 |---|---|---|
-| `Unable to connect to Chrome` | Lighthouse can't find Chrome binary | Add `--chrome-path /usr/bin/google-chrome` |
+| `tcp_socket_win.cc: bind() … Only one usage of each socket address` or Chrome fails to start in WSL | WSL PATH resolves the **Windows** Chrome binary, which spawns as a Windows process and can't bind the DevTools port — passing `--chrome-path` to a one-shot `npx lighthouse` call doesn't help | Use the script approach: spawn `google-chrome-stable` (Linux binary) directly with `--no-sandbox --remote-debugging-port=9222`, then connect Lighthouse via `--port=9222` (see the script template above) |
+| `Unable to connect to Chrome` (non-WSL) | Lighthouse can't find Chrome binary | Set `CHROME_BIN` in the script to the correct binary path |
 | Lighthouse fails on Node 20.18.x | Requires lighthouse@12 | Use `npm i -g lighthouse@12` |
 | `ANALYZE=true next build` fails | `next.config.ts` export not wrapped | Ensure `export default withBundleAnalyzer(nextConfig)` |
 | Speed Insights shows no data | Wrong layout, or not deployed to production | Must be in root `src/app/layout.tsx`; requires production traffic |