Clarify dev symlink source boundaries

Author: Jake Fitzgerald

.claude-plugin/marketplace.json

@@ -7,13 +7,13 @@
     "description": "CAD, robotics, fabrication, and local review plugins."
   },
   "description": "CAD, robotics, fabrication, and local review plugins.",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "plugins": [
     {
       "name": "cad",
       "source": "./plugins/cad",
       "description": "CAD, robotics, fabrication, and local review skills.",
-      "version": "0.1.14",
+      "version": "0.1.15",
       "author": {
         "name": "earthtojake"
       },

AGENTS.md

@@ -59,7 +59,7 @@ product and `models/` as the shared fixture/artifact area.
 - Keep release versioning in lockstep: the git tag, plugin manifests and
   `plugins/*/VERSION`, package manifests/locks, Python `pyproject.toml` files,
   and any other repo-owned release version numbers should all match. The
-  current release version is `0.1.14`. Use `scripts/release/bump-version.sh`
+  current release version is `0.1.15`. Use `scripts/release/bump-version.sh`
   for version bumps as described in `COMMIT.md`.
 
 ## Environments

CONTRIBUTING.md

@@ -139,19 +139,40 @@ paths that CI and local checks expect.
 
 ## Source Boundaries
 
-Each skill must be self-contained and independent at runtime: it must not import
-or depend on code from another skill or from the repository root.
-
-Root source directories are canonical. `viewer/`, `packages/cadjs`, and
-`packages/cadpy` are the source of truth for CAD Viewer and shared CAD runtime
-behavior. Generated copies live under paths such as
-`skills/cad-viewer/scripts/viewer`, `skills/cad-viewer/scripts/packages/`,
-`skills/cad/scripts/packages/`, and snapshot runtimes. Do not patch those
-generated copies as the lasting fix.
-
-When changing skill behavior that uses `packages/cadjs`, `packages/cadpy`, or
-the cad-viewer generated runtime, edit the root source in `packages/*` or
-`viewer/*`, then rebuild the generated skill copies.
+Each skill must be self-contained and independent when it is installed from a
+production branch: it must not import or depend on code from another skill or
+from repository-root modules at runtime.
+
+The `dev` branch uses symlinks only as a checkout layout convenience. Those
+symlinks point generated-output paths back to the canonical sources so
+contributors can edit one copy of shared code. They do not relax the runtime
+self-containment rule: `scripts/build.sh --clean` must be able to replace the
+symlinks with real copies that still run without `skills/`, the repository
+root, or sibling skill directories on `sys.path`, `PYTHONPATH`, `NODE_PATH`, or
+similar lookup paths.
+
+Canonical source directories are:
+
+- `skills/*` for skill instructions, references, and skill-owned scripts.
+- `viewer/` for CAD Viewer app and server source.
+- `packages/cadjs`, `packages/cadpy`, and `packages/cadpy_metadata` for shared
+  runtime helpers that are copied into consuming skills for production.
+
+On `dev`, paths such as `skills/cad-viewer/scripts/viewer`,
+`skills/cad/scripts/packages/cadpy`, `skills/{urdf,srdf,sdf}/scripts/packages`,
+`viewer/packages/*`, and `plugins/cad/skills/*` should be symlinks. Treat those
+paths as generated-output aliases, not separate source roots. Edit the
+canonical source path instead.
+
+When you need to verify or create production outputs locally, run:
+
+```bash
+scripts/build.sh --clean
+scripts/build.sh --check
+```
+
+Do not hand-edit production copies as the lasting fix; change the canonical
+source, then rebuild.
 
 ## Branch Layouts
 

docs/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "cad-skills-docs",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "license": "MIT",
   "private": true,
   "scripts": {

docs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cadjs",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "private": true,
   "type": "module",
   "description": "Reusable CAD render/viewer runtime for docs, CAD Viewer, and generated snapshot browser assets.",

packages/cadjs/package-lock.json

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cadpy"
-version = "0.1.14"
+version = "0.1.15"
 description = "Shared STEP/GLB topology artifact generation runtime for CAD skills."
 requires-python = ">=3.11"
 dependencies = [

packages/cadjs/package.json

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cadpy-metadata"
-version = "0.1.14"
+version = "0.1.15"
 description = "Dependency-free metadata helpers for Python-generated CAD outputs."
 requires-python = ">=3.11"
 dependencies = []

packages/cadpy/pyproject.toml

@@ -6,7 +6,7 @@ development should link the source skills directly, as described in
 
 ## CAD
 
-`plugins/cad` is the first plugin package. It is versioned as `0.1.14`
+`plugins/cad` is the first plugin package. It is versioned as `0.1.15`
 and bundles every supported CAD Skills skill as a generated production copy
 of the canonical `skills/` directories.