@sightmap/sightkick 0.3.0 → 0.4.0

package/README.md

@@ -1,7 +1,7 @@
 # @sightmap/sightkick
 
-The **sightkick** CLI: compile a `webmcp.tools.yaml` + a sightmap `.sightmap/`
-corpus into WebMCP tool IR, and install the sightkick agent skills.
+The **sightkick** CLI: compile a `.sightkick/` tool layer + a sightmap
+`.sightmap/` corpus into WebMCP tool IR, and install the sightkick agent skills.
 
 Ships as a native binary (no Go toolchain required). `npm install` pulls in only
 the `@sightmap/sightkick-<os>-<arch>` package matching your platform; the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sightmap/sightkick",
-  "version": "0.3.0",
-  "description": "sightkick — compile a webmcp.tools.yaml + sightmap corpus into WebMCP tool IR, and install the sightkick agent skills (native binary, no Go toolchain required)",
+  "version": "0.4.0",
+  "description": "sightkick — compile a .sightkick/ tool layer + sightmap corpus into WebMCP tool IR, and install the sightkick agent skills (native binary, no Go toolchain required)",
   "license": "MIT",
   "homepage": "https://sightmap.org",
   "repository": {
@@ -34,11 +34,11 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@sightmap/sightkick-darwin-arm64": "0.3.0",
-    "@sightmap/sightkick-darwin-x64": "0.3.0",
-    "@sightmap/sightkick-linux-arm64": "0.3.0",
-    "@sightmap/sightkick-linux-x64": "0.3.0",
-    "@sightmap/sightkick-win32-arm64": "0.3.0",
-    "@sightmap/sightkick-win32-x64": "0.3.0"
+    "@sightmap/sightkick-darwin-arm64": "0.4.0",
+    "@sightmap/sightkick-darwin-x64": "0.4.0",
+    "@sightmap/sightkick-linux-arm64": "0.4.0",
+    "@sightmap/sightkick-linux-x64": "0.4.0",
+    "@sightmap/sightkick-win32-arm64": "0.4.0",
+    "@sightmap/sightkick-win32-x64": "0.4.0"
   }
 }

package/skills/sightkick-authoring/SKILL.md

@@ -1,20 +1,35 @@
 ---
 name: sightkick-authoring
-description: Author a webmcp.tools.yaml — the sightkick manifest that turns a sightmap corpus into named WebMCP tools (atomic view-scoped actions + guidance journeys), then compile it to IR with `sightkick build`. Use when you have (or are building) a `.sightmap/` corpus and want to define the tools an agent can call on that app. Pairs with sightmap-authoring (writes the corpus this reads) and sightkick-debug (runs the compiled tools on a live page).
+description: Author a .sightkick/ tool layer — the sightkick manifest that turns a sightmap corpus into named WebMCP tools (atomic view-scoped actions + guidance journeys), then compile it to IR with `sightkick build`. Use when you have (or are building) a `.sightmap/` corpus and want to define the tools an agent can call on that app. Pairs with sightmap-authoring (writes the corpus this reads) and sightkick-debug (runs the compiled tools on a live page).
 activation:
   - a `.sightmap/` corpus exists (or is being authored) and you want to define WebMCP tools over it
-  - writing or editing a `webmcp.tools.yaml`
+  - writing or editing a `.sightkick/` tool layer
   - a `sightkick build` reports unresolved component/property/view references
 ---
 
