@se-studio/skills 1.7.3 → 1.7.5

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @se-studio/skills
 
+## 1.7.5
+
+### Patch Changes
+
+- 6b53e51: Document worktree `.env.local` handling: canonical store at `~/source/local-env`, no-clobber seed after `git worktree add`, 1Password as backup only (never overwrite). Seed catalogs the store, never writes through dest symlinks, and is invoked with `pnpm --dir ~/source/se/se-core-product`.
+
+## 1.7.4
+
+### Patch Changes
+
+- All marketing sites are on Next 16.3: drop the PointMe 15.5 deps exception, require `supportedArchitectures` in new-project bootstrap, and point agents at version-matched `nextjs-agent-rules` instead of the Next 15 `agents-md` docs dump.
+
 ## 1.7.3
 
 ### Patch Changes

package/package.json

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

package/references/agent-session/customer-agents-block.md

@@ -1,3 +1,7 @@
+## Next.js docs (version-matched)
+
+This site runs **Next.js 16.3**. Before writing Next.js code, read the relevant guide in `node_modules/next/dist/docs/` (in monorepos, resolve from the app that depends on `next`). Keep the managed `<!-- BEGIN:nextjs-agent-rules -->` block in `AGENTS.md`. Do **not** use `npx @next/codemod agents-md`, `.next-docs`, or `NEXT-AGENTS-MD-START` (Next 15 index: Pages Router, `middleware.ts`). Ignore `vercel-react-native-skills` if the vercel-labs pack installed it.
+
 ## Agent session workflow
 
 **Load skill `site-workflows-agent-session` at the start of every coding session.**
@@ -49,6 +53,7 @@ Never hand-edit `package.json` dependency versions.
 - **Git worktree required** for all feature work — do not implement on the primary `develop` checkout
   - Path: registry `worktreesRoot` / `<feature-slug>` (see se-core-product `packages/skills/references/agent-session/projects.registry.json`)
   - Create: `git worktree add <worktreesRoot>/<feature-slug> -b feature/<scope>/<slug> origin/develop`
+  - Then seed env: `pnpm --dir ~/source/se/se-core-product local-env seed --project <key>` (no-clobber copy of `.env.local`; never invent a stub or symlink at develop)
   - Manifest must set `worktree:`; opt out only if the user says “work in place” / “no worktree” (`worktree_opt_out: true`)
 - CMS edits: `--session <feature-slug>` (isolate cms-edit sessions)
 - Track in-flight work: manifest at `~/source/se/se-core-product/work/active/<feature>.yaml` (or `work/active/` in this repo if core checkout unavailable)

package/references/agent-session/local-env.md

