@sightmap/sightkick 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sightmap/sightkick",
-  "version": "0.4.0",
+  "version": "0.6.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",
@@ -34,11 +34,11 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@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"
+    "@sightmap/sightkick-darwin-arm64": "0.6.0",
+    "@sightmap/sightkick-darwin-x64": "0.6.0",
+    "@sightmap/sightkick-linux-arm64": "0.6.0",
+    "@sightmap/sightkick-linux-x64": "0.6.0",
+    "@sightmap/sightkick-win32-arm64": "0.6.0",
+    "@sightmap/sightkick-win32-x64": "0.6.0"
   }
 }

package/skills/sightkick-authoring/SKILL.md

@@ -71,13 +71,16 @@ sets them (a conflict warns); `tools` and `journeys` accumulate. Most apps set
 - 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)
+  ensure_view: Home        # OPTIONAL: a corpus VIEW name. Omit it and component
+                           #   names resolve against the WHOLE corpus (every view +
+                           #   globals). Set it to scope resolution to one view
+                           #   (+ globals) — disambiguating same-named components —
+                           #   AND to view-scope the tool at runtime (it then 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
+      required: true       # false ⇒ optional: a step using {{title}} auto-skips when it's omitted
       description: The task title.
       # values: [A, B, C]  # required when type: enum
   guard:                   # optional idempotency guard — exactly one of present/absent
@@ -88,19 +91,27 @@ sets them (a conflict warns); `tools` and `journeys` accumulate. Most apps set
 ```
 
 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.
+genuinely **optional**: omit it and a tool resolves its component names against
+the whole corpus (every view's components plus globals). Set it when you want to
+**scope** resolution to a single view — to disambiguate a component name that
+recurs across views — and to **route-scope** the tool so it only registers on
+pages whose route matches. It is a scoping/routing hint, not a prerequisite for
+resolution: a component validly declared on a view resolves with or without it.
 
 ### 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. |
+| `click` | `query` | Click the matched element, the way a user does — it scrolls the target into view and hit-tests to the topmost element at its centre, so it drives custom widgets whose handler sits on an inner child (e.g. a custom-dropdown option). |
 | `wait_for` | `query`, `timeout_ms` (default 5000) | Wait until the query matches — use after a mutating action to confirm the visible result. |
+| `keypress` | `key` | Dispatch one discrete key (e.g. `Enter`) at whatever a preceding fill/click left focused — no query of its own. For a gate a fill's own per-character keys can't stand in for. |
 | `navigate` | `view` | Client-navigate to a corpus **view** by name. |
 | `goto` | `url` | Navigate to a URL template (`{{param}}` interpolated). |
 
+Any step may also carry **`when: "{{param}}"`** — it is skipped when `when`
+interpolates to empty. And a step **auto-skips** when any `{{param}}` it
+interpolates is an *omitted optional* param (see [grouping](#grouping-optional-fields--custom-dropdowns)).
 Reads are **not** steps — declare them with `returns`. A tool that ends with a
 mutation should `wait_for` its own visible feedback before returning.
 
@@ -124,6 +135,51 @@ returns:
       done: done
 ```
 
+## Grouping, optional fields & custom dropdowns
+
+**Group tools by meaning, not by field.** Prefer one tool per meaningful unit a
+user or schema would name — a passenger, a date of birth, a contact block — with
+**typed params** (`enum`/`number`/`string`) whose steps reference **named
+components**. Avoid a generic "set any field by its on-screen label" tool: it
+pushes label-guessing onto the agent, throws away the typed contract that is a
+tool's whole value over raw DOM access, and forces brittle `Component[label*=…]`
+matching that degrades into special-casing exactly when it hits a hard field. A
+grouped tool freely mixes step ops — `fill` for text inputs, click-to-open +
+click-the-option for custom dropdowns — since each field's interaction is authored
+explicitly (so "can't generalize across input types" never arises).
+
+**Optional fields → optional params + skippable steps.** Mark non-required params
+`required: false`; a step **auto-skips** when a `{{param}}` it interpolates is
+omitted (required params are guaranteed present by the input schema). *Omitted ≠
+empty string* — an explicit `""` is a real value and does not skip. Use an explicit
+`when: "{{param}}"` only for a step that gates on a param it doesn't otherwise
+reference. This also lets a grouped tool double as a **partial setter**:
+`set_passenger(firstName="Joel")` sets just that field.
+
+**Custom dropdowns are two clicks, not a special op.** A `<select>`-like custom
+widget (typically an ARIA `button[aria-haspopup=listbox]` + a `[role=option]`
+list) is driven by `click`-ing the trigger to open, then `click`-ing the option —
+the `click` step hits the option the way a user does. Map the trigger and the
+options as corpus components so steps can address `GenderSelect` then
+`GenderSelect Option[label="{{gender}}"]`. No keyboard, no bespoke `select_option`.
+
+**Encode order for dependent fields.** When one field changes another's options
+(e.g. country → state/phone), author the steps in order and `wait_for` the
+dependent control before setting it:
+
+```yaml
+steps:
+  - click: { query: 'CountrySelect' }
+  - click: { query: 'CountrySelect Option[label="{{country}}"]' }
+  - wait_for: { query: 'StateSelect' }        # the re-render has landed
+  - click: { query: 'StateSelect' }
+  - click: { query: 'StateSelect Option[label="{{state}}"]' }
+```
+
+**Reach for a generic `fill_field(field, value)` only** as an escape hatch for a
+large, flat, independent block of homogeneous **text** inputs where typing and
+ordering add nothing — and expect to special-case the structured fields anyway.
+
 ## Component queries (CSS-shaped, over corpus components)
 
 - `Component` — by corpus component name.