-# sightkick-authoring: write a webmcp.tools.yaml
+# sightkick-authoring: write a .sightkick/ tool layer
 
 sightkick compiles two inputs into a self-contained **IR**: a `.sightmap/` corpus
 (the app's component map — authored with the **`sightmap-authoring`** skill) and a
-**`webmcp.tools.yaml`** manifest (the *tool layer*, authored here). `sightkick
-build` resolves every reference in the manifest against the corpus and reports
-unresolved ones with candidate lists. Once it compiles, drive the tools on a live
-page with the **`sightkick-debug`** skill.
+**`.sightkick/`** tool layer (authored here). `sightkick build` resolves every
+reference against the corpus and reports unresolved ones with candidate lists.
+Once it compiles, drive the tools on a live page with the **`sightkick-debug`**
+skill.
+
+The two sit side by side in the app directory:
+
+```
+<app>/
+  .sightmap/     # the corpus (components + views), read by sightkick
+  .sightkick/    # the tool layer, authored here
+    *.yaml       # any number of files — all merged into one manifest
+```
+
+`.sightkick/` mirrors `.sightmap/`: every `*.yaml` file inside is **merged** into
+one manifest (tools and journeys concatenated), with **no dependencies** between
+files — the whole directory is the manifest. Split a large tool layer however
+helps (e.g. one file per view, plus a `journeys.yaml`); keep a tiny one in a
+single `tools.yaml`.
 
 **Prerequisite:** the corpus must exist first — tools reference corpus
 **component names** and **declared properties**, so if a name/property isn't in
@@ -34,14 +49,22 @@ the corpus, author it there (sightmap-authoring) before referencing it here.
 
 ## File shape
 
+Each `.sightkick/*.yaml` file may set any of these top-level keys; they're merged
+across the directory:
+
 ```yaml
-version: 1                 # required (must be 1)
-name: myapp                # the IR name
-corpus: ./.sightmap        # required — path to the corpus dir, relative to this file
-tools: [ ... ]             # required, non-empty
+version: 1                 # optional (defaults to 1); set it once
+name: myapp                # optional — the IR name; defaults to the app dir's name
+corpus: ../.sightmap       # optional — path to the corpus, relative to .sightkick/;
+                           #   defaults to the sibling ../.sightmap
+tools: [ ... ]             # the tools (at least one across the whole directory)
 journeys: [ ... ]          # optional
 ```
 
+The singular fields (`version`/`name`/`corpus`) are taken from whichever file
+sets them (a conflict warns); `tools` and `journeys` accumulate. Most apps set
+`version`/`name` in the first file and never touch `corpus`.
+
 ## Tools
 
 ```yaml
@@ -136,10 +159,12 @@ anything — they only shape the breadcrumbs in results.
 
 ## Worked example (a task-list app)
 
+One file, `.sightkick/tools.yaml` (no `corpus:` — it defaults to the sibling
+`../.sightmap`). Split it across several `.sightkick/*.yaml` files once it grows.
+
 ```yaml
 version: 1
 name: tasks
-corpus: ./.sightmap
 tools:
   - name: list_tasks
     description: List the current tasks and whether each is done.
@@ -194,9 +219,9 @@ journeys:
 ## Build & fix
 
 ```sh
-sightkick build <DIR> -o /tmp/x.ir.json     # <DIR> holds webmcp.tools.yaml + the corpus
-sightkick build <DIR> --verify              # also checks returns extractors against captured
-                                            #   view snapshots; warns on fields empty on every row
+sightkick build <APP_DIR> -o /tmp/x.ir.json  # <APP_DIR> holds .sightkick/ + .sightmap/
+sightkick build <APP_DIR> --verify           # also checks returns extractors against captured
+                                             #   view snapshots; warns on fields empty on every row
 ```
 
 The compiler is your validator. Common diagnostics and fixes:

package/skills/sightkick-debug/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: sightkick-debug
-description: Drive and debug a generated sightkick WebMCP tool script on a live page via `sightmap browser`, with no bespoke sightkick extension. Use when you have a sightkick corpus + `webmcp.tools.yaml` (in the sightkick repo's `examples/` or a `sites/<name>/` dir) and want to inject its compiled tools into a running site and exercise them — either agent-driven (getTools/executeTool over `sightmap browser eval`) or Gemini-driven via the vendored WebMCP inspector.
+description: Drive and debug a generated sightkick WebMCP tool script on a live page via `sightmap browser`, with no bespoke sightkick extension. Use when you have a sightkick `.sightkick/` tool layer + `.sightmap/` corpus (in the sightkick repo's `examples/` or a `sites/<name>/` dir) and want to inject its compiled tools into a running site and exercise them — either agent-driven (getTools/executeTool over `sightmap browser eval`) or Gemini-driven via the vendored WebMCP inspector.
 activation:
-  - a sightkick `webmcp.tools.yaml` + `.sightmap/` corpus is present and you want to run its tools on a live page
+  - a sightkick `.sightkick/` tool layer + `.sightmap/` corpus is present and you want to run its tools on a live page
   - debugging why a generated WebMCP tool does/doesn't register or fire on a real site
 ---
 
 # sightkick-debug: run generated WebMCP tools on a live page
 
-sightkick compiles a `.sightmap/` corpus + a `webmcp.tools.yaml` into an **IR**,
+sightkick compiles a `.sightmap/` corpus + a `.sightkick/` tool layer into an **IR**,
 and a ~19 KB runtime bundle turns that IR into WebMCP tools on
 `document.modelContext`. You do **not** need a bespoke extension to get them onto
 a page: `sightmap browser eval` injects the runtime bundle, then
@@ -29,14 +29,39 @@ sightmap browser install                 # Chrome-for-Testing; needs >=152 for n
 
 That installs the **`sightmap-browser`** skill (driving a live session) and
 **`sightmap-authoring`** skill (building the `.sightmap/` corpus) alongside this
-one — everything needed to build and test a `webmcp.tools.yaml`. No repo checkout
-is required; `<CORPUS_DIR>` below is any directory holding a `webmcp.tools.yaml`
+one — everything needed to build and test a `.sightkick/` tool layer. No repo checkout
+is required; `<CORPUS_DIR>` below is any directory holding a `.sightkick/` tool layer
 + `.sightmap/` corpus.
 
-To **write** the `webmcp.tools.yaml` (its tool/step/`returns`/`journeys` grammar),
+To **write** the `.sightkick/` tool layer (its tool/step/`returns`/`journeys` grammar),
 see the **`sightkick-authoring`** skill — this skill assumes it already exists and
 compiles.
 
+## Quick start: `sightkick browser`
+
+For the common case, one command does the whole setup — build the IR, start a
+sightmap session, and persist-inject the runtime + tools:
+
+```sh
+sightkick browser <CORPUS_DIR>
+#   auto-opens the corpus's home-view URL (or pass --url URL)
+#   --webmcp         expose the native document.modelContext (adds the blink flags)
+#   --extensions P   load an unpacked extension (e.g. a WebMCP inspector)
+#   --profile/--cdp-port/--chrome-flag   passed through to sightmap
+#   --no-start       inject into an already-running session (e.g. after editing the corpus)
+```
+
+It runs sightmap from `<CORPUS_DIR>`, so the session lives in that dir's
+`.sightmap/` — **drive it from there** (`cd <CORPUS_DIR> && sightmap browser
+eval …`, see §4). The inject is **persisted**, so on SPA route changes (and, once
+sightmap's persist re-injection lands, full navigations too) the tools
+re-register automatically. Re-run `sightkick browser <CORPUS_DIR> --no-start`
+after editing the corpus to refresh the injected IR.
+
+The manual steps below (§1–§3) are the same thing unbundled — reach for them for
+finer control, to understand what's happening, or when driving a site the wrapper
+didn't start.
+
 ## 1. Build the two artifacts
 
 Both come straight from the installed `sightkick` CLI:
@@ -45,7 +70,7 @@ Both come straight from the installed `sightkick` CLI:
 # The payload: the runtime bundle (exposes window.__sightkick.load).
 sightkick runtime -o /tmp/sightkick-runtime.js
 
-# The IR for the corpus you're testing (any dir with webmcp.tools.yaml + .sightmap/).
+# The IR for the corpus you're testing (any dir with .sightkick/ + .sightmap/).
 sightkick build <CORPUS_DIR> -o /tmp/x.ir.json
 ```
 
@@ -113,27 +138,45 @@ sleep 1; sightmap browser eval "window.__t"                    # -> ["tool_a","t
 
 ## 4. Drive the tools
 
-### Mode A (agent/scripted): drive via `window.__sightkick.call`
-The **reliable** scripted entry point is `window.__sightkick.call(name, args)` — it
-invokes a tool by name and resolves to the raw `ToolResult` directly, regardless
-of whether the page's `document.modelContext` is our polyfill or a native surface:
+### Mode A (agent/scripted): drive via `sightkick call`
+The scripted entry point is `sightkick call <app-dir> <tool> --param k=v ...`. It
+prints the resolved `ToolResult` as JSON and exits non-zero on `ok:false`.
+`--via` picks how the tool runs:
 
 ```sh
-sightmap browser eval "window.__r='RUN';window.__sightkick.call('add_task',{title:'Water the plants'}).then(function(r){window.__r=JSON.stringify(r)}).catch(function(e){window.__r='ERR '+e});'go'"
-sleep 2; sightmap browser eval "window.__r"                    # the ToolResult JSON (ok/value/items/skipped/guidance)
+sightkick call . add_task --param title="Water the plants"              # --via webmcp (default)
+sightkick call . add_task --param title="Water the plants" --via cli    # translate steps to CLI commands
 ```
 
+**`--via webmcp`** asks the page's own registered tool to run itself, so it
+exercises the contract a real WebMCP client uses. It requires the runtime on the
+page — that's what step 3 above sets up — and a tool is only registered on its
+own view, so an out-of-view tool simply isn't there to call.
+
+**`--via cli`** translates the tool's steps into `sightmap browser <verb>`
+commands and needs no runtime at all: a plain `sightmap browser start` is
+enough. Two reasons to reach for it:
+
+- **Portal-rendered targets.** The runtime clicks by dispatching synthetic
+  events, which do not reach elements rendered outside the app's own DOM
+  subtree — dropdown menu items and modal buttons. The same element takes a
+  real click fine, so a tool that silently no-ops under `--via webmcp` often
+  works under `--via cli`.
+- **Any page you don't control.** A third-party app has no sightkick runtime on
+  it, so `--via webmcp` has nothing to call.
+
 The `ToolResult` carries `ok`, `value`/`items`, `skipped` (idempotency guard
 hit), and `guidance` (next-step breadcrumbs). The sightkick repo's
-`packages/runtime/eval/run.mjs` is a full scripted example of this loop.
+`packages/runtime/eval/run.mjs` is a full scripted example driving the WebMCP
+surface directly.
 
-> **Don't script `document.modelContext.executeTool` directly.** Its call shape
+> **Don't script `document.modelContext.executeTool` yourself.** Its call shape
 > differs by surface: the polyfill takes a bare `{name}`, but a **native**
 > `document.modelContext` (present on Chrome ≥150 even with no blink flags) is
 > stricter and rejects it with `Failed to parse input arguments`, and wraps the
 > result in an envelope (`{content:[{type:'text',text:<ToolResult JSON>}]}`).
-> `window.__sightkick.call` sidesteps both differences — prefer it for Mode A, and
-> leave `executeTool` to the inspector in Mode B.
+> `sightkick call` handles both — use it for Mode A, and leave `executeTool` to
+> the inspector in Mode B.
 
 ### Mode B (native): drive via the inspector
 Open the inspector's sidebar and prompt Gemini — it enumerates