@@ -0,0 +1,82 @@
+# Local env files and git worktrees
+
+Gitignored `.env.local` files do **not** copy into a new worktree. Agents then invent a stub file (two keys, missing Contentful, etc.) or symlink at develop and overwrite the canonical secrets.
+
+**Canonical doc** for this workflow. Also indexed from `docs/WORKFLOW.md`, `docs/DEVELOPMENT.md`, `AGENTS.md`, and skill `site-workflows-agent-session`.
+
+## Layout
+
+| Layer | Path | Role |
+|-------|------|------|
+| Canonical | `~/source/local-env/<project-key>/<relative-path>` | Source of truth on disk. Not a git repo. |
+| Develop checkout | registry `path` | Always-on integration branch. `init` copies from here into the store. |
+| Feature worktrees | `worktreesRoot/<slug>` | Independent **copies**. Never a symlink at develop or the store. |
+| 1Password | documents titled `local-env/<project-key>/<relative-path>` | Backup only. Create if missing. Never overwrite an existing item or checkout file. |
+
+`localEnvRoot` is set on `projects.registry.json` (`~/source/local-env`).
+
+Tracked files are whatever `.env.local` / `.env.*.local` exist on the **develop** checkout (`apps/*/.env.local` and `cms-edit/host/.env.local` included). Nested `experiments/` trees are ignored.
+
+The live Highlander repo (`highlander-health-website`, not the 2026 port) is `localEnvExtras` key `highlander-live` in the registry (not the `highlander` 2026 project). `pnpm local-env` catalogs it with the other sites.
+
+## Commands
+
+The script lives in **se-core-product**. From that repo, `pnpm local-env …` is enough. From a customer worktree, always pass `--dir`:
+
+```bash
+pnpm --dir ~/source/se/se-core-product local-env audit
+pnpm --dir ~/source/se/se-core-product local-env init
+pnpm --dir ~/source/se/se-core-product local-env seed
+pnpm --dir ~/source/se/se-core-product local-env seed --repair-subset --replace-symlinks
+pnpm --dir ~/source/se/se-core-product local-env bootstrap
+pnpm --dir ~/source/se/se-core-product local-env backup
+```
+
+`--project pointme` limits to one registry key. `--dry-run` prints actions.
+
+### After `git worktree add`
+
+```bash
+pnpm --dir ~/source/se/se-core-product local-env seed --project <key>
+```
+
+If the worktree file is a **subset** of canonical keys (typical stub), repair:
+
+```bash
+pnpm --dir ~/source/se/se-core-product local-env seed --project <key> --repair-subset --replace-symlinks
+```
+
+Subset repair copies the old file to `~/source/local-env/.bak/<project>/<relative-path>` (not next to the checkout file), then writes canonical. It does **not** touch a file that has extra keys (diverged). Production checkouts (`productionPath`) are audited only — never seeded. Default `seed` prints leftover `symlink` / `stub` / `subset` skips so a develop-symlink is not silent.
+
+### First-time machine (or after cloning develop)
+
+```bash
+pnpm --dir ~/source/se/se-core-product local-env bootstrap
+pnpm --dir ~/source/se/se-core-product local-env backup
+pnpm --dir ~/source/se/se-core-product local-env audit
+```
+
+### Rotate a token
+
+1. Edit the file in `~/source/local-env/<project>/…` (or edit develop, then `pnpm local-env init` — init will not overwrite an existing store file, so delete or rename the store file first if you mean to refresh it).
+2. `pnpm --dir ~/source/se/se-core-product local-env seed --project <key> --repair-subset` for worktrees that are a subset of the new key set.
+3. `pnpm --dir ~/source/se/se-core-product local-env backup` only creates a **new** 1Password title if missing. To refresh the backup, create a new document or edit the existing one in 1Password by hand — the command will not overwrite.
+
+## Agent rules
+
+1. After creating a worktree, seed env. Do not hand-write `.env.local`.
+2. If `.env.local` is missing, copy from `~/source/local-env/...` (or run `seed`). Never generate a two-key stub.
+3. If a file exists, leave it. Report `audit` status (`stub` / `subset` / `diverged` / `symlink`) instead of overwriting unless the user asks for `--repair-subset`.
+4. Do not symlink worktree env at develop or `~/source/local-env`.
+5. Do not `op inject` or `op document get` onto an existing checkout file. Restore to a temp path, `diff`, then copy only if the user confirms.
+6. `git worktree remove` deletes that tree’s copy. Canonical + 1Password remain.
+
+## Restore from 1Password (manual)
+
+```bash
+op document get --vault Private "local-env/pointme/.env.local" --out-file /tmp/pointme.env.local
+diff -u ~/source/local-env/pointme/.env.local /tmp/pointme.env.local
+# copy only if you intend to replace canonical, then seed
+```
+
+Older documents titled `Point.me env.local` (and similar, ~2026-03) are **stale** (fewer keys than develop). Do not restore those onto disk.

package/references/agent-session/projects.registry.json

@@ -10,6 +10,16 @@
     "pathPattern": "<worktreesRoot>/<feature-slug>",
     "notes": "Feature work (feature/*) must use a git worktree under the project's worktreesRoot. Primary checkouts stay on integration branches only. Opt out only if the user explicitly says work in place / no worktree in the current conversation."
   },
+  "localEnvRoot": "~/source/local-env",
+  "localEnvExtras": [
+    {
+      "key": "highlander-live",
+      "displayName": "Highlander Health (live Bond/Netlify)",
+      "path": "~/source/customers/highlander/highlander-health-website",
+      "worktreesRoot": "~/source/customers/highlander/worktrees",
+      "notes": "Live highlander-health-website, not the 2026 port. local-env only; agents still use registry key highlander for 2026 feature work."
+    }
+  ],
   "projects": [
     {
       "key": "se-core-product",
@@ -91,6 +101,18 @@
       "hostedMcp": "cms-edit-hsd",
       "validate": "pnpm validate",
       "notes": "Agents work only in path (develop) + feature worktrees under worktreesRoot. productionPath is human-only — never push production from agents."
+    },
+    {
+      "key": "highlander",
+      "displayName": "Highlander Health",
+      "path": "~/source/customers/highlander/highlander-health-website-2026",
+      "worktreesRoot": "~/source/customers/highlander/worktrees",
+      "branch": "port-2026",
+      "type": "customer",
+      "contentfulSpaceId": "bkkox68g99rn",
+      "hostedMcp": "cms-edit-highlander",
+      "validate": "pnpm check && pnpm type-check && pnpm validate:routes",
+      "notes": "New 2026 stack. Integration branch is port-2026 until go-live, then develop/main. Live Bond/Netlify site remains highlander-health-website. cms-edit DNS/OAuth for highlander.content.se.studio is a human gate."
     }
   ]
 }

