fix: restore rich descriptions lost in auto-generation

- Snapshot flags: add back value hints (-d <N>, -s <sel>, -o <path>)
- Snapshot flags: restore parenthetical context (@e refs, @c refs, etc.)
- Commands: is → includes valid states enum
- Commands: console → notes --errors filter behavior
- Commands: press → lists common keys (Enter, Tab, Escape)
- Commands: cookie-import-browser → describes picker UI
- Commands: dialog-accept → specifies alert/confirm/prompt
- Tips: restore → arrow (was downgraded to ->)

SKILL.md

@@ -232,14 +232,14 @@ $B css ".button" "background-color"
 The snapshot is your primary tool for understanding and interacting with pages.
 
 ```
--i        Interactive elements only
--c        Remove empty structural elements
--d        Limit tree depth
--s        Scope to CSS selector
--D        Diff against previous snapshot
+-i        Interactive elements only (buttons, links, inputs) with @e refs
+-c        Compact (no empty structural nodes)
+-d <N>    Limit depth
+-s <sel>  Scope to CSS selector
+-D        Diff against previous snapshot (what changed?)
 -a        Annotated screenshot with ref labels
--o        Output path for annotated screenshot
--C        Scan cursor:pointer/onclick/tabindex elements
+-o <path> Output path for screenshot
+-C        Cursor-interactive elements (@c refs — divs with pointer, onclick)
 ```
 
 Combine flags: `$B snapshot -i -a -C -o /tmp/annotated.png`
@@ -279,13 +279,13 @@ Refs are invalidated on navigation — run `snapshot` again after `goto`.
 | `click <sel>` | Click element |
 | `cookie` | Set cookie |
 | `cookie-import <json>` | Import cookies from JSON file |
-| `cookie-import-browser [browser] [--domain d]` | Import cookies from real browser |
-| `dialog-accept [text]` | Auto-accept next dialog |
+| `cookie-import-browser [browser] [--domain d]` | Import cookies from real browser (opens picker UI, or direct with --domain) |
+| `dialog-accept [text]` | Auto-accept next alert/confirm/prompt |
 | `dialog-dismiss` | Auto-dismiss next dialog |
 | `fill <sel> <val>` | Fill input |
 | `header <name> <value>` | Set custom request header |
 | `hover <sel>` | Hover element |
-| `press <key>` | Press key |
+| `press <key>` | Press key (Enter, Tab, Escape, etc.) |
 | `scroll [sel]` | Scroll element into view |
 | `select <sel> <val>` | Select dropdown option |
 | `type <text>` | Type into focused element |
@@ -297,13 +297,13 @@ Refs are invalidated on navigation — run `snapshot` again after `goto`.
 ### Inspection
 | Command | Description |
 |---------|-------------|
-| `attrs <sel>` | Element attributes as JSON |
-| `console [--clear|--errors]` | Console messages |
+| `attrs <sel|@ref>` | Element attributes as JSON |
+| `console [--clear|--errors]` | Console messages (--errors filters to error/warning) |
 | `cookies` | All cookies as JSON |
 | `css <sel> <prop>` | Computed CSS value |
 | `dialog [--clear]` | Dialog messages |
 | `eval <file>` | Run JS file |
-| `is <prop> <sel>` | State check |
+| `is <prop> <sel>` | State check (visible/hidden/enabled/disabled/checked/editable/focused) |
 | `js <expr>` | Run JavaScript |
 | `network [--clear]` | Network requests |
 | `perf` | Page load timings |
@@ -346,7 +346,7 @@ Refs are invalidated on navigation — run `snapshot` again after `goto`.
 
 1. **Navigate once, query many times.** `goto` loads the page; then `text`, `js`, `screenshot` all hit the loaded page instantly.
 2. **Use `snapshot -i` first.** See all interactive elements, then click/fill by ref. No CSS selector guessing.
-3. **Use `snapshot -D` to verify.** Baseline -> action -> diff. See exactly what changed.
+3. **Use `snapshot -D` to verify.** Baseline → action → diff. See exactly what changed.
 4. **Use `is` for assertions.** `is visible .modal` is faster and more reliable than parsing page text.
 5. **Use `snapshot -a` for evidence.** Annotated screenshots are great for bug reports.
 6. **Use `snapshot -C` for tricky UIs.** Finds clickable divs that the accessibility tree misses.

SKILL.md.tmpl

@@ -237,7 +237,7 @@ $B css ".button" "background-color"
 
 1. **Navigate once, query many times.** `goto` loads the page; then `text`, `js`, `screenshot` all hit the loaded page instantly.
 2. **Use `snapshot -i` first.** See all interactive elements, then click/fill by ref. No CSS selector guessing.
-3. **Use `snapshot -D` to verify.** Baseline -> action -> diff. See exactly what changed.
+3. **Use `snapshot -D` to verify.** Baseline → action → diff. See exactly what changed.
 4. **Use `is` for assertions.** `is visible .modal` is faster and more reliable than parsing page text.
 5. **Use `snapshot -a` for evidence.** Annotated screenshots are great for bug reports.
 6. **Use `snapshot -C` for tricky UIs.** Finds clickable divs that the accessibility tree misses.

