@warp-drive/memory-alpha 0.0.0 → 5.9.0-alpha.32

package/logos/logo-yellow-slab.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1498" height="1047" fill="none" viewBox="0 0 1498 1047"><g filter="url(#a)"><path fill="url(#b)" d="M132 175.075C132 149.076 153.138 128 179.213 128H1318.23c26.08 0 47.22 21.076 47.22 47.075v688.85c0 25.999-21.14 47.075-47.22 47.075H179.213C153.138 911 132 889.924 132 863.925z"/><path fill="#201328" d="M1043.4 587.312c0-39.962 30.84-72.357 68.87-72.357h53.09c38.04 0 68.88-32.395 68.88-72.357v-92.651c0-39.962-30.84-72.358-68.88-72.358h-53.09c-38.01 0-68.82 32.351-68.87 72.275v92.734c0 39.962-30.83 72.357-68.869 72.357h-53.089c-38.036 0-68.871-32.395-68.871-72.357v-87.409c0-39.962-30.835-72.358-68.872-72.358h-51.654c-38.037 0-68.872 32.396-68.872 72.358v87.409c0 39.962-30.835 72.357-68.872 72.357h-53.088c-38.037 0-68.872-32.395-68.872-72.357v-92.652c0-39.961-30.835-72.357-68.872-72.357h-53.088c-38.037 0-68.872 32.396-68.872 72.357v92.652c0 39.962 30.835 72.357 68.872 72.357h53.088c38.037 0 68.872 32.395 68.872 72.357v101.741c0 39.962 30.835 72.358 68.872 72.358h53.088c38.037 0 68.872-32.396 68.872-72.358V587.312c0-39.962 30.835-72.357 68.872-72.357h51.654c38.037 0 68.872 32.395 68.872 72.357v101.741c0 39.962 30.835 72.358 68.871 72.358h53.089c38.039 0 68.869-32.396 68.869-72.358z"/></g><defs><linearGradient id="b" x1="748.724" x2="1167.5" y1="128" y2="1070.23" gradientUnits="userSpaceOnUse"><stop stop-color="#ffc474"/><stop offset="1" stop-color="#ff9809"/></linearGradient><filter id="a" width="1497.45" height="1047" x="0" y="0" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feColorMatrix in="SourceAlpha" result="hardAlpha" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"/><feOffset dy="4"/><feGaussianBlur stdDeviation="66"/><feComposite in2="hardAlpha" operator="out"/><feColorMatrix values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.1 0"/><feBlend in2="BackgroundImageFix" result="effect1_dropShadow_757_188"/><feColorMatrix in="SourceAlpha" result="hardAlpha" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"/><feOffset dy="4"/><feGaussianBlur stdDeviation="18"/><feComposite in2="hardAlpha" operator="out"/><feColorMatrix values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.25 0"/><feBlend in2="effect1_dropShadow_757_188" result="effect2_dropShadow_757_188"/><feColorMatrix in="SourceAlpha" result="hardAlpha" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"/><feOffset dy="4"/><feGaussianBlur stdDeviation="2"/><feComposite in2="hardAlpha" operator="out"/><feColorMatrix values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.25 0"/><feBlend in2="effect2_dropShadow_757_188" result="effect3_dropShadow_757_188"/><feBlend in="SourceGraphic" in2="effect3_dropShadow_757_188" result="shape"/></filter></defs></svg>

package/logos/word-mark-black.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="2081" height="200" fill="none" viewBox="0 0 2081 200"><path fill="#000" d="M2064.89 185.359c-15.57 5.16-31.15 8.846-46.72 11.058q-23.22 3.456-47.55 3.456c-20.73 0-39.21-2.212-55.43-6.635q-24.18-6.773-40.77-19.49c-11.06-8.478-19.49-18.844-25.3-31.1-5.8-12.256-8.71-26.125-8.71-41.606 0-14.375 2.91-27.69 8.71-39.947 5.9-12.348 14.19-23.037 24.88-32.068 10.78-9.123 23.78-16.218 38.98-21.286C1928.19 2.58 1945.14 0 1963.85 0c17.23 0 32.99 2.35 47.27 7.05 14.38 4.607 26.68 11.472 36.91 20.595q15.48 13.684 23.91 33.727c5.71 13.361 8.57 28.75 8.57 46.167v12.716h-187.16a48.3 48.3 0 0 0 8.16 16.449c3.87 4.976 9.08 9.215 15.62 12.717 6.54 3.501 14.56 6.22 24.05 8.155 9.58 1.935 21.01 2.903 34.28 2.903 9.4 0 18.61-.553 27.64-1.659 9.04-1.198 17.47-2.719 25.3-4.562q11.745-2.902 21.15-6.358c6.36-2.304 11.47-4.607 15.34-6.911zm-35.38-102.7c-.47-4.7-1.89-9.538-4.29-14.514-2.3-5.069-5.99-9.63-11.06-13.685s-11.7-7.371-19.9-9.952q-12.3-4.008-30.69-4.008-17.28 0-29.85 4.285-12.585 4.284-21.15 10.643c-5.62 4.239-10 8.8-13.13 13.684-3.14 4.884-5.16 9.4-6.09 13.546zm-284.63 112.099h-59.71l-96.06-189.92h57.22l69.11 142.924 68.98-142.924h57.22zm-238.29 0V4.838h51.28v189.92zm-32.63-146.932c-1.38-.461-3.4-1.06-6.08-1.797q-3.87-1.245-9.12-2.35-5.25-1.244-11.61-2.073c-4.15-.553-8.43-.83-12.86-.83-9.21 0-17.83 1.152-25.84 3.456q-11.895 3.317-22.26 8.984a125.3 125.3 0 0 0-19.35 12.717c-5.9 4.7-11.33 9.537-16.31 14.514v114.311h-51.28V4.838h51.28v30.824c6.17-4.608 12.49-9.03 18.94-13.27a163 163 0 0 1 20.32-11.472c7.09-3.318 14.56-5.944 22.39-7.88 7.83-2.026 16.12-3.04 24.88-3.04 3.32 0 6.68.184 10.09.553 3.5.276 6.86.645 10.09 1.106 3.32.46 6.4.967 9.26 1.52s5.35 1.106 7.46 1.659zM1263.71 99.66c0 12.164-1.33 22.991-4 32.483-2.68 9.399-6.45 17.6-11.34 24.604-4.79 7.003-10.6 12.947-17.42 17.831q-10.08 7.325-22.53 11.749c-8.29 2.948-17.23 5.114-26.81 6.496q-14.37 1.935-30 1.935h-120.53V4.838h120.26c10.41 0 20.41.691 29.99 2.073 9.59 1.29 18.52 3.41 26.82 6.359 8.38 2.948 15.99 6.865 22.8 11.749 6.82 4.791 12.63 10.735 17.42 17.83 4.89 7.004 8.66 15.205 11.34 24.605 2.67 9.399 4 20.134 4 32.206m-51.69 0q0-13.685-3.6-23.775c-2.3-6.727-6.08-12.256-11.33-16.587-5.16-4.423-11.93-7.694-20.32-9.814-8.38-2.211-18.61-3.317-30.68-3.317h-63.73v107.262h63.73c12.07 0 22.3-1.06 30.68-3.179 8.39-2.212 15.16-5.529 20.32-9.952 5.25-4.515 9.03-10.137 11.33-16.864q3.6-10.09 3.6-23.774M986.574 63.169q0 14.237-4.699 25.157-4.562 10.92-14.514 18.383-9.952 7.464-25.71 11.335-15.62 3.732-37.735 3.732h-85.285v72.982h-17.278V4.838h102.563q22.116 0 37.735 3.87 15.758 3.732 25.71 11.058t14.514 18.246q4.7 10.92 4.699 25.157m-17.831 0q0-13.546-4.561-21.84-4.423-8.294-13.823-12.716-9.26-4.562-23.636-6.082-14.237-1.52-33.865-1.52h-74.227v84.593h74.227q7.602 0 16.172.138 8.709 0 17.14-.83 8.432-.967 16.034-3.179 7.74-2.349 13.546-7.05 5.945-4.699 9.399-12.301 3.594-7.602 3.594-19.213M766.455 19.49q-4.01-1.244-11.197-2.627-7.049-1.52-18.245-1.52-15.481 0-29.166 3.87-13.545 3.732-25.295 10.229a126.3 126.3 0 0 0-21.563 15.205q-9.951 8.57-17.969 18.245v131.866h-17.278V4.838h17.278V43.54a166 166 0 0 1 20.043-17.555q10.92-8.017 22.945-13.684a125.8 125.8 0 0 1 25.157-8.985Q724.435 0 738.533 0q4.839 0 8.708.276 3.87.14 7.05.553 3.317.277 6.22.691 2.902.416 5.944.968zm-220.33 175.268v-21.01q-9.952 5.39-22.669 9.952-12.579 4.562-26.677 7.879-13.96 3.318-28.751 5.114-14.79 1.797-29.027 1.797-18.522 0-33.312-3.317-14.652-3.318-24.881-9.814-10.228-6.635-15.757-16.31-5.529-9.814-5.529-22.669 0-12.717 6.358-22.393 6.497-9.813 18.384-17.001 11.887-7.326 28.612-12.302 16.864-5.115 37.598-8.57 20.733-3.594 44.784-5.806 24.19-2.349 50.867-3.87V61.925q0-8.846-3.318-15.62-3.317-6.772-9.261-11.749-5.943-5.115-13.96-8.431-8.017-3.456-17.416-5.53-9.262-2.074-19.628-2.902a219 219 0 0 0-20.596-.968q-13.96 0-25.433 1.383-11.473 1.381-21.425 3.87-9.952 2.35-19.075 5.529a563 563 0 0 0-18.384 6.773V14.099q19.213-5.114 40.915-8.846 21.839-3.87 46.305-3.87 20.733 0 38.703 3.593 17.969 3.456 31.238 11.196 13.27 7.74 20.872 20.043 7.603 12.164 7.603 29.718v128.825zm0-102.977q-45.2 2.489-77.268 7.05-31.929 4.561-52.248 11.196-20.32 6.634-29.857 15.481-9.399 8.846-9.399 20.042 0 9.123 4.561 16.173 4.7 7.049 13.408 11.887 8.708 4.7 21.148 7.188 12.44 2.349 27.922 2.349 9.123 0 18.798-.967a276 276 0 0 0 19.49-2.903 319 319 0 0 0 19.075-4.423q9.4-2.627 17.693-5.667t15.066-6.497q6.912-3.455 11.611-7.049zM180.245 4.838l67.73 176.098L318.193 4.838h19.213l-76.438 189.92h-25.71L168.634 23.222l-66.486 171.536h-25.71L0 4.838h19.213l70.218 176.098L157.023 4.838z"/></svg>

package/logos/word-mark-white.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="2081" height="200" fill="none" viewBox="0 0 2081 200"><path fill="#fff" d="M2064.89 185.359c-15.57 5.16-31.15 8.846-46.72 11.058q-23.22 3.456-47.55 3.456c-20.73 0-39.21-2.212-55.43-6.635q-24.18-6.773-40.77-19.49c-11.06-8.478-19.49-18.844-25.3-31.1-5.8-12.256-8.71-26.125-8.71-41.606 0-14.375 2.91-27.69 8.71-39.947 5.9-12.348 14.19-23.037 24.88-32.068 10.78-9.123 23.78-16.218 38.98-21.286C1928.19 2.58 1945.14 0 1963.85 0c17.23 0 32.99 2.35 47.27 7.05 14.38 4.607 26.68 11.472 36.91 20.595q15.48 13.684 23.91 33.727c5.71 13.361 8.57 28.75 8.57 46.167v12.716h-187.16a48.3 48.3 0 0 0 8.16 16.449c3.87 4.976 9.08 9.215 15.62 12.717 6.54 3.501 14.56 6.22 24.05 8.155 9.58 1.935 21.01 2.903 34.28 2.903 9.4 0 18.61-.553 27.64-1.659 9.04-1.198 17.47-2.719 25.3-4.562q11.745-2.902 21.15-6.358c6.36-2.304 11.47-4.607 15.34-6.911zm-35.38-102.7c-.47-4.7-1.89-9.538-4.29-14.514-2.3-5.069-5.99-9.63-11.06-13.685s-11.7-7.371-19.9-9.952q-12.3-4.008-30.69-4.008-17.28 0-29.85 4.285-12.585 4.284-21.15 10.643c-5.62 4.239-10 8.8-13.13 13.684-3.14 4.884-5.16 9.4-6.09 13.546zm-284.63 112.099h-59.71l-96.06-189.92h57.22l69.11 142.924 68.98-142.924h57.22zm-238.29 0V4.838h51.28v189.92zm-32.63-146.932c-1.38-.461-3.4-1.06-6.08-1.797q-3.87-1.245-9.12-2.35-5.25-1.244-11.61-2.073c-4.15-.553-8.43-.83-12.86-.83-9.21 0-17.83 1.152-25.84 3.456q-11.895 3.317-22.26 8.984a125.3 125.3 0 0 0-19.35 12.717c-5.9 4.7-11.33 9.537-16.31 14.514v114.311h-51.28V4.838h51.28v30.824c6.17-4.608 12.49-9.03 18.94-13.27a163 163 0 0 1 20.32-11.472c7.09-3.318 14.56-5.944 22.39-7.88 7.83-2.026 16.12-3.04 24.88-3.04 3.32 0 6.68.184 10.09.553 3.5.276 6.86.645 10.09 1.106 3.32.46 6.4.967 9.26 1.52s5.35 1.106 7.46 1.659zM1263.71 99.66c0 12.164-1.33 22.991-4 32.483-2.68 9.399-6.45 17.6-11.34 24.604-4.79 7.003-10.6 12.947-17.42 17.831q-10.08 7.325-22.53 11.749c-8.29 2.948-17.23 5.114-26.81 6.496q-14.37 1.935-30 1.935h-120.53V4.838h120.26c10.41 0 20.41.691 29.99 2.073 9.59 1.29 18.52 3.41 26.82 6.359 8.38 2.948 15.99 6.865 22.8 11.749 6.82 4.791 12.63 10.735 17.42 17.83 4.89 7.004 8.66 15.205 11.34 24.605 2.67 9.399 4 20.134 4 32.206m-51.69 0q0-13.685-3.6-23.775c-2.3-6.727-6.08-12.256-11.33-16.587-5.16-4.423-11.93-7.694-20.32-9.814-8.38-2.211-18.61-3.317-30.68-3.317h-63.73v107.262h63.73c12.07 0 22.3-1.06 30.68-3.179 8.39-2.212 15.16-5.529 20.32-9.952 5.25-4.515 9.03-10.137 11.33-16.864q3.6-10.09 3.6-23.774M986.574 63.169q0 14.237-4.699 25.157-4.562 10.92-14.514 18.383-9.952 7.464-25.71 11.335-15.62 3.732-37.735 3.732h-85.285v72.982h-17.278V4.838h102.563q22.116 0 37.735 3.87 15.758 3.732 25.71 11.058t14.514 18.246q4.7 10.92 4.699 25.157m-17.831 0q0-13.546-4.561-21.84-4.423-8.294-13.823-12.716-9.26-4.562-23.636-6.082-14.237-1.52-33.865-1.52h-74.227v84.593h74.227q7.602 0 16.172.138 8.709 0 17.14-.83 8.432-.967 16.034-3.179 7.74-2.349 13.546-7.05 5.945-4.699 9.399-12.301 3.594-7.602 3.594-19.213M766.455 19.49q-4.01-1.244-11.197-2.627-7.049-1.52-18.245-1.52-15.481 0-29.166 3.87-13.545 3.732-25.295 10.229a126.3 126.3 0 0 0-21.563 15.205q-9.951 8.57-17.969 18.245v131.866h-17.278V4.838h17.278V43.54a166 166 0 0 1 20.043-17.555q10.92-8.017 22.945-13.684a125.8 125.8 0 0 1 25.157-8.985Q724.435 0 738.533 0q4.839 0 8.708.276 3.87.14 7.05.553 3.317.277 6.22.691 2.902.416 5.944.968zm-220.33 175.268v-21.01q-9.952 5.39-22.669 9.952-12.579 4.562-26.677 7.879-13.96 3.318-28.751 5.114-14.79 1.797-29.027 1.797-18.522 0-33.312-3.317-14.652-3.318-24.881-9.814-10.228-6.635-15.757-16.31-5.529-9.814-5.529-22.669 0-12.717 6.358-22.393 6.497-9.813 18.384-17.001 11.887-7.326 28.612-12.302 16.864-5.115 37.598-8.57 20.733-3.594 44.784-5.806 24.19-2.349 50.867-3.87V61.925q0-8.846-3.318-15.62-3.317-6.772-9.261-11.749-5.943-5.115-13.96-8.431-8.017-3.456-17.416-5.53-9.262-2.074-19.628-2.902a219 219 0 0 0-20.596-.968q-13.96 0-25.433 1.383-11.473 1.381-21.425 3.87-9.952 2.35-19.075 5.529a563 563 0 0 0-18.384 6.773V14.099q19.213-5.114 40.915-8.846 21.839-3.87 46.305-3.87 20.733 0 38.703 3.593 17.969 3.456 31.238 11.196 13.27 7.74 20.872 20.043 7.603 12.164 7.603 29.718v128.825zm0-102.977q-45.2 2.489-77.268 7.05-31.929 4.561-52.248 11.196-20.32 6.634-29.857 15.481-9.399 8.846-9.399 20.042 0 9.123 4.561 16.173 4.7 7.049 13.408 11.887 8.708 4.7 21.148 7.188 12.44 2.349 27.922 2.349 9.123 0 18.798-.967a276 276 0 0 0 19.49-2.903 319 319 0 0 0 19.075-4.423q9.4-2.627 17.693-5.667t15.066-6.497q6.912-3.455 11.611-7.049zM180.245 4.838l67.73 176.098L318.193 4.838h19.213l-76.438 189.92h-25.71L168.634 23.222l-66.486 171.536h-25.71L0 4.838h19.213l70.218 176.098L157.023 4.838z"/></svg>

package/package.json

@@ -1,12 +1,28 @@
 {
   "name": "@warp-drive/memory-alpha",
-  "version": "0.0.0",
-  "private": false,
-  "description": "Reserved placeholder for @warp-drive/memory-alpha, published ahead of its first real release from https://github.com/warp-drive-data/warp-drive.",
+  "version": "5.9.0-alpha.32",
+  "description": "WarpDrive knowledge packaged as plain markdown for AI coding agents (Claude Skills, MCP servers, Copilot/Cursor instruction files, etc.)",
   "license": "MIT",
+  "author": "Chris Thoburn <runspired@users.noreply.github.com>",
   "repository": {
     "type": "git",
     "url": "git+ssh://git@github.com:warp-drive-data/warp-drive.git",
     "directory": "warp-drive-packages/memory-alpha"
+  },
+  "homepage": "https://github.com/warp-drive-data/warp-drive",
+  "bugs": "https://github.com/warp-drive-data/warp-drive/issues",
+  "type": "module",
+  "files": [
+    "skills",
+    "README.md",
+    "LICENSE.md",
+    "logos"
+  ],
+  "exports": {
+    "./*": "./skills/*",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "sync": "echo \"syncing\""
   }
 }

package/skills/_meta.json

@@ -0,0 +1,8 @@
+{
+  "title": "Skills",
+  "items": ["schemas", "requests", "contributors"],
+  "webIndex": "overview",
+  "files": {
+    "index": { "draft": true }
+  }
+}

package/skills/contributors/_meta.json

@@ -0,0 +1,10 @@
+{
+  "title": "Contributors",
+  "items": ["start-in-a-fresh-worktree", "fix-at-the-source"],
+  "webIndex": "overview",
+  "files": {
+    "index": { "draft": true },
+    "start-in-a-fresh-worktree": { "title": "Start in a Fresh Worktree" },
+    "fix-at-the-source": { "title": "Fix at the Source" }
+  }
+}

package/skills/contributors/fix-at-the-source.md

@@ -0,0 +1,43 @@
+# Fix at the Source
+
+Use this skill whenever you're fixing a bug, adding a guard, or adding a fallback inside
+WarpDrive's internals (`Store`, cache, graph, reactive signals, record arrays). The question is
+never just "where do I stop the crash" — it's "where does 'x changed' fail to correctly produce
+'y updated', and what's the one place that should know it."
+
+## Steps
+
+1. Trace the bug back to its root cause: the place where a change to one piece of state should
+   have correctly propagated to another, and didn't. Fix there, not at the symptom's surface.
+   A patch at the surface only treats the one call site that happened to crash or misbehave —
+   every other consumer of the same broken invariant is still wrong.
+2. That root cause is usually also the cheapest place to check: the earliest point in the call
+   chain where the fact you need — "is there new data to sync," "did anything actually change" —
+   is already known or a single cheap check away (an `undefined` check, a reference comparison, a
+   boolean already on the object). Put the fix there, immediately in front of the work it's
+   guarding.
+3. Centralize the check at that one source instead of duplicating a defensive check at every
+   downstream consumer. Don't guard further upstream "just in case" (runs even when the expensive
+   work wouldn't have happened) or further downstream after the fact (too late, and easy to miss
+   a sibling call site that needs the same guard). One correct check at the source beats the same
+   defensive check copy-pasted in ten places.
+4. Don't reach for a wider fix (a new state field, a broader notification path, a refactor of how
+   staleness is tracked) when a narrow, local check at the source does the job. Save the bigger
+   change for when the narrow check turns out to be wrong somewhere else too.
+5. Treat a fallback (`?? []`, `|| defaultValue`) that only exists to stop a crash as a smell, not
+   a fix — it silently produces a plausible-looking wrong result instead of a loud one, and
+   doesn't restore the "x changed → y updated" correctness that was actually broken. Prefer a
+   guard that skips unnecessary work over a fallback that fabricates an input for it.
+
+## Example
+
+`ManyArrayManager#_syncArray` re-syncs a `ManyArray`'s membership whenever its relationship goes
+stale. A relationship can go stale from a `links`-only update with no new `data` (e.g. a save
+response that only changes a pagination link) — in that case there is no membership to sync at
+all. The root cause was that staleness alone doesn't imply new membership data exists; the fix
+was a single `rawValue.data !== undefined` check placed directly in front of the clear-and-refill,
+the one place that has the fact it needs. Not a `?? []` fallback (which would silently empty an
+already-populated array on an unrelated links-only change, papering over the symptom instead of
+the cause) and not a fix upstream in the graph layer (which would touch every consumer of
+relationship state to fix a bug specific to this one array-sync path, trading a narrow correct
+check for a wide speculative one).