package/references/deps-update/projects.registry.json

@@ -78,6 +78,16 @@
       "workspace": false,
       "hasPinOverrides": false,
       "notes": "Deps updates run on develop checkout only. Never push production branch; human promotes production-hsd-website."
+    },
+    {
+      "key": "highlander",
+      "displayName": "Highlander Health",
+      "path": "~/source/customers/highlander/highlander-health-website-2026",
+      "branch": "port-2026",
+      "validate": "pnpm check && pnpm type-check && pnpm validate:routes",
+      "workspace": true,
+      "hasPinOverrides": false,
+      "notes": "2026 port. Integration branch port-2026 until live; then develop/main."
     }
   ]
 }

package/references/lockfile-sync/README.md

@@ -54,13 +54,13 @@ Use `pnpm install --no-frozen-lockfile` only when intentionally repairing the lo
 
 Apply the full stack when touching deps or CI in each repo:
 
-| Repo | Pre-commit | CI develop/dev | CI hoisted | Vercel frozen (marketing) |
-|------|------------|----------------|------------|---------------------------|
-| brightline-sites | yes | yes | yes | yes |
-| pedestal-sites | — | partial | — | no |
-| om1-website | — | — | — | — |
-| se-website-2026 | yes | yes | yes | yes |
-| pointme | — | — | — | — |
-| hsd (`develop-hsd-website`; prod human-only: `production-hsd-website`) | yes | yes (develop) | n/a | yes |
-
-Update this table as repos adopt the pattern.
+| Repo | Pre-commit | CI integration branch | CI hoisted | Vercel frozen (marketing) | Vercel cms-edit hoisted |
+|------|------------|----------------------|------------|---------------------------|-------------------------|
+| brightline-sites | yes | develop | yes | yes | yes |
+| pedestal-sites | yes | develop | yes | yes | yes |
+| om1-website | yes | develop | yes | yes | yes |
+| se-website-2026 | yes | develop | yes | yes | yes |
+| pointme | yes | develop | yes | yes | yes |
+| hsd (`develop-hsd-website`; prod human-only: `production-hsd-website`) | yes | develop (+ `extended-port`) | yes | yes | yes |
+
+Update this table as repos adopt the pattern. Every cms-edit host `pnpm-workspace.yaml` must include `supportedArchitectures` (current + linux, x64, glibc).

package/skills/site-workflows-agent-session/SKILL.md

@@ -7,7 +7,9 @@ description: "Start and manage agent work sessions across se-core-product and cu
 
 Orchestrates **where** to work, **where code belongs**, and **how to isolate parallel features**. **Humans only** merge marketing production and core `main` — except **cms-edit-only** customer merges (reference `cms-edit-prod-merge.md`).
 
-**Registry:** [`packages/skills/references/agent-session/projects.registry.json`](../../references/agent-session/projects.registry.json) — repo paths, `worktreesRoot`, `productionPath` / `productionBranch`, integration branches, hosted MCP keys.
+**Registry:** [`packages/skills/references/agent-session/projects.registry.json`](../../references/agent-session/projects.registry.json) — repo paths, `worktreesRoot`, `productionPath` / `productionBranch`, integration branches, hosted MCP keys, `localEnvRoot`.
+
+**Local env / worktrees:** [`local-env.md`](../../references/agent-session/local-env.md) — canonical `~/source/local-env`, no-clobber seed, 1Password backup only.
 
 **Manifest template:** [`packages/skills/references/agent-session/manifest.template.yaml`](../../references/agent-session/manifest.template.yaml)
 
@@ -151,9 +153,13 @@ cd <primary_repo>   # registry path — develop/dev checkout
 git fetch origin
 mkdir -p <worktreesRoot>   # from registry, e.g. ~/source/customers/hopskipdrive/worktrees
 git worktree add <worktreesRoot>/<feature-slug> -b <branch> origin/<integration-branch>