@@ -216,20 +272,28 @@ journeys:
         reason: confirm the task you just added
 ```
 
+A journey's `description` isn't decoration — it's the one-line gloss `sightkick outline` prints
+for that journey (see "Plan time" below), the thing a plan-time reader uses to decide "is this the
+flow I want" before reading a single tool's detail. Write it for that reader: name the outcome, one
+sentence, no jargon a first-time reader of this app wouldn't already have.
+
 ## 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
+sightkick outline <APP_DIR>                  # read-back check: what a plan-time agent will see
 ```
 
 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.
+- **unresolved component / property / view** — the name isn't in the corpus
+  (within the tool's scope: the whole corpus, or one view when `ensure_view` is
+  set). `build` prints candidates; fix the query, declare the component/property
+  in the corpus (sightmap-authoring), or drop/adjust `ensure_view` if it's
+  scoping the name out. 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
@@ -240,3 +304,25 @@ The compiler is your validator. Common diagnostics and fixes:
 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.
+
+`build` proves the tool layer compiles; `outline` shows what an agent will actually see when it
+tries to use it. Read your new tool's one-liner in the output — if it doesn't identify what the
+tool does on its own, that's an authoring gap (a description that assumes context an agent
+resolving a scenario won't have), not an implementation gap `build` would ever catch.
+
+## Plan time
+
+Once the tool layer builds clean, a plan-time reader (an agent resolving a `.feature` scenario
+into a plan, or you checking what one would see) never needs the full IR or the raw YAML — see
+`docs/scenario-testing.md` §6/§6.1:
+
+```sh
+sightkick outline <APP_DIR>                                    # journeys + every tool's one-liner
+sightkick explain <APP_DIR> --journey add_and_review           # full detail for that journey's tools
+sightkick explain <APP_DIR> --view TaskList                    # or for a view's tools
+sightkick explain <APP_DIR> add_task                           # or for named tools directly
+```
+
+`outline` is the orientation pass (~3 KB on a 16-tool corpus, about an eighth of the IR); `explain`
+fills in description/params/`ensure_view`/returns for a selected subset. Neither carries `steps`,
+`guard`, or a compiled query — that's runtime DOM-addressing detail, not plan-time information.

package/skills/sightkick-debug/SKILL.md

@@ -45,8 +45,11 @@ 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)
+#   --webmcp         expose the native document.modelContext AND auto-load the
+#                    bundled WebMCP inspector (+ sightmap's overlay) — open it
+#                    from Chrome's side panel to drive the tools with Gemini
+#   --no-inspector   with --webmcp, skip the inspector (native surface only)
+#   --extensions P   load EXTRA unpacked extensions, merged with the above
 #   --profile/--cdp-port/--chrome-flag   passed through to sightmap
 #   --no-start       inject into an already-running session (e.g. after editing the corpus)
 ```
@@ -74,6 +77,11 @@ sightkick runtime -o /tmp/sightkick-runtime.js
 sightkick build <CORPUS_DIR> -o /tmp/x.ir.json
 ```
 
+To *read* the tool layer — what's in it, rather than injecting it — run `sightkick outline
+<CORPUS_DIR>` (journeys + every tool's one-liner) or `explain` for full detail on a subset. Never
+`cat` the IR file for this: roughly two thirds of it is compiled DOM-addressing detail
+(`steps`/`guard`/`Query` trees) that's noise for a reader.
+
 Rebuild the IR whenever the corpus/manifest changes. The runtime bundle is
 embedded in the CLI, so re-emit it after upgrading `sightkick`.
 
@@ -94,11 +102,18 @@ sightmap browser start --detach --url <SITE_URL> --profile /tmp/sk-dbg
 ### Mode B — inspector/Gemini-driven (native WebMCP surface)
 Turn on the blink flags so Chrome exposes the real `document.modelContext`, and
 load the **WebMCP inspector** (a drive-with-Gemini sidebar). Our tools register on
-the native surface, so the inspector reads them like any site's own. The inspector
-isn't shipped with the CLI — use the vendored copy in the sightkick repo
-(`vendor/webmcp-tool/unpacked`, whose `NOTES.md` explains the flag/CfT-version
-rationale) or install it from the Chrome Web Store. Point `<INSPECTOR_DIR>` at its
-unpacked directory:
+the native surface, so the inspector reads them like any site's own.
+
+The easy path is `sightkick browser <CORPUS_DIR> --webmcp`: it flips the blink
+flags **and** auto-loads the bundled inspector (plus sightmap's overlay). The
+inspector is vendored from upstream
+([`beaufortfrancois/model-context-tool-inspector`](https://github.com/beaufortfrancois/model-context-tool-inspector),
+Apache-2.0) and embedded in the CLI, so nothing to install — open it from Chrome's
+side panel. Add `--no-inspector` for the native surface without it.
+
+To do it by hand instead (finer control, or a non-sightkick session), point
+`<INSPECTOR_DIR>` at an unpacked copy of the inspector — the repo's
+`vendor/webmcp-tool/unpacked` (see its `NOTES.md`) or a Chrome-Web-Store install:
 
 ```sh
 sightmap browser start --detach --url <SITE_URL> --profile /tmp/sk-dbg \
@@ -136,6 +151,9 @@ sightmap browser eval "window.__t='RUN';document.modelContext.getTools().then(fu
 sleep 1; sightmap browser eval "window.__t"                    # -> ["tool_a","tool_b",...]
 ```
 
+That's the live, view-scoped names-only listing — the offline, whole-corpus equivalent is
+`sightkick outline <CORPUS_DIR>`, which works with no browser session at all.
+
 ## 4. Drive the tools
 
 ### Mode A (agent/scripted): drive via `sightkick call`