browse/SKILL.md

@@ -104,14 +104,14 @@ $B diff https://staging.app.com https://prod.app.com
 The snapshot is your primary tool for understanding and interacting with pages.
 
 ```
--i        Interactive elements only
--c        Remove empty structural elements
--d        Limit tree depth
--s        Scope to CSS selector
--D        Diff against previous snapshot
+-i        Interactive elements only (buttons, links, inputs) with @e refs
+-c        Compact (no empty structural nodes)
+-d <N>    Limit depth
+-s <sel>  Scope to CSS selector
+-D        Diff against previous snapshot (what changed?)
 -a        Annotated screenshot with ref labels
--o        Output path for annotated screenshot
--C        Scan cursor:pointer/onclick/tabindex elements
+-o <path> Output path for screenshot
+-C        Cursor-interactive elements (@c refs — divs with pointer, onclick)
 ```
 
 Combine flags: `$B snapshot -i -a -C -o /tmp/annotated.png`
@@ -151,13 +151,13 @@ Refs are invalidated on navigation — run `snapshot` again after `goto`.
 | `click <sel>` | Click element |
 | `cookie` | Set cookie |
 | `cookie-import <json>` | Import cookies from JSON file |
-| `cookie-import-browser [browser] [--domain d]` | Import cookies from real browser |
-| `dialog-accept [text]` | Auto-accept next dialog |
+| `cookie-import-browser [browser] [--domain d]` | Import cookies from real browser (opens picker UI, or direct with --domain) |
+| `dialog-accept [text]` | Auto-accept next alert/confirm/prompt |
 | `dialog-dismiss` | Auto-dismiss next dialog |
 | `fill <sel> <val>` | Fill input |
 | `header <name> <value>` | Set custom request header |
 | `hover <sel>` | Hover element |
-| `press <key>` | Press key |
+| `press <key>` | Press key (Enter, Tab, Escape, etc.) |
 | `scroll [sel]` | Scroll element into view |
 | `select <sel> <val>` | Select dropdown option |
 | `type <text>` | Type into focused element |
@@ -169,13 +169,13 @@ Refs are invalidated on navigation — run `snapshot` again after `goto`.
 ### Inspection
 | Command | Description |
 |---------|-------------|
-| `attrs <sel>` | Element attributes as JSON |
-| `console [--clear|--errors]` | Console messages |
+| `attrs <sel|@ref>` | Element attributes as JSON |
+| `console [--clear|--errors]` | Console messages (--errors filters to error/warning) |
 | `cookies` | All cookies as JSON |
 | `css <sel> <prop>` | Computed CSS value |
 | `dialog [--clear]` | Dialog messages |
 | `eval <file>` | Run JS file |
-| `is <prop> <sel>` | State check |
+| `is <prop> <sel>` | State check (visible/hidden/enabled/disabled/checked/editable/focused) |
 | `js <expr>` | Run JavaScript |
 | `network [--clear]` | Network requests |
 | `perf` | Page load timings |

browse/src/commands.ts