+# Script lives in se-core-product — do not run this from a customer worktree
+pnpm --dir ~/source/se/se-core-product local-env seed --project <project_key>
 cd <worktreesRoot>/<feature-slug>
 ```
 
+`.env.local` is gitignored and does **not** appear in a new worktree. Seed with `pnpm --dir ~/source/se/se-core-product local-env` — do not hand-write a stub and do not symlink at develop. Full rules: [`local-env.md`](../../references/agent-session/local-env.md).
+
 | Project key | worktreesRoot |
 |-------------|---------------|
 | `se-core-product` | `~/source/se/worktrees` |
@@ -163,6 +169,7 @@ cd <worktreesRoot>/<feature-slug>
 | `pointme` | `~/source/customers/pointme/worktrees` |
 | `pedestal` | `~/source/customers/pedestal/worktrees` |
 | `hsd` | `~/source/customers/hopskipdrive/worktrees` |
+| `highlander` | `~/source/customers/highlander/worktrees` |
 
 **Manifest gate:** set `worktree:` to the worktree path before coding. Do all edits, installs, tests, and commits from that path. Do not leave the primary checkout on a feature branch.
 
@@ -359,5 +366,6 @@ Agent must load this skill, write manifest (with `worktree` path), run placement
 | `pointme` | `develop` | `main` | customer |
 | `pedestal` | `develop` | `main` | customer monorepo |
 | `hsd` | `develop` (`develop-hsd-website`) | `production` (`production-hsd-website`) | customer |
+| `highlander` | `port-2026` until live, then `develop` | `main` after cutover | customer |
 
 Full paths (`path`, `worktreesRoot`, `productionPath`), MCP keys: `projects.registry.json`.

package/skills/site-workflows-deps-update/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: site-workflows-deps-update
-description: "Update npm dependencies to latest across se-core-product and consumer SE Studio sites, one repo at a time. Pins Next.js 16.3 and Node 24, updates pnpm to latest 11.x, enforces no pnpm patches everywhere. Validates, commits, and pushes to dev/develop. PointMe stays on Next 15.5 until its dedicated upgrade. Use when asked to update outdated packages or bump dependencies."
+description: "Update npm dependencies to latest across se-core-product and consumer SE Studio sites, one repo at a time. Pins Next.js 16.3 and Node 24, updates pnpm to latest 11.x, enforces no pnpm patches everywhere. Validates, commits, and pushes to dev/develop. Use when asked to update outdated packages or bump dependencies."
 ---
 
 # SE dependency update (one project at a time)
@@ -11,7 +11,7 @@ Update npm dependencies to **latest** in se-core-product and consumer repos that
 
 **Default:** Process **one repo per invocation**. At the end, summarize changes and offer the next project.
 
-**Never:** push to `main`/`master`/`production` or any production branch; promote from production checkouts (e.g. HSD `production-hsd-website`); bump Next to 17; bump Node to 25+; use `pnpm patch` / `patchedDependencies` / `patches/`; bypass or remove `minimumReleaseAge`; **hand-edit `package.json` dependency versions** (use `pnpm update` instead). Production promotion is **human-only** for all customer sites. **PointMe:** keep `overrides.next` on `^15.5.x` until the Next 16 site wave — do not pull it to 16 during a routine deps update.
+**Never:** push to `main`/`master`/`production` or any production branch; promote from production checkouts (e.g. HSD `production-hsd-website`); bump Next to 17; bump Node to 25+; use `pnpm patch` / `patchedDependencies` / `patches/`; bypass or remove `minimumReleaseAge`; **hand-edit `package.json` dependency versions** (use `pnpm update` instead). Production promotion is **human-only** for all customer sites. All marketing sites pin `overrides.next` to `^16.3.x`.
 
 ---
 
@@ -126,12 +126,21 @@ Without this, isolated `pnpm install` on darwin can omit snapshots such as `@rol
 - **`minimumReleaseAge: 1440`** — do not install packages published in the last 24 hours (supply-chain guard).
 - **`@se-studio/*` exclude** — our own packages may update immediately after npm publish.
 - **Keep repo-specific additional excludes** when present (e.g. vitest pins in se-core-product, `@emnapi/runtime` in se-website-2026, PointMe `mapbox-gl` / `react-day-picker` overrides).
-- **PointMe exception:** leave `next: ^15.5.x` until that site’s Next 16 wave.
+- **PointMe:** keep extra overrides (`mapbox-gl`, `react-day-picker`, `caniuse-lite`) — still pin `next: ^16.3.x` like every other site.
 
 `pnpm update -r --latest` would bump `next` past the supported 16.3 line and `@types/node` → 26 without the overrides block. The overrides prevent that.
 
 **Never bypass `minimumReleaseAge`** during dependency updates. Do not remove the block, comment it out, or use undocumented pnpm flags. If a non-`@se-studio` package was published within 24 hours, it stays at the current version until it ages out — note that in the report and re-run later if needed.
 
