@sightmap/sightkick 0.2.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.2.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.2.0",
-    "@sightmap/sightkick-darwin-x64": "0.2.0",
-    "@sightmap/sightkick-linux-arm64": "0.2.0",
-    "@sightmap/sightkick-linux-x64": "0.2.0",
-    "@sightmap/sightkick-win32-arm64": "0.2.0",
-    "@sightmap/sightkick-win32-x64": "0.2.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

@@ -0,0 +1,242 @@
+---
+name: sightkick-authoring
+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 `.sightkick/` tool layer
+  - a `sightkick build` reports unresolved component/property/view references
+---
+
+# 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
+**`.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
+the corpus, author it there (sightmap-authoring) before referencing it here.
+
+## Mental model
+
+- A **tool** is one atomic action at a single point in time — no navigation
+  crossing mid-tool. It bundles ordered `steps` (fill/click/…) and/or a
+  `returns` read, and yields a structured result.
+- Multi-step flows are **not executed** by a runtime. A **journey** is a
+  compile-time ordering over tools that compiles into **guidance breadcrumbs**
+  ("after `add_task`, consider `list_tasks`") attached to each tool's result. The
+  agent sequences; you hand it the map.
+- Tools address elements by **component query** (component identity + extracted
+  properties + descendant scope), never raw CSS.
+
+## File shape
+
+Each `.sightkick/*.yaml` file may set any of these top-level keys; they're merged
+across the directory:
+
+```yaml
+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
+- name: add_task           # required, unique
+  description: Add a task. # shown in getTools(); a result-shape hint is appended automatically
+  mode: live               # live (default) drives the DOM; api is opt-in reads-only
+  ensure_view: Home        # a corpus VIEW name — scopes component resolution to that
+                           #   view (+ globals) AND view-scopes the tool at runtime
+                           #   (it only registers on pages whose route matches)
+  params:                  # become the tool's input schema; referenced as {{name}}
+    - name: title
+      type: string         # string | number | boolean | enum
+      required: true
+      description: The task title.
+      # values: [A, B, C]  # required when type: enum
+  guard:                   # optional idempotency guard — exactly one of present/absent
+    present: { query: 'TaskItem[title="{{title}}"]' }   # SKIP the steps when this exists
+    # absent: { query: ... }                            # SKIP when it does NOT exist
+  steps: [ ... ]           # ordered actions (below)
+  returns: { ... }         # the structured result (below)
+```
+
+A `live` tool needs **at least one `step` or a `returns`**. `ensure_view` is
+optional but recommended — it both disambiguates component names and controls
+which page the tool appears on.
+
+### Steps (each is a single-key mapping: the op)
+
+| Step | Body | Does |
+|------|------|------|
+| `fill` | `query`, `value` | Type `value` (supports `{{param}}`) into the matched input. |
+| `click` | `query` | Click the matched element. |
+| `wait_for` | `query`, `timeout_ms` (default 5000) | Wait until the query matches — use after a mutating action to confirm the visible result. |
+| `navigate` | `view` | Client-navigate to a corpus **view** by name. |
+| `goto` | `url` | Navigate to a URL template (`{{param}}` interpolated). |
+
+Reads are **not** steps — declare them with `returns`. A tool that ends with a
+mutation should `wait_for` its own visible feedback before returning.
+
+### Returns (exactly one of `value` or `list`, or description-only)
+
+```yaml
+returns:
+  description: One task title.        # optional; also folded into the tool description
+  value:                             # a single scalar
+    query: 'TaskItem[title="{{title}}"]'
+    property: title                  # a DECLARED corpus property of the matched component
+```
+
+```yaml
+returns:
+  description: The current task rows.
+  list:                              # an array of objects, one per match
+    rows: TaskItem                   # a compquery; every match is a row
+    fields:                          # outputName: <declared property of the row>
+      title: title                   # scalar shorthand, or: title: { property: title }
+      done: done
+```
+
+## Component queries (CSS-shaped, over corpus components)
+
+- `Component` — by corpus component name.
+- `Component[prop="v"]` — filter on an **extracted property** (not a raw DOM
+  attribute). Operators: `=` exact, `^=` prefix, `*=` substring; append ` i` for
+  case-insensitive (e.g. `[label="done" i]`).
+- `A B` — descendant; the **last** component is the target, an ancestor predicate
+  scopes it (`TaskItem[title="{{title}}"] TaskToggle`). There is **no `>`** child
+  combinator — use whitespace.
+- `Component#N` — 0-based occurrence when several match (weak fallback; prefer a
+  distinguishing property).
+- `{{param}}` interpolates a tool param into any query/value/url.
+
+Every property you filter on or read must be **declared in the corpus**. If a
+label is CSS-uppercased on screen but lowercase in the DOM text, match
+case-insensitively with ` i`.
+
+## Journeys → guidance (not execution)
+
+```yaml
+journeys:
+  - name: add_and_review
+    description: Add a task, then review the list.
+    steps:
+      - add_task                                   # bare tool name
+      - tool: list_tasks                           # or a mapping with a reason
+        reason: see the task you just added
+```
+
+Each journey needs **≥2 steps** to produce guidance edges. A tool shared across
+journeys accumulates the union of its successors. Journeys never navigate or run
+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
+tools:
+  - name: list_tasks
+    description: List the current tasks and whether each is done.
+    ensure_view: Home
+    returns:
+      description: The task rows (title + done-state).
+      list:
+        rows: TaskItem
+        fields:
+          title: title
+          done: done
+
+  - name: add_task
+    description: Add a task to the list.
+    ensure_view: Home
+    params:
+      - name: title
+        type: string
+        required: true
+        description: The task title.
+    steps:
+      - fill:  { query: NewTaskInput, value: "{{title}}" }
+      - click: { query: AddTaskButton }
+      - wait_for: { query: 'TaskItem[title="{{title}}"]' }
+    returns:
+      description: The title of the new task.
+      value: { query: 'TaskItem[title="{{title}}"]', property: title }
+
+  - name: complete_task
+    description: Mark a task done by clicking its toggle.
+    ensure_view: Home
+    params:
+      - name: title
+        type: string
+        required: true
+        description: The task to complete.
+    steps:
+      - click: { query: 'TaskItem[title="{{title}}"] TaskToggle' }
+      - wait_for: { query: 'TaskItem[title="{{title}}"] TaskToggle[label="Undo"]' }
+    returns:
+      value: { query: 'TaskItem[title="{{title}}"]', property: done }
+
+journeys:
+  - name: add_and_review
+    description: Add a task, then review the list.
+    steps:
+      - add_task
+      - tool: list_tasks
+        reason: confirm the task you just added
+```
+
+## Build & fix
+
+```sh
+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:
+
+- **unresolved component / property / view** — the name isn't in the corpus (for
+  that view). `build` prints candidates; fix the query, or declare the
+  component/property in the corpus (sightmap-authoring). Remember property refs
+  resolve against the **row/target** component.
+- **`returns has both value and list`** — pick one.
+- **`live tool needs at least one step or a returns`** — add a step or a read.
+- **`unrecognized step op`** / **`not a single-key mapping`** — each step is one
+  op key (`fill`/`click`/`wait_for`/`navigate`/`goto`) with its body.
+- **`--verify` says a field resolves empty on every row** — the declared property
+  extracts nothing on the live DOM; fix the property's extractor in the corpus.
+
+For `--verify` you need a captured snapshot of the view (`sightmap capture` /
+`snapshot` in the sightmap-browser skill). Once `build` is clean, run the tools
+on a live page with the **sightkick-debug** skill.

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,10 +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 `.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:
@@ -41,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
 ```
 
@@ -109,18 +138,45 @@ sleep 1; sightmap browser eval "window.__t"                    # -> ["tool_a","t
 
 ## 4. Drive the tools
 
-### Mode A (polyfill): drive over eval
-The polyfill's `executeTool(tool, args)` accepts a bare `{name}`:
+### 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';document.modelContext.executeTool({name:'search'},{query:'ATL to LHR'}).then(function(r){window.__r=r.content[0].text}).catch(function(e){window.__r='ERR '+e});'go'"
-sleep 2; sightmap browser eval "window.__r"                    # the ToolResult JSON (ok/value/items/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
 ```
 
-The result envelope is `{content:[{type:'text',text:<ToolResult JSON>}]}`; 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.
+**`--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 driving the WebMCP
+surface directly.
+
+> **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>}]}`).
+> `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