@se-studio/skills 1.7.4 → 1.7.5

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/skills",
-  "version": "1.7.4",
+  "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

@@ -53,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/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`.