package/skills/contributors/index.md

@@ -0,0 +1,18 @@
+# WarpDrive Contributors Skills — Agent Index
+
+You are an AI agent contributing to WarpDrive's own codebase (not consuming `@warp-drive/*`
+packages as a dependency in an app). Find the single row below that matches your task and read
+**only** that file. Do not read other skill files, do not list or read whole directories.
+
+| If you need to... | Read exactly |
+| --- | --- |
+| Begin any session or task in this repo — get a working copy to make changes in | `start-in-a-fresh-worktree.md` |
+| You're fixing a bug, adding a guard, or adding a fallback in WarpDrive's internals (`Store`, cache, graph, reactive signals, record arrays) | `fix-at-the-source.md` |
+
+The first row applies to **every** session, whatever the task — read it before anything else,
+then read the row matching your actual task.
+
+Each skill file is self-contained for its task and links out to any other skill file it
+genuinely depends on — follow a link only if you hit the specific case it describes.
+
+If nothing above matches, the skill you need doesn't exist yet in this category.

package/skills/contributors/overview.md

@@ -0,0 +1,11 @@
+# WarpDrive Contributor Skills
+
+Skills for contributing to WarpDrive's own codebase, not for consuming `@warp-drive/*` packages
+as a dependency in an app.
+
+| If you need to... | Go to |
+| --- | --- |
+| Begin any session or task in this repo — get a working copy to make changes in | [Start in a Fresh Worktree](/skills/contributors/start-in-a-fresh-worktree.md) |
+| Fix a bug, add a guard, or add a fallback in WarpDrive's internals (`Store`, cache, graph, reactive signals, record arrays) | [Fix at the Source](/skills/contributors/fix-at-the-source.md) |
+
+If nothing above matches, the skill you need doesn't exist yet in this category.

