sync: update from private repo (ce93095)

docs/tools/writeuserscript.md

@@ -1,13 +1,16 @@
 # WriteUserScript
 
-Creates or overwrites a script in the caller's user folder.
+Creates or overwrites a Playwright browser-macro in the caller's
+`browser-macros/` folder.
 
-Two destinations are supported:
+> **Retired (2026-06):** plain-Node `scripts/` (the old `kind: 'script'`) and
+> `templates/` were removed. Keep reusable procedures/boilerplate in **Skills**,
+> and run ad-hoc code with the **Bash** tool. Passing `kind: 'script'` now
+> returns an error pointing at those replacements.
 
-| kind | directory | runtime | signature |
-|------|-----------|---------|-----------|
-| `'script'` (default) | `scripts/` | plain Node.js | `main({ params })` |
-| `'browser-macro'` | `browser-macros/` | Playwright — Chromium | `main({ context, params })` |
+| directory | runtime | signature |
+|-----------|---------|-----------|
+| `browser-macros/` | Playwright — Chromium | `main({ context, params })` |
 
 ## Input
 
@@ -15,7 +18,6 @@ Two destinations are supported:
 {
   name: string,                        // slug — '.js' appended if absent
   content: string,                     // full file text (frontmatter + main())
-  kind?: 'script' | 'browser-macro',  // default: 'script'
   overwrite?: boolean                  // default: false — error if file exists
 }
 ```
@@ -26,14 +28,14 @@ The content must define a `main` function. The following forms are all accepted:
 
 ```js
 // ES function declaration
-async function main({ params }) { … }
+async function main({ context, params }) { … }
 
 // Arrow / assigned function
-const main = async ({ params }) => { … };
+const main = async ({ context, params }) => { … };
 
 // CommonJS export
-module.exports = async function main({ params }) { … };
-exports.main = async function({ params }) { … };
+module.exports = async function main({ context, params }) { … };
+exports.main = async function({ context, params }) { … };
 ```
 
 If none of these patterns is found the tool returns `isError: true` with a
@@ -53,10 +55,10 @@ params:
 ---
 ```
 
-Frontmatter is parsed by `RunUserScript` for param validation. Scripts without
+Frontmatter is parsed by `RunUserScript` for param validation. Macros without
 frontmatter still run, but param validation is skipped.
 
-Browser macros may additionally declare `session_profile_id: <N>` to auto-load
+Macros may additionally declare `session_profile_id: <N>` to auto-load
 a saved login session (see `RunUserScript` docs).
 
 ## Size limit
@@ -70,41 +72,15 @@ Pass `overwrite: true` to replace the existing file atomically.
 
 ## When to use
 
-- You discovered a useful reusable pattern during a task — save it for next time.
-- The user asks you to create or update a script they can run later via `RunUserScript`.
+- You discovered a useful browser-automation pattern during a task — save it for next time.
+- The user asks you to create or update a macro they can run later via `RunUserScript`.
 - You want to prototype a browser automation without going through the UI.
 
-## Examples
-
-### Plain Node script
-
-```js
-WriteUserScript({
-  name: "fetch-and-clean",
-  kind: "script",
-  content: `---
-description: Fetch a URL and return cleaned JSON
-params:
-  - name: url
-    type: string
----
-const https = require('https');
-
-async function main({ params }) {
-  const res = await fetch(params.url);
-  const json = await res.json();
-  return { items: json.items ?? [] };
-}
-`
-})
-```
-
-### Browser macro
+## Example
 
 ```js
 WriteUserScript({
   name: "screenshot-dashboard",
-  kind: "browser-macro",
   content: `---
 description: Take a screenshot of the dashboard
 params:
@@ -126,6 +102,7 @@ async function main({ context, params }) {
 | Situation | `isError` | message contains |
 |-----------|-----------|-----------------|
 | No authenticated user | true | "authenticated" |
+| Retired `kind: 'script'` passed | true | "retired" |
 | `name` missing / empty | true | `"name"` |
 | `name` contains `/`, space, etc. | true | "alphanumeric" |
 | `content` missing `main` | true | "main" |
@@ -135,5 +112,5 @@ async function main({ context, params }) {
 ## Notes
 
 - `WriteUserScript` is a META_TOOL — available in every movement without listing it in `allowed_tools`.
-- After writing, use `RunUserScript` to immediately execute and verify the script.
-- Use `ListUserAssets` to see all scripts currently in the folder.
+- After writing, use `RunUserScript` to immediately execute and verify the macro.
+- Use `ListUserAssets` to see all macros currently in the folder.