From e0797233cd1f09bd00a5bedceea4f915165ebca2 Mon Sep 17 00:00:00 2001
From: Aleksei Gurianov <gurianov@gmail.com>
Date: Sat, 3 Oct 2026 19:26:47 +0000
Subject: [PATCH 01/11] feat: materialize agent skills via APM in mise deps
 lifecycle

Declare Reatom agent skills in apm.yml and install them through a new
[deps.skills] mise dependency provider. Skills deploy into .agents/skills
(agent-skills target), which stays gitignored and is reproduced by
'apm install' from the committed apm.lock.yaml (hash-pinned).

- pin APM to a git commit: released 0.4.3 rejects SKILL_BUNDLE packages
- ignore .agents/skills and apm_modules/
- document the workflow in docs/tooling.md
---
 .config/mise/conf.d/_config.toml |  10 +++
 .gitignore                       |   6 ++
 apm.lock.yaml                    | 131 +++++++++++++++++++++++++++++++
 apm.yml                          |   7 ++
 docs/tooling.md                  |  15 ++++
 5 files changed, 169 insertions(+)
 create mode 100644 apm.lock.yaml
 create mode 100644 apm.yml

diff --git a/.config/mise/conf.d/_config.toml b/.config/mise/conf.d/_config.toml
index 43174020..b2070773 100644
--- a/.config/mise/conf.d/_config.toml
+++ b/.config/mise/conf.d/_config.toml
@@ -6,6 +6,7 @@ node = "lts"
 jq = "latest"
 vp = "latest"
 hk = "latest"
+uv = "0.12"
 
 [task_config]
 dir = "{{ config_root }}"
@@ -24,3 +25,12 @@ run = "nub install"
 
 [shell_alias]
 mr = "mise run"
+
+# Agent skills materialized by APM (see apm.yml); output is gitignored.
+[deps.skills]
+auto = true
+sources = ["apm.yml"]
+outputs = [".agents/skills"]
+# Pinned to microsoft/apm main (v0.33.0-dev): skill-bundle installs need
+# an unreleased fix (released 0.4.3 rejects SKILL_BUNDLE packages).
+run = "uvx --from 'git+https://github.com/microsoft/apm@18c4c43c924ceae890fe0f2038806690e5b2d6c8' apm install --only apm"
diff --git a/.gitignore b/.gitignore
index 7914e40f..0bcd4ae8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -51,3 +51,9 @@ progress*.txt
 # vitest browser-mode failure screenshots
 __screenshots__/
 .vitest-attachments/
+
+# APM dependencies
+apm_modules/
+
+# APM-materialized agent skills (generated from apm.yml, do not edit)
+.agents/skills/
diff --git a/apm.lock.yaml b/apm.lock.yaml
new file mode 100644
index 00000000..2f9191e9
--- /dev/null
+++ b/apm.lock.yaml
@@ -0,0 +1,131 @@
+lockfile_version: '1'
+apm_version: 0.33.0
+dependencies:
+- repo_url: reatom/reatom
+  name: reatom
+  host: github.com
+  resolved_commit: b48778e3bf3a80d85b176157b094c2470d0ab86e
+  resolved_ref: v1001
+  version: unknown
+  package_type: skill_bundle
+  deployed_files:
+  - .agents/skills/reatom
+  - .agents/skills/reatom-async
+  - .agents/skills/reatom-async/REFERENCE.md
+  - .agents/skills/reatom-async/SKILL.md
+  - .agents/skills/reatom-jsx
+  - .agents/skills/reatom-jsx/REFERENCE.md
+  - .agents/skills/reatom-jsx/SKILL.md
+  - .agents/skills/reatom-review
+  - .agents/skills/reatom-review/SKILL.md
+  - .agents/skills/reatom/REFERENCE.md
+  - .agents/skills/reatom/SKILL.md
+  deployed_file_hashes:
+    .agents/skills/reatom-async/REFERENCE.md: sha256:8cdbdd44a17ec47d4ab4ef36186d502c838517df020c6c14044733d188476951
+    .agents/skills/reatom-async/SKILL.md: sha256:a6acfcc8886475923b93e280564193fbfb97be2385df65c758b1d1eec2c7505d
+    .agents/skills/reatom-jsx/REFERENCE.md: sha256:55f87fcefed94fd6b63e5ebfd11dd4c6aac1f7fd61b06d73cca25f212306401c
+    .agents/skills/reatom-jsx/SKILL.md: sha256:e26740b0cc7a3f1ddd0556e0bde67c27381bd0ae50a25619d603fe2a2873a6c2
+    .agents/skills/reatom-review/SKILL.md: sha256:219e3e15521b23d5e88629461c6891fdf95b0b01fbe94620939a6040fa5c6520
+    .agents/skills/reatom/REFERENCE.md: sha256:8dd96cc5bfb697a1848377f98a8a227901cc4144b767293c609822e8191b1b69
+    .agents/skills/reatom/SKILL.md: sha256:2954dab61ae3495ade98ea222164af4e20ae8973c1f0fdcf2875708e78c2da27
+  content_hash: sha256:ac7b61894281e986ec77f58dfe6bbeef9bb12602a3c4e461769303c42d336b29
+deployments:
+- kind: project-relative
+  target: agent-skills
+  value: .agents/skills/reatom
+  runtime: null
+  scope: project
+  owners:
+  - reatom/reatom
+  active_owner: reatom/reatom
+  content_hash: null
+- kind: project-relative
+  target: agent-skills
+  value: .agents/skills/reatom-async
+  runtime: null
+  scope: project
+  owners:
+  - reatom/reatom
+  active_owner: reatom/reatom
+  content_hash: null
+- kind: project-relative
+  target: agent-skills
+  value: .agents/skills/reatom-async/REFERENCE.md
+  runtime: null
+  scope: project
+  owners:
+  - reatom/reatom
+  active_owner: reatom/reatom
+  content_hash: sha256:8cdbdd44a17ec47d4ab4ef36186d502c838517df020c6c14044733d188476951
+- kind: project-relative
+  target: agent-skills
+  value: .agents/skills/reatom-async/SKILL.md
+  runtime: null
+  scope: project
+  owners:
+  - reatom/reatom
+  active_owner: reatom/reatom
+  content_hash: sha256:a6acfcc8886475923b93e280564193fbfb97be2385df65c758b1d1eec2c7505d
+- kind: project-relative
+  target: agent-skills
+  value: .agents/skills/reatom-jsx
+  runtime: null
+  scope: project
+  owners:
+  - reatom/reatom
+  active_owner: reatom/reatom
+  content_hash: null
+- kind: project-relative
+  target: agent-skills
+  value: .agents/skills/reatom-jsx/REFERENCE.md
+  runtime: null
+  scope: project
+  owners:
+  - reatom/reatom
+  active_owner: reatom/reatom
+  content_hash: sha256:55f87fcefed94fd6b63e5ebfd11dd4c6aac1f7fd61b06d73cca25f212306401c
+- kind: project-relative
+  target: agent-skills
+  value: .agents/skills/reatom-jsx/SKILL.md
+  runtime: null
+  scope: project
+  owners:
+  - reatom/reatom
+  active_owner: reatom/reatom
+  content_hash: sha256:e26740b0cc7a3f1ddd0556e0bde67c27381bd0ae50a25619d603fe2a2873a6c2
+- kind: project-relative
+  target: agent-skills
+  value: .agents/skills/reatom-review
+  runtime: null
+  scope: project
+  owners:
+  - reatom/reatom
+  active_owner: reatom/reatom
+  content_hash: null
+- kind: project-relative
+  target: agent-skills
+  value: .agents/skills/reatom-review/SKILL.md
+  runtime: null
+  scope: project
+  owners:
+  - reatom/reatom
+  active_owner: reatom/reatom
+  content_hash: sha256:219e3e15521b23d5e88629461c6891fdf95b0b01fbe94620939a6040fa5c6520
+- kind: project-relative
+  target: agent-skills
+  value: .agents/skills/reatom/REFERENCE.md
+  runtime: null
+  scope: project
+  owners:
+  - reatom/reatom
+  active_owner: reatom/reatom
+  content_hash: sha256:8dd96cc5bfb697a1848377f98a8a227901cc4144b767293c609822e8191b1b69
+- kind: project-relative
+  target: agent-skills
+  value: .agents/skills/reatom/SKILL.md
+  runtime: null
+  scope: project
+  owners:
+  - reatom/reatom
+  active_owner: reatom/reatom
+  content_hash: sha256:2954dab61ae3495ade98ea222164af4e20ae8973c1f0fdcf2875708e78c2da27
diff --git a/apm.yml b/apm.yml
new file mode 100644
index 00000000..a8429c05
--- /dev/null
+++ b/apm.yml
@@ -0,0 +1,7 @@
+name: karkas
+version: 1.0.0
+dependencies:
+  apm:
+    - reatom/reatom#v1001
+targets:
+  - agent-skills
diff --git a/docs/tooling.md b/docs/tooling.md
index 94aecf3d..8eb3a518 100644
--- a/docs/tooling.md
+++ b/docs/tooling.md
@@ -86,3 +86,18 @@ decision.
 - `sharp`: denied; no current workflow requires its native install path.
 
 Review newly requested scripts with `nub ignored-builds` before changing these decisions.