package/skills/contributors/start-in-a-fresh-worktree.md

@@ -0,0 +1,77 @@
+# Start In A Fresh Worktree
+
+Use this skill at the start of every session contributing to WarpDrive itself, before reading
+code or making any change. Each session gets its own `git worktree` branched from a freshly
+fetched `origin/main` — never the shared primary checkout, and never whatever commit that
+checkout's `HEAD` happens to be parked on.
+
+## Steps
+
+1. Don't work in the primary checkout, even for a "quick" one-file change. `pnpm install` in this
+   repo also builds every package and rewrites hardlinks into the `node_modules` of every other
+   package and test app that depends on it (see
+   [Setting Up The Project](/guides/contributing/setting-up-the-project.md)), so two sessions
+   installing or building in the same checkout clobber each other's build output — and the
+   failures show up later as stale or half-written `dist` content, not as an obvious conflict.
+2. Branch from a freshly fetched `origin/main`, not from the current `HEAD`. Any long-lived
+   checkout is usually sitting on an unrelated feature branch; branching off it silently folds
+   someone else's unmerged commits into your diff and your PR. `main` is also the branch PRs
+   target, so branching anywhere else guarantees an unnecessary rebase.
+
+   ```sh
+   git fetch origin main
+   git worktree add -b <branch-name> ../warp-drive-<topic> origin/main
+   ```
+3. Always make the worktree a **sibling** of the repo (`../warp-drive-<topic>`), never a directory
+   nested inside it. This is not a tidiness preference — Node's resolution algorithm searches
+   *upward* for `node_modules`, so a worktree at `<repo>/anything/my-worktree` silently resolves
+   any dependency or `bin` its own install hasn't provided from `<repo>/node_modules` — the
+   primary checkout's tree. Three properties of this repo turn that into a wrong answer rather
+   than an error: `pnpm-workspace.yaml` sets `hoist: false` and uses injected workspace packages
+   specifically to keep each test app's dep tree isolated, `pnpm install` hardlinks built output
+   into consumers' `node_modules`, and the packages lean on branded types. So a nested worktree
+   gets the other checkout's `dist`, mismatched versions, duplicate modules in a bundle, and
+   private-brand type errors that point nowhere near the cause. A sibling has no shared ancestor
+   holding a `node_modules`, so resolution can't cross over.
+
+   Nesting is also the *default* for Claude Code's own worktree mechanisms — `--worktree`,
+   `EnterWorktree`, and `Agent` with `isolation: "worktree"` all create under
+   `<repo>/.claude/worktrees/` and currently offer no way to relocate that. In this repo, don't use
+   them: create the sibling yourself with `git worktree add` as above. `.gitignore` covers
+   `.claude/worktrees/` so a nested one that slips in doesn't pollute `git status`, but that entry
+   is damage control, not permission.
+4. Install from the new worktree's root. `node_modules` is not shared between worktrees, so a
+   fresh worktree has no dependencies and no built packages at all until you install:
+
+   ```sh
+   cd ../warp-drive-<topic>
+   pnpm install
+   ```
+
+   Two setup steps are *not* per-worktree and don't need repeating: `mise install` fetches the
+   pinned `node`/`pnpm`/`bun` toolchain globally, and `@warp-drive/holodeck`'s
+   `ensure-cert` writes `holodeck-localhost.pem` into your home directory. Only run those if
+   you've never set the project up on this machine.
+5. Run every command from the worktree root for the rest of the session, and don't `cd` back into
+   the primary checkout to run tests, lint, or builds — that reintroduces exactly the
+   cross-session build clobbering the worktree exists to prevent.
+6. Remember that some git state is shared across all worktrees of a repo, not isolated by one.
+   The stash stack is global: a bare `git stash pop` can restore another session's work into your
+   tree, so set work aside with a temporary WIP commit instead, or use
+   `git stash push -u -m "<unique-tag>"` and `git stash apply <sha>` against the entry you can
+   identify by tag. Branch checkouts are also global — a branch already checked out in another
+   worktree cannot be checked out in yours.
+7. Clean up once the PR merges, so the next session's `git worktree list` stays readable:
+
+   ```sh
+   git worktree remove ../warp-drive-<topic>
+   git worktree prune
+   ```
+
+## Why "fresh" and "off main" are separate requirements
+
+They fail in different ways. Reusing an existing worktree gets you a dirty tree, stale
+`node_modules`, and leftover build output from unrelated work — a green local test run there tells
+you nothing about your change. Branching off the wrong commit gets you a *clean* worktree whose
+diff against `main` contains commits you never wrote; that one survives all local verification and
+only surfaces in review, as a PR touching files the task never mentioned.

