@syncmatters/script-api 1.0.21 → 1.0.22

package/docs/01-workspace-layout.md

@@ -3,8 +3,9 @@
 A workspace pulled by `sm` mirrors platform script files locally and adds editor tooling.
 
 ```
-files/              # script source (.mjs, .json, …) — EDIT and push via sm push
-meta/               # one *.meta.json sidecar per file under files/ — EDIT and push
+files/Scripts/      # integration scripts + sync logic (.mjs, .json, …) — EDIT and push via sm push
+files/Connectors/   # connector source, one folder per connector — EDIT and push
+meta/               # one *.meta.json sidecar per file under files/ (same sub-path) — EDIT and push
 syncs/<sync_uid>/   # sync.config.json — GENERATED read-only snapshots (sm pull sync)
 groups/<group_uid>/ # group.config.json — GENERATED read-only snapshots
 types/              # typed-connection .d.ts — GENERATED (sm types)
@@ -18,7 +19,9 @@ AGENTS.md           # CLI-generated agent guide (managed block + your notes belo
 
 | Path | Agent may edit? | `sm push`? |
 | --- | --- | --- |
-| `files/**` | Yes (when tasked) | Yes (with sidecar) |
+| `files/Scripts/**` | Yes (when tasked) | Yes (with sidecar) |
+| `files/Connectors/**` | Yes (connector work only) | Yes (with sidecar) |
+| any other top-level folder under `files/` (`Modules/`, `Services/`, …) | **No** — the platform rejects it | **No** |
 | `meta/**` | Yes | Yes (meta fields) |
 | `syncs/**/sync.config.json` | **No** | **No** |
 | `groups/**/group.config.json` | **No** | **No** |

package/docs/04-module-wiring-and-sidecars.md

@@ -28,17 +28,21 @@ The **entry** script's sidecar lists every file the platform must stage for that
 
 ```json
 "module_script_file_paths": [
-  "Services/AcmeSync/acme-filter.mjs",
-  "Services/AcmeSync/acme-utils.mjs"
+  "Scripts/AcmeSync/acme-filter.mjs",
+  "Scripts/AcmeSync/acme-utils.mjs"
 ]
 ```
 
+Paths are FullNames — the path under `files/` without the `files/` prefix. Script modules always
+start with `Scripts/`; only connector code lives under `Connectors/`. The platform rejects any
+other top-level folder.
+
 `sm push` maps paths to platform file ids from workspace state. Every referenced path must exist
 and be tracked — unresolved references block the wiring change for that file.
 
 ## Linking sync logic to a sync
 
-1. Push the module file(s) under `files/` with correct sidecars.
+1. Push the module file(s) under `files/Scripts/` with correct sidecars.
 2. In the **web UI**, open the sync configuration and attach the script file as custom logic
    (sets `script_file_id` on the platform).
 3. Locally, run `sm pull sync` and read `syncs/<sync_uid>/sync.config.json`:
@@ -53,7 +57,8 @@ not a push payload.
 
 A new file under `files/` is created on the platform only when:
 
-1. It has a `meta/` sidecar, and
-2. You `sm push` it.
+1. It sits under `files/Scripts/` (or `files/Connectors/<Name>/` for connector code),
+2. It has a `meta/` sidecar, and
+3. You `sm push` it.
 
 No sidecar → no push.

package/docs/06-cli-workflow-and-tokens.md

@@ -5,7 +5,8 @@
 ```
 sm pull                    # scripts + meta pins (+ syncs/groups when scoped)
 sm pull sync               # optional: refresh sync/group snapshots only
-→ edit files/ and meta/ only
+sm sync fields --source <conn>:<obj> --dest <conn>:<obj>   # both connections must resolve — stop and ask if one is missing
+→ edit files/Scripts/ and meta/Scripts/ only (files/Connectors/ for connector work)
 → sm validate
 → sm status / sm diff
 → sm push -m "describe change" --yes
@@ -13,8 +14,11 @@ sm pull sync               # optional: refresh sync/group snapshots only
 
 - **Scripts only:** `sm push` uploads changed files under `files/` (and meta sidecars). It does
   **not** upload `syncs/` or `groups/`.
-- **Sync config changes:** `changes/*.sync-changes.json` → `sm sync draft` → human review →
-  `sm sync push` (needs `syncs:write`). Agents push only on human instruction.
+- **Sync config changes:** confirm every `connection_uid` with `sm sync fields` first — if it
+  reports an unknown connection or object, stop and ask the human to create the connection,
+  select objects and refresh metadata; do not author mappings from connector tests, OpenAPI
+  specs, another workspace or memory. Then `changes/*.sync-changes.json` → `sm sync draft` →
+  human review → `sm sync push` (needs `syncs:write`). Agents push only on human instruction.
 - **Reading snapshots:** use `syncs/` and `groups/` for context before editing the wired module
   in `files/`.
 

package/docs/07-style-and-pitfalls.md

@@ -16,6 +16,8 @@
 | Editing `sync.config.json` to fix mappings | Change sync in web UI; re-pull snapshots |
 | Pushing `syncs/` or `groups/` | Not supported — push only `files/` + `meta/` |
 | Plain object default export for sync logic | **Class** default export; platform uses `new` |
+| New file outside `files/Scripts/` (e.g. `files/Modules/…`) | Platform rejects it — script code lives under `files/Scripts/`, connectors under `files/Connectors/` |
+| Authoring mappings for a connection that does not exist yet | Stop; ask the human to create the connection, then map only what `sm sync fields` prints |
 | Missing meta sidecar on new file | Add `meta/.../*.meta.json` before push |
 | Unwired `import` | Add path to `module_script_file_paths` in sidecar |
 | Running sync logic locally | Types check locally; execution is platform-only |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncmatters/script-api",
-  "version": "1.0.21",
+  "version": "1.0.22",
   "description": "TypeScript type definitions for the SyncMatters script API (types only - scripts execute on the SyncMatters platform)",
   "types": "./index.d.ts",
   "exports": {
@@ -28,7 +28,7 @@
   "license": "MIT",
   "author": "SyncMatters",
   "homepage": "https://syncmatters.com",
-  "typesContentHash": "3dcf1af8c79b37f9fe75992f52dbbdc70d0f22515d9f65b1123ceb7e4f31de20",
+  "typesContentHash": "b96f39108ef358c683102abb6eaeae9b47358feb140dcdc03fea91f41410102a",
   "dependencies": {
     "@types/node": "*"
   }