@@ -51,9 +51,9 @@ export const COMMAND_DESCRIPTIONS: Record<string, { category: string; descriptio
   'js':      { category: 'Inspection', description: 'Run JavaScript', usage: 'js <expr>' },
   'eval':    { category: 'Inspection', description: 'Run JS file', usage: 'eval <file>' },
   'css':     { category: 'Inspection', description: 'Computed CSS value', usage: 'css <sel> <prop>' },
-  'attrs':   { category: 'Inspection', description: 'Element attributes as JSON', usage: 'attrs <sel>' },
-  'is':      { category: 'Inspection', description: 'State check', usage: 'is <prop> <sel>' },
-  'console': { category: 'Inspection', description: 'Console messages', usage: 'console [--clear|--errors]' },
+  'attrs':   { category: 'Inspection', description: 'Element attributes as JSON', usage: 'attrs <sel|@ref>' },
+  'is':      { category: 'Inspection', description: 'State check (visible/hidden/enabled/disabled/checked/editable/focused)', usage: 'is <prop> <sel>' },
+  'console': { category: 'Inspection', description: 'Console messages (--errors filters to error/warning)', usage: 'console [--clear|--errors]' },
   'network': { category: 'Inspection', description: 'Network requests', usage: 'network [--clear]' },
   'dialog':  { category: 'Inspection', description: 'Dialog messages', usage: 'dialog [--clear]' },
   'cookies': { category: 'Inspection', description: 'All cookies as JSON' },
@@ -65,17 +65,17 @@ export const COMMAND_DESCRIPTIONS: Record<string, { category: string; descriptio
   'select':  { category: 'Interaction', description: 'Select dropdown option', usage: 'select <sel> <val>' },
   'hover':   { category: 'Interaction', description: 'Hover element', usage: 'hover <sel>' },
   'type':    { category: 'Interaction', description: 'Type into focused element', usage: 'type <text>' },
-  'press':   { category: 'Interaction', description: 'Press key', usage: 'press <key>' },
+  'press':   { category: 'Interaction', description: 'Press key (Enter, Tab, Escape, etc.)', usage: 'press <key>' },
   'scroll':  { category: 'Interaction', description: 'Scroll element into view', usage: 'scroll [sel]' },
   'wait':    { category: 'Interaction', description: 'Wait for element/condition', usage: 'wait <sel|--networkidle|--load>' },
   'upload':  { category: 'Interaction', description: 'Upload file(s)', usage: 'upload <sel> <file...>' },
   'viewport':{ category: 'Interaction', description: 'Set viewport size', usage: 'viewport <WxH>' },
   'cookie':  { category: 'Interaction', description: 'Set cookie' },
   'cookie-import': { category: 'Interaction', description: 'Import cookies from JSON file', usage: 'cookie-import <json>' },
-  'cookie-import-browser': { category: 'Interaction', description: 'Import cookies from real browser', usage: 'cookie-import-browser [browser] [--domain d]' },
+  'cookie-import-browser': { category: 'Interaction', description: 'Import cookies from real browser (opens picker UI, or direct with --domain)', usage: 'cookie-import-browser [browser] [--domain d]' },
   'header':  { category: 'Interaction', description: 'Set custom request header', usage: 'header <name> <value>' },
   'useragent': { category: 'Interaction', description: 'Set user agent', usage: 'useragent <string>' },
-  'dialog-accept': { category: 'Interaction', description: 'Auto-accept next dialog', usage: 'dialog-accept [text]' },
+  'dialog-accept': { category: 'Interaction', description: 'Auto-accept next alert/confirm/prompt', usage: 'dialog-accept [text]' },
   'dialog-dismiss': { category: 'Interaction', description: 'Auto-dismiss next dialog' },
   // Visual
   'screenshot': { category: 'Visual', description: 'Save screenshot', usage: 'screenshot [path]' },

browse/src/snapshot.ts

@@ -52,16 +52,17 @@ export const SNAPSHOT_FLAGS: Array<{
   long: string;
   description: string;
   takesValue?: boolean;
+  valueHint?: string;
   optionKey: keyof SnapshotOptions;
 }> = [
-  { short: '-i', long: '--interactive', description: 'Interactive elements only', optionKey: 'interactive' },
-  { short: '-c', long: '--compact', description: 'Remove empty structural elements', optionKey: 'compact' },
-  { short: '-d', long: '--depth', description: 'Limit tree depth', takesValue: true, optionKey: 'depth' },
-  { short: '-s', long: '--selector', description: 'Scope to CSS selector', takesValue: true, optionKey: 'selector' },
-  { short: '-D', long: '--diff', description: 'Diff against previous snapshot', optionKey: 'diff' },
+  { short: '-i', long: '--interactive', description: 'Interactive elements only (buttons, links, inputs) with @e refs', optionKey: 'interactive' },
+  { short: '-c', long: '--compact', description: 'Compact (no empty structural nodes)', optionKey: 'compact' },
+  { short: '-d', long: '--depth', description: 'Limit depth', takesValue: true, valueHint: '<N>', optionKey: 'depth' },
+  { short: '-s', long: '--selector', description: 'Scope to CSS selector', takesValue: true, valueHint: '<sel>', optionKey: 'selector' },
+  { short: '-D', long: '--diff', description: 'Diff against previous snapshot (what changed?)', optionKey: 'diff' },
   { short: '-a', long: '--annotate', description: 'Annotated screenshot with ref labels', optionKey: 'annotate' },
-  { short: '-o', long: '--output', description: 'Output path for annotated screenshot', takesValue: true, optionKey: 'outputPath' },
-  { short: '-C', long: '--cursor-interactive', description: 'Scan cursor:pointer/onclick/tabindex elements', optionKey: 'cursorInteractive' },
+  { short: '-o', long: '--output', description: 'Output path for screenshot', takesValue: true, valueHint: '<path>', optionKey: 'outputPath' },
+  { short: '-C', long: '--cursor-interactive', description: 'Cursor-interactive elements (@c refs — divs with pointer, onclick)', optionKey: 'cursorInteractive' },
 ];
 
 interface ParsedNode {

scripts/gen-skill-docs.ts

@@ -63,10 +63,8 @@ function generateSnapshotFlags(): string {
   ];
 
   for (const flag of SNAPSHOT_FLAGS) {
-    const flagStr = flag.takesValue
-      ? `${flag.short.padEnd(10)}${flag.description}`
-      : `${flag.short.padEnd(10)}${flag.description}`;
-    lines.push(flagStr);
+    const label = flag.valueHint ? `${flag.short} ${flag.valueHint}` : flag.short;
+    lines.push(`${label.padEnd(10)}${flag.description}`);
   }
 
   lines.push('```');