+
+## Agent skills
+
+Agent skills are declared in `apm.yml` (Microsoft APM) and materialized into
+`.agents/skills/`, which is gitignored. mise runs the install automatically as
+the `skills` dependency provider whenever `apm.yml` changes:
+
+```sh
+mise deps install skills   # run manually
+mise deps --explain skills # inspect the freshness decision
+```
+
+`apm.lock.yaml` pins resolved git commits and content hashes and is committed.
+The provider runs APM from a pinned git commit because released APM (0.4.3)
+cannot install skill-bundle packages yet.

From 83336c8af3062ca99f8107a2015c64a0e0b1a83d Mon Sep 17 00:00:00 2001
From: Aleksei Gurianov <gurianov@gmail.com>
Date: Sat, 3 Oct 2026 19:33:46 +0000
Subject: [PATCH 02/11] refactor: run APM as a mise-managed tool instead of uvx

APM v0.33.0 (released yesterday) supports SKILL_BUNDLE installs, so the
provider now uses the registry-backed apm tool pinned in _config.toml
rather than a uvx git build.
---
 .config/mise/conf.d/_config.toml | 6 ++----
 docs/tooling.md                  | 4 ++--
 2 files changed, 4 insertions(+), 6 deletions(-)

diff --git a/.config/mise/conf.d/_config.toml b/.config/mise/conf.d/_config.toml
index b2070773..a69ca4e1 100644
--- a/.config/mise/conf.d/_config.toml
+++ b/.config/mise/conf.d/_config.toml
@@ -6,7 +6,7 @@ node = "lts"
 jq = "latest"
 vp = "latest"
 hk = "latest"
-uv = "0.12"
+apm = "0.33.0"
 
 [task_config]
 dir = "{{ config_root }}"
@@ -31,6 +31,4 @@ mr = "mise run"
 auto = true
 sources = ["apm.yml"]
 outputs = [".agents/skills"]