package/skills/index.md

@@ -0,0 +1,17 @@
+# WarpDrive Skills — Agent Index
+
+You are an AI agent looking for WarpDrive knowledge. Find the single row below that matches
+your task and read **only** that file. Do not read other skill files, do not list or read whole
+directories, and do not read this package's `overview.md` — none of that is necessary to
+complete a task.
+
+| If you need to... | Read exactly |
+| --- | --- |
+| Define a resource's shape — fields, relationships, identity — for the `Store` | `schemas/define-a-resource-schema.md` |
+| Fetch or query remote data through the `Store` so it's cached and reactive | `requests/fetch-and-cache-data.md` |
+| You're contributing to WarpDrive itself, not just consuming it as a dependency | `contributors/index.md` |
+
+Each skill file is self-contained for its task and links out to any other skill file it
+genuinely depends on — follow a link only if you hit the specific case it describes.
+
+If nothing above matches, the skill you need doesn't exist yet in this package.

package/skills/overview.md

@@ -0,0 +1,27 @@
+# WarpDrive Agent Skills
+
+This section packages WarpDrive knowledge for AI coding agents — Claude, Copilot, Cursor, and
+similar tools — as small, focused, task-oriented skills.
+
+Each skill is a single markdown file describing one thing to accomplish with WarpDrive: defining
+a schema, making a request, handling a mutation, and so on. Skills are grouped into directories
+by topic, the same way the [Guides](/guides/index.md) are, and published as the
+[`@warp-drive/memory-alpha`](https://www.npmjs.com/package/@warp-drive/memory-alpha) npm
+package — named after the Federation's central archive of all recorded knowledge, minus the
+away-team incident that torched the original — so it can be installed into any project and
+consumed by an MCP server, a Claude Code skill, or adapted into tool-specific instruction files
+(Cursor rules, Copilot instructions, etc.).
+
+Find the row below that matches what you're doing, or browse the categories in the sidebar.
+
+| If you need to... | Go to |
+| --- | --- |
+| Define a resource's shape — fields, relationships, identity — for the `Store` | [Define a Resource Schema](/skills/schemas/define-a-resource-schema.md) |
+| Fetch or query remote data through the `Store` so it's cached and reactive | [Fetch and Cache Data](/skills/requests/fetch-and-cache-data.md) |
+| You're contributing to WarpDrive itself, not just consuming it as a dependency | [Contributor Skills](/skills/contributors/index.md) |
+
+This is the same routing table an AI agent uses to find a skill — it just links out to readable
+pages instead of naming files to read. If you're an AI agent rather than a human reader, don't
+start here — read the package's `skills/index.md` (or its
+[README](https://www.npmjs.com/package/@warp-drive/memory-alpha)) instead, which routes you
+directly to the one file you need without loading this page or any directory listing.

package/skills/requests/_meta.json

@@ -0,0 +1,7 @@
+{
+  "title": "Requests",
+  "items": ["fetch-and-cache-data"],
+  "files": {
+    "fetch-and-cache-data": { "title": "Fetch and Cache Data" }
+  }
+}

package/skills/requests/fetch-and-cache-data.md

@@ -0,0 +1,71 @@
+# Fetch and Cache Data
+
+Use this skill when you need to fetch remote data through the WarpDrive `Store` so that the
+result is cached, deduplicated, and reactively available to the rest of the app.
+
+## Steps
+
+1. Call `store.request(requestInfo)` with a plain request object (`url`, optional `method`,
+   `headers`, `body`).
+2. Await the result and read `.content` off of it.
+
+```ts
+const { content } = await store.request({ url: '/api/users' });
+```
+
+3. For a resource that already has a registered schema, prefer a builder over hand-writing the
+   request. `findRecord` from `@warp-drive/utilities/json-api` is the built-in builder for
+   fetching a single resource by type and id:
+
+```ts
+import { findRecord } from '@warp-drive/utilities/json-api';
+
+const { content } = await store.request(findRecord('user', userId));
+```
+
+4. To reuse a request shape, write your own builder — a plain function returning a request
+   object:
+
+```ts
+// builders/get-users.ts
+export function getUsers() {
+  return { url: '/api/users' };
+}
+
+// elsewhere
+import { getUsers } from '#/builders/get-users.ts';
+const { content } = await store.request(getUsers());
+```
+
+## In a component (reactive control flow)
+
+Prefer the `<Request />` component (Ember) or `useQuery`-style hooks (React) over manual
+`await` + local loading state — this gets automatic loading/error states and cleanup on
+unmount for free:
+
+```gts
+import { Request } from '@warp-drive/ember';
+import { findRecord } from '@warp-drive/utilities/json-api';
+
+<template>
+  <Request @query={{findRecord "user" @userId}}>
+    <:content as |result|>Hello {{result.data.name}}!</:content>
+    <:loading>Loading…</:loading>
+    <:error as |error state|>
+      <button {{on "click" state.retry}}>Try Again</button>
+    </:error>
+  </Request>
+</template>
+```
+
+## Notes
+
+- `store.request` works with any resource type, not just ones with schemas registered — for
+  unregistered types you get the raw response back rather than a reactive resource.
+- A request's schema-backed resource must be registered first — see
+  [Define a Resource Schema](/skills/schemas/define-a-resource-schema).
+
+## Related
+
+- Full guide: [Making Requests](/guides/the-manual/requests/index.md)
+- Related skill: [Define a Resource Schema](/skills/schemas/define-a-resource-schema)

package/skills/schemas/_meta.json

@@ -0,0 +1,7 @@
+{
+  "title": "Schemas",
+  "items": ["define-a-resource-schema"],
+  "files": {
+    "define-a-resource-schema": { "title": "Define a Resource Schema" }
+  }
+}

package/skills/schemas/define-a-resource-schema.md

@@ -0,0 +1,57 @@
+# Define a Resource Schema
+
+Use this skill when you need to teach a WarpDrive `Store` the shape of a resource type (e.g.
+`'user'`) — its fields, its relationships, and how they should be cached and reactively exposed.
+
+## Steps
+
+1. Pick a `ResourceType` string for the resource (e.g. `'user'`).
+2. Call `store.schema.registerResource` with a `ResourceSchema` describing:
+   - `identity` — how the resource's primary key is represented, typically `{ kind: '@id', name: 'id' }`.
+   - `legacy: true` — use `LegacyMode`, the current recommendation for both new and existing apps
+     (`PolarisMode` is still a preview and not yet recommended).
+   - `fields` — an array describing each attribute and relationship.
+
+```ts
+store.schema.registerResource({
+  type: 'user',
+  identity: { kind: '@id', name: 'id' },
+  legacy: true,
+  fields: [
+    { kind: 'field', name: 'firstName', sourceKey: 'first-name' },
+    { kind: 'field', name: 'lastName', sourceKey: 'last-name' },
+    { kind: 'field', name: 'lastSeen', sourceKey: 'last-seen', type: 'date-time' },
+    {
+      kind: 'resource',
+      name: 'bestFriend',
+      sourceKey: 'best-friend',
+      options: { async: false, inverse: null },
+    },
+    {
+      kind: 'collection',
+      name: 'pets',
+      options: { async: false, inverse: null, polymorphic: true },
+    },
+  ],
+});
+```
+
+## Field kinds
+
+- `field` — a plain attribute. Add `type` (e.g. `'date-time'`) to run the value through a
+  registered transform on read/write.
+- `resource` — a to-one relationship to another resource type.
+- `collection` — a to-many relationship to another resource type.
+- `sourceKey` lets the schema's field `name` (camelCase, used in app code) differ from the key
+  the field actually lives at in cached data (e.g. dasherized keys from a JSON:API response).
+
+## Notes
+
+- Schemas are plain JSON — they can be authored by hand, generated, or loaded from a remote
+  source at runtime.
+- Register schemas once, early, before any request that touches the resource type.
+
+## Related
+
+- Full guide: [Schemas](/guides/the-manual/schemas/index.md)
+- Related skill: [Fetch and Cache Data](/skills/requests/fetch-and-cache-data)

package/index.js

@@ -1,2 +0,0 @@
-// placeholder release, see README
-module.exports = {};