+### Next.js 16 agent docs (do not use the Next 15 dump)
+
+Marketing sites run **Next.js 16.3**. Version-matched docs live in each app’s `node_modules/next/dist/docs/` (the `next` package may not be visible from a monorepo root).
+
+- **Keep** the managed `<!-- BEGIN:nextjs-agent-rules -->` block that `next dev` writes in `AGENTS.md`.
+- **Do not** run `npx @next/codemod agents-md` or restore `NEXT-AGENTS-MD-START` / `.next-docs` — that index is Next 15 (Pages Router, `middleware.ts`, upgrade guides only through v15).
+- Cursor’s Vercel plugin **`nextjs`** skill is fine for App Router patterns; it is not a substitute for `node_modules/next/dist/docs/`.
+- After `npx skills add vercel-labs/agent-skills`, **delete `vercel-react-native-skills`** — these are web sites. Do not treat React Native skills as Next guidance.
+
 ---
 
 ## Step 4 — Update pnpm (all repos)
@@ -236,7 +245,7 @@ Include in the summary:
 
 - Major dependency bumps (from the Step 1 audit diff)
 - pnpm version: before → after
-- Confirmed pins: Next 16.3.x (PointMe: Next 15.5.x until its upgrade), Node 24, `@types/node` ^24
+- Confirmed pins: Next 16.3.x, Node 24, `@types/node` ^24
 - Confirmed `minimumReleaseAge: 1440` and `@se-studio/*` exclude present
 - Packages still outdated because they are inside the 24-hour release window (if any)
 - Patches check bootstrapped (yes/no)
@@ -274,6 +283,7 @@ See [`references/lockfile-sync/README.md`](../../references/lockfile-sync/README
 | Issue | Action |
 |-------|--------|
 | `ERR_PNPM_OUTDATED_LOCKFILE` on frozen/hoisted install | `package.json` and `pnpm-workspace.yaml` overrides out of sync with lockfile — re-run `pnpm update` for the package and align `overrides` |
+| `ERR_PNPM_LOCKFILE_MISSING_DEPENDENCY` (`rollup-linux-*`, Sharp, etc.) on hoisted frozen install | Missing `supportedArchitectures` (current + linux, x64, glibc) — add the Step 3 block, run `pnpm install`, then re-verify hoisted |
 | `next` or `@types/node` still outdated to wrong major | Re-run overrides + safety re-pin; check `pnpm-workspace.yaml` overrides |
 | Non-`@se-studio` package still outdated after update | Likely within 24h of npm publish — wait and re-run; **do not** bypass `minimumReleaseAge` |
 | `corepack use` fails | Run `corepack enable` once, retry |

package/skills/site-workflows-new-project/SKILL.md

@@ -40,6 +40,36 @@ After cleanup, `pnpm validate` must pass before continuing.
 
 ---
 
+## Step 2b — Workspace install policy (`pnpm-workspace.yaml`)
+
+Merge these into the existing file (do not wipe `packages`, `allowBuilds`, or other keys). Canonical copy: skill `site-workflows-deps-update` Step 3.
+
+```yaml
+# Record linux-x64/glibc optional natives (cms-edit Vercel + hoisted frozen install).
+supportedArchitectures:
+  os:
+    - current
+    - linux
+  cpu:
+    - current
+    - x64
+  libc:
+    - current
+    - glibc
+
+minimumReleaseAge: 1440
+minimumReleaseAgeExclude:
+  - '@se-studio/*'
+
+overrides:
+  next: ^16.3.1
+  '@types/node': ^24.13.2
+```
+
+Then `pnpm install` (not frozen) so the lockfile records linux optional snapshots. Confirm `AGENTS.md` uses `nextjs-agent-rules` (Next 16 `node_modules/next/dist/docs/`), not `NEXT-AGENTS-MD-START` / `.next-docs`.
+
+---
+
 ## Step 3 — Update project identity in `src/lib/constants.ts`
 
 Read `src/lib/constants.ts` and update:
@@ -84,6 +114,8 @@ This version has breaking changes — APIs, conventions, and file structure may
 
 This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
 
+Do **not** replace this with `npx @next/codemod agents-md` (Next 15 `.next-docs` index).
+
 <!-- END:nextjs-agent-rules -->
 
 <!-- BEGIN:se-studio-package-rules -->