-# Pinned to microsoft/apm main (v0.33.0-dev): skill-bundle installs need
-# an unreleased fix (released 0.4.3 rejects SKILL_BUNDLE packages).
-run = "uvx --from 'git+https://github.com/microsoft/apm@18c4c43c924ceae890fe0f2038806690e5b2d6c8' apm install --only apm"
+run = "apm install --only apm"
diff --git a/docs/tooling.md b/docs/tooling.md
index 8eb3a518..f2c6a8c4 100644
--- a/docs/tooling.md
+++ b/docs/tooling.md
@@ -99,5 +99,5 @@ mise deps --explain skills # inspect the freshness decision
 ```
 
 `apm.lock.yaml` pins resolved git commits and content hashes and is committed.
-The provider runs APM from a pinned git commit because released APM (0.4.3)
-cannot install skill-bundle packages yet.
+The `apm` CLI is pinned in `_config.toml` (0.33.0+ is required to install
+skill-bundle packages such as `reatom/reatom`).

From 61e7af450f074951b3fafc37beb5d2782c1f666a Mon Sep 17 00:00:00 2001
From: Aleksei Gurianov <gurianov@gmail.com>
Date: Sat, 3 Oct 2026 19:36:12 +0000
Subject: [PATCH 03/11] feat: add kahraman storybook-testing skill to APM deps

---
 apm.lock.yaml | 31 +++++++++++++++++++++++++++++++
 apm.yml       |  1 +
 2 files changed, 32 insertions(+)

diff --git a/apm.lock.yaml b/apm.lock.yaml
index 2f9191e9..23be9a32 100644
--- a/apm.lock.yaml
+++ b/apm.lock.yaml
@@ -1,6 +1,19 @@
 lockfile_version: '1'
 apm_version: 0.33.0
 dependencies:
+- repo_url: apphane-dev/kahraman
+  name: kahraman
+  host: github.com
+  resolved_commit: fb984ed4c2f3b7bf77414d03526f6353a8f894f5
+  resolved_ref: v0.3.1
+  version: unknown
+  package_type: skill_bundle
+  deployed_files:
+  - .agents/skills/kahraman-storybook-testing
+  - .agents/skills/kahraman-storybook-testing/SKILL.md
+  deployed_file_hashes:
+    .agents/skills/kahraman-storybook-testing/SKILL.md: sha256:92883384858f07732f62e04b679f7c0d3750beb2c5eac26a4b92da0c7d87c3eb
+  content_hash: sha256:e271e09b53f348ac1e86e3a4bd9906433a1295ad5d2f043470940f101c6a7220
 - repo_url: reatom/reatom
   name: reatom
   host: github.com
@@ -30,6 +43,24 @@ dependencies:
     .agents/skills/reatom/SKILL.md: sha256:2954dab61ae3495ade98ea222164af4e20ae8973c1f0fdcf2875708e78c2da27
   content_hash: sha256:ac7b61894281e986ec77f58dfe6bbeef9bb12602a3c4e461769303c42d336b29
 deployments:
+- kind: project-relative
+  target: agent-skills
+  value: .agents/skills/kahraman-storybook-testing
+  runtime: null
+  scope: project
+  owners:
+  - apphane-dev/kahraman
+  active_owner: apphane-dev/kahraman
+  content_hash: null
+- kind: project-relative
+  target: agent-skills
+  value: .agents/skills/kahraman-storybook-testing/SKILL.md
+  runtime: null
+  scope: project
+  owners:
+  - apphane-dev/kahraman
+  active_owner: apphane-dev/kahraman
+  content_hash: sha256:92883384858f07732f62e04b679f7c0d3750beb2c5eac26a4b92da0c7d87c3eb
 - kind: project-relative
   target: agent-skills
   value: .agents/skills/reatom
diff --git a/apm.yml b/apm.yml
index a8429c05..2ee0be98 100644
--- a/apm.yml
+++ b/apm.yml
@@ -3,5 +3,6 @@ version: 1.0.0
 dependencies:
   apm:
     - reatom/reatom#v1001
+    - apphane-dev/kahraman#v0.3.1
 targets:
   - agent-skills

From 5a3e04423e2397f7dd69dbcdbc3d0156fe8e46e2 Mon Sep 17 00:00:00 2001
From: Aleksei Gurianov <gurianov@gmail.com>
Date: Sat, 3 Oct 2026 20:01:18 +0000
Subject: [PATCH 04/11] feat: add poteto unslop skill and automated skill
 updates

- pin cursor/plugins unslop (repo-local so every clone gets it, matching
  the machine-wide skill set)
- add skills:update mise task (apm install --update)
- add weekly skills-update workflow that opens a PR when refs move
---
 .config/mise/conf.d/tasks-skills.toml |  3 ++
 .github/workflows/skills-update.yml   | 56 +++++++++++++++++++++++++++
 apm.lock.yaml                         | 33 ++++++++++++++++
 apm.yml                               |  1 +
 docs/tooling.md                       |  4 ++
 5 files changed, 97 insertions(+)
 create mode 100644 .config/mise/conf.d/tasks-skills.toml
 create mode 100644 .github/workflows/skills-update.yml

diff --git a/.config/mise/conf.d/tasks-skills.toml b/.config/mise/conf.d/tasks-skills.toml
new file mode 100644
index 00000000..f683c5b0
--- /dev/null
+++ b/.config/mise/conf.d/tasks-skills.toml
@@ -0,0 +1,3 @@
+[tasks."skills:update"]
+description = "Bump APM skill dependencies to latest refs and re-materialize"
+run = "apm install --update --only apm"
diff --git a/.github/workflows/skills-update.yml b/.github/workflows/skills-update.yml
new file mode 100644
index 00000000..033a428a
--- /dev/null
+++ b/.github/workflows/skills-update.yml
@@ -0,0 +1,56 @@
+name: Skills update
+
+on:
+  schedule:
+    - cron: "0 6 * * 1" # weekly, Monday 06:00 UTC
+  workflow_dispatch:
+
+concurrency:
+  group: skills-update
+  cancel-in-progress: false
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Setup mise
+        uses: jdx/mise-action@1648a7812b9aeae629881980618f079932869151 # v4.0.1
+        with:
+          install: true
+          cache: true
+
+      - name: Config mise
+        run: mise settings experimental=true
+
+      - name: Update skill dependencies
+        run: mise run --no-deps skills:update
+
+      - name: Open update PR
+        id: pr
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          if git diff --quiet apm.yml apm.lock.yaml; then
+            echo "updated=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          branch="chore/skills-update"
+          git checkout -b "$branch"
+          git commit -am "chore: update agent skill dependencies"
+          git push origin "$branch" --force
+          gh pr list --head "$branch" --state open --json number --jq '.[0].number' | xargs -r -I{} gh pr merge {} --auto --squash || true
+          gh pr create \
+            --head "$branch" \
+            --title "chore: update agent skill dependencies" \
+            --body "Automated bump of apm.yml skill refs and apm.lock.yaml hashes via \`mise run skills:update\`."
+          echo "updated=true" >> "$GITHUB_OUTPUT"
diff --git a/apm.lock.yaml b/apm.lock.yaml
index 23be9a32..45986619 100644
--- a/apm.lock.yaml
+++ b/apm.lock.yaml
@@ -14,6 +14,21 @@ dependencies:
   deployed_file_hashes:
     .agents/skills/kahraman-storybook-testing/SKILL.md: sha256:92883384858f07732f62e04b679f7c0d3750beb2c5eac26a4b92da0c7d87c3eb
   content_hash: sha256:e271e09b53f348ac1e86e3a4bd9906433a1295ad5d2f043470940f101c6a7220
+- repo_url: cursor/plugins
+  name: unslop
+  host: github.com
+  resolved_commit: 23e4138daa01c42d4969f7a5465f82704e64f798
+  resolved_ref: main
+  version: unknown
+  virtual_path: pstack/skills/unslop
+  is_virtual: true
+  package_type: claude_skill
+  deployed_files:
+  - .agents/skills/unslop
+  - .agents/skills/unslop/SKILL.md
+  deployed_file_hashes:
+    .agents/skills/unslop/SKILL.md: sha256:195411d320b5b328f9f642baf59757ed19aaf0931c0838740e0aca273d538dc1
+  content_hash: sha256:6018ca8c329ba87c6b4298207f58d6b773fe23e44ff52a00a9a4d160c19bedc0
 - repo_url: reatom/reatom
   name: reatom
   host: github.com
@@ -160,3 +175,21 @@ deployments:
   - reatom/reatom
   active_owner: reatom/reatom
   content_hash: sha256:2954dab61ae3495ade98ea222164af4e20ae8973c1f0fdcf2875708e78c2da27
+- kind: project-relative
+  target: agent-skills
+  value: .agents/skills/unslop
+  runtime: null
+  scope: project
+  owners:
+  - cursor/plugins/pstack/skills/unslop
+  active_owner: cursor/plugins/pstack/skills/unslop
+  content_hash: null
+- kind: project-relative
+  target: agent-skills
+  value: .agents/skills/unslop/SKILL.md
+  runtime: null
+  scope: project
+  owners:
+  - cursor/plugins/pstack/skills/unslop
+  active_owner: cursor/plugins/pstack/skills/unslop
+  content_hash: sha256:195411d320b5b328f9f642baf59757ed19aaf0931c0838740e0aca273d538dc1
diff --git a/apm.yml b/apm.yml
index 2ee0be98..8dad7210 100644
--- a/apm.yml
+++ b/apm.yml
@@ -4,5 +4,6 @@ dependencies:
   apm:
     - reatom/reatom#v1001
     - apphane-dev/kahraman#v0.3.1
+    - cursor/plugins/pstack/skills/unslop#main
 targets:
   - agent-skills
diff --git a/docs/tooling.md b/docs/tooling.md
index f2c6a8c4..5d809da9 100644
--- a/docs/tooling.md
+++ b/docs/tooling.md
@@ -101,3 +101,7 @@ mise deps --explain skills # inspect the freshness decision
 `apm.lock.yaml` pins resolved git commits and content hashes and is committed.
 The `apm` CLI is pinned in `_config.toml` (0.33.0+ is required to install
 skill-bundle packages such as `reatom/reatom`).
+
+Updating: `mise run skills:update` bumps every `apm.yml` ref to the latest
+upstream tag/commit and refreshes `apm.lock.yaml` hashes. CI runs the same
+command weekly (`skills-update.yml`) and opens a PR when anything moved.

From b1cb75edb60b4a8a9eb39cb149d15728fdb52549 Mon Sep 17 00:00:00 2001
From: Aleksei Gurianov <gurianov@gmail.com>
Date: Sat, 3 Oct 2026 20:03:05 +0000
Subject: [PATCH 05/11] fix(ci): bump hk.pkl schema package to v2.4.0 for hk
 2.x

hk is pinned to latest in mise and now resolves to 2.x, which cannot
evaluate a config amending the v1.46.0 schema package (pklr fails with
"listing index amendment requires an Int index"), so prepare:git-hooks
- and with it the whole test workflow - dies before any checks run.
hk 2.4.0 validates and installs hooks cleanly against its own v2.4.0
package, matching what hk init generates.
---
 .config/hk.pkl | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.config/hk.pkl b/.config/hk.pkl
index 67d80021..da93a0df 100644
--- a/.config/hk.pkl
+++ b/.config/hk.pkl
@@ -1,5 +1,5 @@
-amends "package://github.com/jdx/hk/releases/download/v1.46.0/hk@1.46.0#/Config.pkl"
-import "package://github.com/jdx/hk/releases/download/v1.46.0/hk@1.46.0#/Builtins.pkl"
+amends "package://github.com/jdx/hk/releases/download/v2.4.0/hk@2.4.0#/Config.pkl"
+import "package://github.com/jdx/hk/releases/download/v2.4.0/hk@2.4.0#/Builtins.pkl"
 
 local format = new Step {
   check = "mise run format:check"

From c4be2e71ed3d494518c0136cb9c0e0f6dd71281d Mon Sep 17 00:00:00 2001
From: Aleksei Gurianov <gurianov@gmail.com>
Date: Sat, 3 Oct 2026 20:04:51 +0000
Subject: [PATCH 06/11] feat: fetch TypeScript guide and auto-enable agent
 invocation

- add cursor/plugins typescript-best-practices to apm.yml
- strip disable-model-invocation from unslop and the TS guide via a
  post-install lifecycle hook (scripts/patch-skills.sh)
---
 apm.lock.yaml           | 44 +++++++++++++++++++++++++++++++++++++++++
 apm.yml                 |  7 +++++++
 docs/tooling.md         |  6 ++++++
 scripts/patch-skills.sh |  9 +++++++++
 4 files changed, 66 insertions(+)
 create mode 100755 scripts/patch-skills.sh

diff --git a/apm.lock.yaml b/apm.lock.yaml
index 45986619..87c91bb4 100644
--- a/apm.lock.yaml
+++ b/apm.lock.yaml
@@ -14,6 +14,23 @@ dependencies:
   deployed_file_hashes:
     .agents/skills/kahraman-storybook-testing/SKILL.md: sha256:92883384858f07732f62e04b679f7c0d3750beb2c5eac26a4b92da0c7d87c3eb
   content_hash: sha256:e271e09b53f348ac1e86e3a4bd9906433a1295ad5d2f043470940f101c6a7220
+- repo_url: cursor/plugins
+  name: typescript-best-practices
+  host: github.com
+  resolved_commit: 23e4138daa01c42d4969f7a5465f82704e64f798
+  resolved_ref: main
+  version: unknown
+  virtual_path: pstack/skills/typescript-best-practices
+  is_virtual: true
+  package_type: claude_skill
+  deployed_files:
+  - .agents/skills/typescript-best-practices
+  - .agents/skills/typescript-best-practices/SKILL.md
+  - .agents/skills/typescript-best-practices/references/patterns.md
+  deployed_file_hashes:
+    .agents/skills/typescript-best-practices/SKILL.md: sha256:28f9e61710e205f6f3c5476f333483cff0e988f6a5b639e2faad536344b40c5e
+    .agents/skills/typescript-best-practices/references/patterns.md: sha256:faa1362055374452efccac1b629677c61acfb0bcc6c4e3311836b5715638ee18
+  content_hash: sha256:59b3d20cf0939379ac9120ab9fb94076ad3aec99177308c699c720f475bcbd2c
 - repo_url: cursor/plugins
   name: unslop
   host: github.com
@@ -175,6 +192,33 @@ deployments:
   - reatom/reatom
   active_owner: reatom/reatom
   content_hash: sha256:2954dab61ae3495ade98ea222164af4e20ae8973c1f0fdcf2875708e78c2da27
+- kind: project-relative
+  target: agent-skills
+  value: .agents/skills/typescript-best-practices
+  runtime: null
+  scope: project
+  owners:
+  - cursor/plugins/pstack/skills/typescript-best-practices
+  active_owner: cursor/plugins/pstack/skills/typescript-best-practices
+  content_hash: null
+- kind: project-relative
+  target: agent-skills
+  value: .agents/skills/typescript-best-practices/SKILL.md
+  runtime: null
+  scope: project
+  owners:
+  - cursor/plugins/pstack/skills/typescript-best-practices
+  active_owner: cursor/plugins/pstack/skills/typescript-best-practices
+  content_hash: sha256:28f9e61710e205f6f3c5476f333483cff0e988f6a5b639e2faad536344b40c5e
+- kind: project-relative
+  target: agent-skills
+  value: .agents/skills/typescript-best-practices/references/patterns.md
+  runtime: null
+  scope: project
+  owners:
+  - cursor/plugins/pstack/skills/typescript-best-practices
+  active_owner: cursor/plugins/pstack/skills/typescript-best-practices
+  content_hash: sha256:faa1362055374452efccac1b629677c61acfb0bcc6c4e3311836b5715638ee18
 - kind: project-relative
   target: agent-skills
   value: .agents/skills/unslop
diff --git a/apm.yml b/apm.yml
index 8dad7210..416a9bab 100644
--- a/apm.yml
+++ b/apm.yml
@@ -5,5 +5,12 @@ dependencies:
     - reatom/reatom#v1001
     - apphane-dev/kahraman#v0.3.1
     - cursor/plugins/pstack/skills/unslop#main
+    - cursor/plugins/pstack/skills/typescript-best-practices#main
 targets:
   - agent-skills
+lifecycle:
+  post-install:
+    - type: command
+      description: Allow agents to auto-invoke unslop and TypeScript guide
+      bash: ./scripts/patch-skills.sh
+      timeoutSec: 10
diff --git a/docs/tooling.md b/docs/tooling.md
index 5d809da9..02ccf86e 100644
--- a/docs/tooling.md
+++ b/docs/tooling.md
@@ -105,3 +105,9 @@ skill-bundle packages such as `reatom/reatom`).
 Updating: `mise run skills:update` bumps every `apm.yml` ref to the latest
 upstream tag/commit and refreshes `apm.lock.yaml` hashes. CI runs the same
 command weekly (`skills-update.yml`) and opens a PR when anything moved.
+
+Two fetched skills (unslop, typescript-best-practices) have
+`disable-model-invocation: true` upstream; `scripts/patch-skills.sh` strips it
+via an `apm.yml` post-install lifecycle hook so agents can auto-apply them.
+Fresh clones must run `apm lifecycle trust` once to enable the hook (apm will
+warn and skip it until then).
diff --git a/scripts/patch-skills.sh b/scripts/patch-skills.sh
new file mode 100755
index 00000000..9e8f7b3f
--- /dev/null
+++ b/scripts/patch-skills.sh
@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Re-applied after every `apm install` (see lifecycle in apm.yml).
+# Strips `disable-model-invocation` so agents can apply these skills
+# automatically, matching the machine-wide copies.
+set -euo pipefail
+for skill in unslop typescript-best-practices; do
+  f=".agents/skills/$skill/SKILL.md"
+  [ -f "$f" ] && sed -i '/^disable-model-invocation:/d' "$f"
+done

From 883868c830be5c1d9407da4500e2315ad1b93761 Mon Sep 17 00:00:00 2001
From: Aleksei Gurianov <gurianov@gmail.com>
Date: Sat, 3 Oct 2026 20:07:41 +0000
Subject: [PATCH 07/11] chore(skills): check lockfile and warn about upstream
 updates

---
 .config/hk.pkl                      |  5 +++
 .github/workflows/skills-update.yml | 56 -----------------------------
 scripts/check-skills-lock.sh        | 22 ++++++++++++
 3 files changed, 27 insertions(+), 56 deletions(-)
 delete mode 100644 .github/workflows/skills-update.yml
 create mode 100755 scripts/check-skills-lock.sh

diff --git a/.config/hk.pkl b/.config/hk.pkl
index da93a0df..ce88cc57 100644
--- a/.config/hk.pkl
+++ b/.config/hk.pkl
@@ -34,9 +34,14 @@ local fastSteps = new Mapping<String, Step> {
   ["typecheck"] = typecheck
 }
 
+local skillsLock = new Step {
+  check = "scripts/check-skills-lock.sh"
+}
+
 local checkSteps = new Mapping<String, Step> {
   ...fastSteps
   ["fallow"] = fallow
+  ["skills-lock"] = skillsLock
 }
 
 hooks {
diff --git a/.github/workflows/skills-update.yml b/.github/workflows/skills-update.yml
deleted file mode 100644
index 033a428a..00000000
--- a/.github/workflows/skills-update.yml
+++ /dev/null
@@ -1,56 +0,0 @@
-name: Skills update
-
-on:
-  schedule:
-    - cron: "0 6 * * 1" # weekly, Monday 06:00 UTC
-  workflow_dispatch:
-
-concurrency:
-  group: skills-update
-  cancel-in-progress: false
-
-jobs:
-  update:
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    permissions:
-      contents: write
-      pull-requests: write
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Setup mise
-        uses: jdx/mise-action@1648a7812b9aeae629881980618f079932869151 # v4.0.1
-        with:
-          install: true
-          cache: true
-
-      - name: Config mise
-        run: mise settings experimental=true
-
-      - name: Update skill dependencies
-        run: mise run --no-deps skills:update
-
-      - name: Open update PR
-        id: pr
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          if git diff --quiet apm.yml apm.lock.yaml; then
-            echo "updated=false" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          branch="chore/skills-update"
-          git checkout -b "$branch"
-          git commit -am "chore: update agent skill dependencies"
-          git push origin "$branch" --force
-          gh pr list --head "$branch" --state open --json number --jq '.[0].number' | xargs -r -I{} gh pr merge {} --auto --squash || true
-          gh pr create \
-            --head "$branch" \
-            --title "chore: update agent skill dependencies" \
-            --body "Automated bump of apm.yml skill refs and apm.lock.yaml hashes via \`mise run skills:update\`."
-          echo "updated=true" >> "$GITHUB_OUTPUT"
diff --git a/scripts/check-skills-lock.sh b/scripts/check-skills-lock.sh
new file mode 100755
index 00000000..38b54cc4
--- /dev/null
+++ b/scripts/check-skills-lock.sh
@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# hk check: keep apm.lock.yaml in sync with apm.yml, and surface
+# upstream skill releases. Network required (resolves git refs).
+set -euo pipefail
+
+apm install --only apm >/dev/null
+
+if ! git diff --exit-code --quiet -- apm.yml apm.lock.yaml; then
+  echo "✗ agent skill manifest/lockfile out of sync —" >&2
+  echo "  run 'mise deps install skills' (or 'mise run skills:update') and commit the result:" >&2
+  git diff --stat -- apm.yml apm.lock.yaml >&2
+  exit 1
+fi
+
+# Warn-only: newer upstream tags should not block commits, but should be seen.
+if ! out="$(apm outdated 2>/dev/null)"; then
+  :
+fi
+if ! printf '%s' "$out" | grep -q "up-to-date"; then
+  echo "⚠ outdated agent skills — consider 'mise run skills:update':" >&2
+  printf '%s\n' "$out" | sed 's/^/  /' >&2
+fi

From fcac228cfda802f0d7e45015c0dfa482280b2bd9 Mon Sep 17 00:00:00 2001
From: Aleksei Gurianov <gurianov@gmail.com>
Date: Sat, 3 Oct 2026 20:07:59 +0000
Subject: [PATCH 08/11] refactor: enforce skill lockfile sync via hk instead of
 cron

Replace the weekly skills-update workflow with a hk 'skills-lock' check
(scripts/check-skills-lock.sh): fails when apm.yml and apm.lock.yaml
drift, warns on outdated upstream refs. 'mise run skills:update' stays
for manual bumps.
---
 apm.lock.yaml   | 32 ++++++++++++++++++++++----------
 docs/tooling.md |  7 ++++---
 2 files changed, 26 insertions(+), 13 deletions(-)

diff --git a/apm.lock.yaml b/apm.lock.yaml
index 87c91bb4..724be0fe 100644
--- a/apm.lock.yaml
+++ b/apm.lock.yaml
@@ -54,7 +54,6 @@ dependencies:
   version: unknown
   package_type: skill_bundle
   deployed_files:
-  - .agents/skills/reatom
   - .agents/skills/reatom-async
   - .agents/skills/reatom-async/REFERENCE.md
   - .agents/skills/reatom-async/SKILL.md
@@ -63,17 +62,30 @@ dependencies:
   - .agents/skills/reatom-jsx/SKILL.md
   - .agents/skills/reatom-review
   - .agents/skills/reatom-review/SKILL.md
-  - .agents/skills/reatom/REFERENCE.md
-  - .agents/skills/reatom/SKILL.md
   deployed_file_hashes:
     .agents/skills/reatom-async/REFERENCE.md: sha256:8cdbdd44a17ec47d4ab4ef36186d502c838517df020c6c14044733d188476951
     .agents/skills/reatom-async/SKILL.md: sha256:a6acfcc8886475923b93e280564193fbfb97be2385df65c758b1d1eec2c7505d
     .agents/skills/reatom-jsx/REFERENCE.md: sha256:55f87fcefed94fd6b63e5ebfd11dd4c6aac1f7fd61b06d73cca25f212306401c
     .agents/skills/reatom-jsx/SKILL.md: sha256:e26740b0cc7a3f1ddd0556e0bde67c27381bd0ae50a25619d603fe2a2873a6c2
     .agents/skills/reatom-review/SKILL.md: sha256:219e3e15521b23d5e88629461c6891fdf95b0b01fbe94620939a6040fa5c6520
+  content_hash: sha256:ac7b61894281e986ec77f58dfe6bbeef9bb12602a3c4e461769303c42d336b29
+- repo_url: reatom/reatom
+  name: reatom
+  host: github.com
+  resolved_commit: b48778e3bf3a80d85b176157b094c2470d0ab86e
+  resolved_ref: v1001
+  version: unknown
+  virtual_path: skills/reatom
+  is_virtual: true
+  package_type: claude_skill
+  deployed_files:
+  - .agents/skills/reatom
+  - .agents/skills/reatom/REFERENCE.md
+  - .agents/skills/reatom/SKILL.md
+  deployed_file_hashes:
     .agents/skills/reatom/REFERENCE.md: sha256:8dd96cc5bfb697a1848377f98a8a227901cc4144b767293c609822e8191b1b69
     .agents/skills/reatom/SKILL.md: sha256:2954dab61ae3495ade98ea222164af4e20ae8973c1f0fdcf2875708e78c2da27
-  content_hash: sha256:ac7b61894281e986ec77f58dfe6bbeef9bb12602a3c4e461769303c42d336b29
+  content_hash: sha256:de9586017eddbb781a9fdf5233636c2305892776363fa5d4e12517bea6ba82b4
 deployments:
 - kind: project-relative
   target: agent-skills
@@ -99,8 +111,8 @@ deployments:
   runtime: null
   scope: project
   owners:
-  - reatom/reatom
-  active_owner: reatom/reatom
+  - reatom/reatom/skills/reatom
+  active_owner: reatom/reatom/skills/reatom
   content_hash: null
 - kind: project-relative
   target: agent-skills
@@ -180,8 +192,8 @@ deployments:
   runtime: null
   scope: project
   owners:
-  - reatom/reatom
-  active_owner: reatom/reatom
+  - reatom/reatom/skills/reatom
+  active_owner: reatom/reatom/skills/reatom
   content_hash: sha256:8dd96cc5bfb697a1848377f98a8a227901cc4144b767293c609822e8191b1b69
 - kind: project-relative
   target: agent-skills
@@ -189,8 +201,8 @@ deployments:
   runtime: null
   scope: project
   owners:
-  - reatom/reatom
-  active_owner: reatom/reatom
+  - reatom/reatom/skills/reatom
+  active_owner: reatom/reatom/skills/reatom
   content_hash: sha256:2954dab61ae3495ade98ea222164af4e20ae8973c1f0fdcf2875708e78c2da27
 - kind: project-relative
   target: agent-skills
diff --git a/docs/tooling.md b/docs/tooling.md
index 02ccf86e..82e91dbe 100644
--- a/docs/tooling.md
+++ b/docs/tooling.md
@@ -102,9 +102,10 @@ mise deps --explain skills # inspect the freshness decision
 The `apm` CLI is pinned in `_config.toml` (0.33.0+ is required to install
 skill-bundle packages such as `reatom/reatom`).
 
-Updating: `mise run skills:update` bumps every `apm.yml` ref to the latest
-upstream tag/commit and refreshes `apm.lock.yaml` hashes. CI runs the same
-command weekly (`skills-update.yml`) and opens a PR when anything moved.
+Sync: the hk `skills-lock` check (runs in `hk check` / pre-push and CI) fails
+when `apm.yml` and `apm.lock.yaml` drift apart, and warns when upstream skill
+refs are outdated. Update with `mise deps install skills` (sync only) or
+`mise run skills:update` (bump refs to latest upstream), then commit.
 
 Two fetched skills (unslop, typescript-best-practices) have
 `disable-model-invocation: true` upstream; `scripts/patch-skills.sh` strips it

From d15a37861b80e401f135ac8de39c723b26499c09 Mon Sep 17 00:00:00 2001
From: Aleksei Gurianov <gurianov@gmail.com>
Date: Sat, 3 Oct 2026 20:29:42 +0000
Subject: [PATCH 09/11] feat: couple skill deps to npm package versions

scripts/sync-skills.sh syncs apm.yml refs from node_modules: kahraman
tracks its exact release tag; reatom re-resolves the v1001 branch head
when @reatom/core's installed version moves (recorded in
.config/skill-deps.txt). Wired into the mise deps skills provider and
the hk skills-lock step (check/fix).
---
 .config/hk.pkl                   |  3 +-
 .config/mise/conf.d/_config.toml |  4 +-
 .config/skill-deps.txt           |  1 +
 apm.lock.yaml                    | 32 ++++---------
 scripts/check-skills-lock.sh     | 22 ---------
 scripts/sync-skills.sh           | 81 ++++++++++++++++++++++++++++++++
 6 files changed, 96 insertions(+), 47 deletions(-)
 create mode 100644 .config/skill-deps.txt
 delete mode 100755 scripts/check-skills-lock.sh
 create mode 100755 scripts/sync-skills.sh

diff --git a/.config/hk.pkl b/.config/hk.pkl
index ce88cc57..064581b1 100644
--- a/.config/hk.pkl
+++ b/.config/hk.pkl
@@ -35,7 +35,8 @@ local fastSteps = new Mapping<String, Step> {
 }
 
 local skillsLock = new Step {
-  check = "scripts/check-skills-lock.sh"
+  check = "scripts/sync-skills.sh --check"
+  fix = "scripts/sync-skills.sh"
 }
 
 local checkSteps = new Mapping<String, Step> {
diff --git a/.config/mise/conf.d/_config.toml b/.config/mise/conf.d/_config.toml
index a69ca4e1..3aa9d60d 100644
--- a/.config/mise/conf.d/_config.toml
+++ b/.config/mise/conf.d/_config.toml
@@ -29,6 +29,6 @@ mr = "mise run"
 # Agent skills materialized by APM (see apm.yml); output is gitignored.
 [deps.skills]
 auto = true
-sources = ["apm.yml"]
+sources = ["apm.yml", "pnpm-lock.yaml", "apps/*/package.json", "packages/*/package.json", "site/package.json"]
 outputs = [".agents/skills"]
-run = "apm install --only apm"
+run = "scripts/sync-skills.sh"
diff --git a/.config/skill-deps.txt b/.config/skill-deps.txt
new file mode 100644
index 00000000..2167b5d7
--- /dev/null
+++ b/.config/skill-deps.txt
@@ -0,0 +1 @@
+@reatom/core=1001.3.0
diff --git a/apm.lock.yaml b/apm.lock.yaml
index 724be0fe..87c91bb4 100644
--- a/apm.lock.yaml
+++ b/apm.lock.yaml
@@ -54,6 +54,7 @@ dependencies:
   version: unknown
   package_type: skill_bundle
   deployed_files:
+  - .agents/skills/reatom
   - .agents/skills/reatom-async
   - .agents/skills/reatom-async/REFERENCE.md
   - .agents/skills/reatom-async/SKILL.md
@@ -62,30 +63,17 @@ dependencies:
   - .agents/skills/reatom-jsx/SKILL.md
   - .agents/skills/reatom-review
   - .agents/skills/reatom-review/SKILL.md
+  - .agents/skills/reatom/REFERENCE.md
+  - .agents/skills/reatom/SKILL.md
   deployed_file_hashes:
     .agents/skills/reatom-async/REFERENCE.md: sha256:8cdbdd44a17ec47d4ab4ef36186d502c838517df020c6c14044733d188476951
     .agents/skills/reatom-async/SKILL.md: sha256:a6acfcc8886475923b93e280564193fbfb97be2385df65c758b1d1eec2c7505d
     .agents/skills/reatom-jsx/REFERENCE.md: sha256:55f87fcefed94fd6b63e5ebfd11dd4c6aac1f7fd61b06d73cca25f212306401c
     .agents/skills/reatom-jsx/SKILL.md: sha256:e26740b0cc7a3f1ddd0556e0bde67c27381bd0ae50a25619d603fe2a2873a6c2
     .agents/skills/reatom-review/SKILL.md: sha256:219e3e15521b23d5e88629461c6891fdf95b0b01fbe94620939a6040fa5c6520
-  content_hash: sha256:ac7b61894281e986ec77f58dfe6bbeef9bb12602a3c4e461769303c42d336b29
-- repo_url: reatom/reatom
-  name: reatom
-  host: github.com
-  resolved_commit: b48778e3bf3a80d85b176157b094c2470d0ab86e
-  resolved_ref: v1001
-  version: unknown
-  virtual_path: skills/reatom
-  is_virtual: true
-  package_type: claude_skill
-  deployed_files:
-  - .agents/skills/reatom
-  - .agents/skills/reatom/REFERENCE.md
-  - .agents/skills/reatom/SKILL.md
-  deployed_file_hashes:
     .agents/skills/reatom/REFERENCE.md: sha256:8dd96cc5bfb697a1848377f98a8a227901cc4144b767293c609822e8191b1b69
     .agents/skills/reatom/SKILL.md: sha256:2954dab61ae3495ade98ea222164af4e20ae8973c1f0fdcf2875708e78c2da27
-  content_hash: sha256:de9586017eddbb781a9fdf5233636c2305892776363fa5d4e12517bea6ba82b4
+  content_hash: sha256:ac7b61894281e986ec77f58dfe6bbeef9bb12602a3c4e461769303c42d336b29
 deployments:
 - kind: project-relative
   target: agent-skills
@@ -111,8 +99,8 @@ deployments:
   runtime: null
   scope: project
   owners:
-  - reatom/reatom/skills/reatom
-  active_owner: reatom/reatom/skills/reatom
+  - reatom/reatom
+  active_owner: reatom/reatom
   content_hash: null
 - kind: project-relative
   target: agent-skills
@@ -192,8 +180,8 @@ deployments:
   runtime: null
   scope: project
   owners:
-  - reatom/reatom/skills/reatom
-  active_owner: reatom/reatom/skills/reatom
+  - reatom/reatom
+  active_owner: reatom/reatom
   content_hash: sha256:8dd96cc5bfb697a1848377f98a8a227901cc4144b767293c609822e8191b1b69
 - kind: project-relative
   target: agent-skills
@@ -201,8 +189,8 @@ deployments:
   runtime: null
   scope: project
   owners:
-  - reatom/reatom/skills/reatom
-  active_owner: reatom/reatom/skills/reatom
+  - reatom/reatom
+  active_owner: reatom/reatom
   content_hash: sha256:2954dab61ae3495ade98ea222164af4e20ae8973c1f0fdcf2875708e78c2da27
 - kind: project-relative
   target: agent-skills
diff --git a/scripts/check-skills-lock.sh b/scripts/check-skills-lock.sh
deleted file mode 100755
index 38b54cc4..00000000
--- a/scripts/check-skills-lock.sh
+++ /dev/null
@@ -1,22 +0,0 @@
-#!/usr/bin/env bash
-# hk check: keep apm.lock.yaml in sync with apm.yml, and surface
-# upstream skill releases. Network required (resolves git refs).
-set -euo pipefail
-
-apm install --only apm >/dev/null
-
-if ! git diff --exit-code --quiet -- apm.yml apm.lock.yaml; then
-  echo "✗ agent skill manifest/lockfile out of sync —" >&2
-  echo "  run 'mise deps install skills' (or 'mise run skills:update') and commit the result:" >&2
-  git diff --stat -- apm.yml apm.lock.yaml >&2
-  exit 1
-fi
-
-# Warn-only: newer upstream tags should not block commits, but should be seen.
-if ! out="$(apm outdated 2>/dev/null)"; then
-  :
-fi
-if ! printf '%s' "$out" | grep -q "up-to-date"; then
-  echo "⚠ outdated agent skills — consider 'mise run skills:update':" >&2
-  printf '%s\n' "$out" | sed 's/^/  /' >&2
-fi
diff --git a/scripts/sync-skills.sh b/scripts/sync-skills.sh
new file mode 100755
index 00000000..c245419a
--- /dev/null
+++ b/scripts/sync-skills.sh
@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# Couple agent-skill deps in apm.yml to the npm packages that ship them.
+#
+#   kahraman      -> apphane-dev/kahraman#v<version>  (release tags match npm)
+#   @reatom/core  -> reatom/reatom#v1001              (no per-release tags; the
+#                     lockfile pins the branch-head commit and the recorded npm
+#                     version in .config/skill-deps.txt forces a re-resolve
+#                     whenever the installed npm version moves)
+#
+# fix mode (default): rewrite refs from node_modules, then `apm install`.
+# check mode (--check): fail if refs would change or the lockfile is stale.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+STATE=".config/skill-deps.txt"
+
+MODE="${1:-fix}"
+changed=""
+
+require_version() { # <pkg>
+	node -p "require('./node_modules/$1/package.json').version" 2>/dev/null ||
+		{ echo "✗ $1 not installed — run 'nub install' first" >&2; exit 1; }
+}
+
+fail_check() {
+	echo "✗ $* — run 'scripts/sync-skills.sh' (or 'mise deps install skills') and commit" >&2
+	exit 1
+}
+
+sync_tag() { # <pkg> <repo-prefix>
+	local pkg="$1" prefix="$2" ver ref
+	ver="$(require_version "$pkg")"
+	ref="${prefix}#v${ver}"
+	if ! grep -qF "$ref" apm.yml; then
+		[[ "$MODE" == "--check" ]] &&
+			fail_check "$pkg@$ver installed but apm.yml pins $(grep -oF "${prefix}#v[0-9A-Za-z._-]*" apm.yml || echo 'nothing')"
+		sed -i "s|${prefix}#v[0-9A-Za-z._-]*|${ref}|" apm.yml
+		changed="$changed $pkg"
+	fi
+}
+
+sync_branch() { # <pkg> <repo-prefix> <branch>
+	local pkg="$1" prefix="$2" branch="$3" ver recorded
+	ver="$(require_version "$pkg")"
+	recorded=""
+	if [ -f "$STATE" ]; then
+		recorded="$(sed -n "s|^${pkg}=||p" "$STATE" | tail -1)"
+	fi
+	if [[ "$recorded" != "$ver" ]]; then
+		[[ "$MODE" == "--check" ]] &&
+			fail_check "$pkg@$ver installed but apm.yml was resolved for ${recorded:-<unknown>}"
+			sed -i "s|${prefix}#[0-9A-Za-z._-]*|${prefix}#${branch}|" apm.yml
+		if grep -q "^${pkg}=" "$STATE" 2>/dev/null; then
+			sed -i "s|^${pkg}=.*|${pkg}=${ver}|" "$STATE"
+		else
+			echo "${pkg}=${ver}" >> "$STATE"
+		fi
+		changed="$changed $pkg"
+	fi
+}
+
+sync_tag kahraman apphane-dev/kahraman
+sync_branch @reatom/core reatom/reatom v1001
+
+if [[ "$MODE" == "--check" ]]; then
+	if ! git diff --exit-code --quiet -- apm.yml apm.lock.yaml; then
+		fail_check "uncommitted changes in apm.yml/apm.lock.yaml"
+	fi
+	hold="$(mktemp)"
+	cp apm.lock.yaml "$hold"
+	apm install --only apm >/dev/null
+	if ! diff -q "$hold" apm.lock.yaml >/dev/null; then
+		echo "✗ lockfile out of sync with apm.yml — re-materialized in the working tree; commit the changes" >&2
+		git diff --stat -- apm.lock.yaml >&2
+		exit 1
+	fi
+	rm -f "$hold"
+	exit 0
+fi
+
+[[ -n "$changed" ]] && echo "skill deps synced from npm:$changed"
+apm install --only apm

From f553c5d7bfab6af8a9ee76aa80889a09ca502a48 Mon Sep 17 00:00:00 2001
From: Aleksei Gurianov <gurianov@gmail.com>
Date: Sat, 3 Oct 2026 20:30:35 +0000
Subject: [PATCH 10/11] docs: describe npm-coupled skill dep sync

---
 docs/tooling.md | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/docs/tooling.md b/docs/tooling.md
index 82e91dbe..3ad405ef 100644
--- a/docs/tooling.md
+++ b/docs/tooling.md
@@ -102,10 +102,14 @@ mise deps --explain skills # inspect the freshness decision
 The `apm` CLI is pinned in `_config.toml` (0.33.0+ is required to install
 skill-bundle packages such as `reatom/reatom`).
 
-Sync: the hk `skills-lock` check (runs in `hk check` / pre-push and CI) fails
-when `apm.yml` and `apm.lock.yaml` drift apart, and warns when upstream skill
-refs are outdated. Update with `mise deps install skills` (sync only) or
-`mise run skills:update` (bump refs to latest upstream), then commit.
+Skill deps are coupled to the npm packages that ship them:
+`scripts/sync-skills.sh` syncs `apm.yml` refs from the installed
+`node_modules` versions (kahraman tracks its exact release tag; reatom
+re-resolves the v1001 branch head when `@reatom/core` moves, recorded in
+`.config/skill-deps.txt`). It runs automatically from the mise `skills`
+dependency provider whenever package manifests or the lockfile change, and the
+hk `skills-lock` check (in `hk check` / pre-push and CI) fails on drift.
+`mise run skills:update` still bumps refs to the latest upstream tags manually.
 
 Two fetched skills (unslop, typescript-best-practices) have
 `disable-model-invocation: true` upstream; `scripts/patch-skills.sh` strips it

From bff86134a3c8461d35c9fc9fbcb8251682aca3a4 Mon Sep 17 00:00:00 2001
From: Aleksei Gurianov <gurianov@gmail.com>
Date: Sat, 3 Oct 2026 21:07:03 +0000
Subject: [PATCH 11/11] fix(ci): invalidate skills dep on apm.lock.yaml and
 enforce lock check in CI

The skills dependency provider ignored apm.lock.yaml, so a checkout or
update that changed only the lock left .agents/skills stale even though
the pinned commits and hashes moved; include it in sources.

The docs claimed the skills-lock check runs in CI, but 'mise run ci'
never invoked hk check, so nothing enforced it there; wire the check
into the ci task as lint:skills-lock.
---
 .config/mise/conf.d/_config.toml       | 2 +-
 .config/mise/conf.d/tasks-quality.toml | 5 +++++
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/.config/mise/conf.d/_config.toml b/.config/mise/conf.d/_config.toml
index 3aa9d60d..b6634f4a 100644
--- a/.config/mise/conf.d/_config.toml
+++ b/.config/mise/conf.d/_config.toml
@@ -29,6 +29,6 @@ mr = "mise run"
 # Agent skills materialized by APM (see apm.yml); output is gitignored.
 [deps.skills]
 auto = true
-sources = ["apm.yml", "pnpm-lock.yaml", "apps/*/package.json", "packages/*/package.json", "site/package.json"]
+sources = ["apm.yml", "apm.lock.yaml", "pnpm-lock.yaml", "apps/*/package.json", "packages/*/package.json", "site/package.json"]
 outputs = [".agents/skills"]
 run = "scripts/sync-skills.sh"
diff --git a/.config/mise/conf.d/tasks-quality.toml b/.config/mise/conf.d/tasks-quality.toml
index ff33fff7..088cb2f4 100644
--- a/.config/mise/conf.d/tasks-quality.toml
+++ b/.config/mise/conf.d/tasks-quality.toml
@@ -47,6 +47,10 @@ description = "Type check all TypeScript projects"
 alias = "tc"
 run = ["mise run //apps/demo:typecheck", "mise run //packages/create-karkas:typecheck"]
 
+[tasks."lint:skills-lock"]
+description = "Check APM skill refs and lockfile are in sync"
+run = "scripts/sync-skills.sh --check"
+
 [tasks."lint:steiger"]
 description = "Check demo FSD architecture with steiger"
 run = "mise run //apps/demo:lint:steiger"
@@ -100,6 +104,7 @@ env = { VITE_CONNECT_LOGGER = "false" }
 run = [
 	{ task = "prepare" },
 	{ task = "format:check" },
+	{ task = "lint:skills-lock" },
 	{ task = "lint" },
 	{ task = "test:ci" },
 	{ tasks = ["typecheck", "lint:steiger", "lint:fallow"] },