Pup - the AI's own browser

@@ -2,6 +2,33 @@  ## UNRELEASED (rides the next version) — AD-base re-discovery + self-guarded powershell primitives +### BEHAVIOURAL claims: shipped skills described a taskbar the Mac doesn't have++The worst of the doc classes, and the one no tool the fleet built can detect — these sentences+contain **no path and no platform word**, so nothing greps them. pup's shipped skills documented+Windows taskbar behaviour as simply *what happens*: window-type taskbar icons, overlay badges,+jump lists, `browser_alert_window` "flashes the taskbar", the wiki view-toggle right-click menu.++Two of them changed what an AI would DO, which is why this outranks a cosmetic doc bug:++- `SKILL.md` told the AI **"do not open a second window to 'check' what a taskbar icon already+  answers."** On macOS there is no icon to read, so the AI would skip a legitimate check on the+  strength of information it can never have. Now: on macOS use `browser_list_tabs`, and expect the+  user to describe a window by title or URL rather than by an icon.+- `pup-adom-wiki` told the AI to **tell the user to right-click the pup taskbar button**. A Mac user+  sent looking for that control cannot distinguish "not there" from "I missed it". Now scoped+  Windows-only with the one-verb `wikiView` alternative — and the caveat was moved ABOVE the+  instruction it qualifies, since a note placed after the advice arrives after the AI has acted.++Also scoped: the `taskbarGrouping` preference sections in `SKILL.md` and+`pup-windows-sessions-tabs`, the README's icon/overlay/jump-list sections, and+`browser_alert_window` — which documents its real macOS behaviour (unhide at z-position + an AD+toast whose click focuses) rather than implying a flash that cannot occur.++Unscoped behavioural claims went 19 → 5; the remaining five are image alt-text and verb-table rows+inside already-scoped sections. Deliberately not driven to zero — tightening prose to satisfy a+matcher would be gaming the metric rather than helping the reader.+ ### Shipped skills asserted Windows-only facts the macOS port made false  **Second pass — my own first pass was incomplete, in the way this class always is.** After fixing

@@ -53,6 +53,13 @@ Full everyday usage (tabs, recording, window ownership, cold-start playbook) is  ## Window-type taskbar icons: read a pup window at a glance +> **Windows only.** This section and the taskbar/overlay/jump-list sections below describe **Windows+> taskbar** behaviour. macOS has no taskbar, no per-window tile, no overlay badges and no jump+> lists, so none of it applies there — a pup window on a Mac appears as an ordinary browser window+> and its identity comes from the launched bundle. The one signal that IS cross-platform is the+> **tab title** (solid dot = signed in, hollow dot = public). `browser_configure`'s+> `taskbarGrouping` / `agentActivity` are stored on macOS but inert; the verb says so in its reply.+ ![The pup window-type icon family](docs/icons/family-v1.png)  Every pup window's **taskbar icon states what kind of thing it is showing**. All five share the same@@ -162,7 +169,7 @@ pup can show any Adom wiki page from **two viewpoints**, and both the AI and the   thread on the machine. First use returns `wikiLoginNeeded:true`; the user signs in once, in that   window. -**The user can flip a wiki window themselves**: right-click its taskbar button: the jump list+**Windows only** (macOS has no taskbar or jump list — reopen with `wikiView` instead). **The user can flip a wiki window themselves**: right-click its taskbar button: the jump list carries **"Adom wiki: switch to logged-in view"** (or "...switch to public view"). Clicking it relaunches that same window under the other cookie jar, brings it to the front, and shows an on-screen caption while it works ("Switching to the logged-in view of the Adom wiki", then

@@ -103,6 +103,9 @@ Every `browser_*` verb works on macOS; only the OS-presentation layer differs:  ## Taskbar preference — the USER can ask for "combined mode" +> **WINDOWS ONLY.** macOS has no taskbar; `browser_configure` stores the preference and returns+> `taskbarSupported:false`, but nothing changes on screen. Don't propose it to a Mac user.+ pup windows each get their own taskbar button by default ("split": one button per window, badged with its tab count). If the user says anything like "combine my pup windows", "group the pup icons", "one taskbar button for pup", "my taskbar is cluttered with pup windows" — that's the@@ -113,6 +116,13 @@ the user asks — it's their taskbar. Details: `pup-windows-sessions-tabs`.  ## Window-type taskbar icons (split mode) — what the user sees per window +> **WINDOWS ONLY.** Everything in this section is a Windows taskbar behaviour. **macOS has no+> taskbar**, no per-window tile, and no jump list, so on a Mac none of these icons, overlays or+> right-click affordances exist. The category signal that DOES survive cross-platform is the **tab+> title** (solid dot = signed in, hollow dot = public). On macOS, use `browser_list_windows` /+> `browser_list_tabs` to tell windows apart — do not refer the user to an icon they cannot see,+> and do not skip a check on the assumption an icon already answered it.+ In split mode every pup window's taskbar icon states its CONTENT KIND. All five share the teal Adom tile with a solid browser-window drawing; the glyph inside the window is the category: @@ -127,9 +137,12 @@ Adom tile with a solid browser-window drawing; the glyph inside the window is th The category derives from ALL tabs and updates live (about a second). The corner overlay stays the ACTIVE TAB'S FAVICON (or window/tab counters in grouped mode) — never repurpose it. Adom wiki tab titles also lead with a text glyph: solid dot = signed in, hollow dot = public. You never manage-any of this; pup does it automatically. It is worth KNOWING because the user can see login state-and window kind at a glance — do not open a second window to "check" what a taskbar icon already-answers, and when the user says "the window with the book/globe icon" you know which one they mean.+any of this; pup does it automatically. It is worth KNOWING because **on Windows** the user can see+login state and window kind at a glance — there, do not open a second window to "check" what a+taskbar icon already answers, and when the user says "the window with the book/globe icon" you know+which one they mean. **On macOS neither shortcut applies**: there is no icon to read, so check with+`browser_list_tabs` rather than assuming, and expect the user to describe a window by its title or+URL rather than by an icon.  A WIKI window's taskbar right-click jump list also carries a view toggle ("Adom wiki: switch to logged-in view" / "...to public view") — a USER affordance that relaunches that window under the

@@ -71,6 +71,12 @@ hydrogen.adom.inc SSO once; the session then persists in the authed profile and (Container-identity auto-login — no interactive step — is still tracked in `adom/wiki` #89; when it lands, this becomes zero-touch.) +> **WINDOWS ONLY — do not offer this on macOS.** The jump-list task lives on a Windows taskbar+> button; macOS has neither, so there is nothing for the user to right-click. On a Mac just reopen+> the window yourself with `wikiView:"authed"` / `"public"` — same result, one verb, no user step.+> Telling a Mac user to right-click a taskbar button sends them looking for a control that does not+> exist, and they cannot tell that from having missed it.+ **The user can flip the view themselves (v1.9.3).** Every wiki pup window carries a **taskbar right-click menu** task — "🔓 Switch to logged-in view" on a public window, "📖 Switch to public view" on an authed one. Clicking it relaunches THAT window under the other cookie jar and brings it

@@ -62,8 +62,12 @@ windows, no focus stolen) and stays fully drivable + screenshottable there — y - **Sizing/positioning does NOT foreground** — `browser_open_window {width,height,x,y}` places the window   at an exact size/spot **for clean screenshot framing** while it stays in the background. So you can frame   a shot without ever disturbing the user's main work.-- **`browser_alert_window`** flashes the taskbar (a non-intrusive "it's ready/done" nudge) — prefer it over-  raising the window. Use it for an explicit end-of-task "it's ready".+- **`browser_alert_window`** — a non-intrusive "it's ready/done" nudge; prefer it over raising the window.+  Use it for an explicit end-of-task "it's ready". **On Windows** it flashes the taskbar button. **On+  macOS** there is no taskbar and no API to bounce another app's Dock tile, so the verb instead unhides+  the window at its z-position (visible, still NOT focused) and posts a native AD toast whose click+  focuses it; `{stop:true}` dismisses the toast. Same contract — a nudge that never steals focus — so+  call it identically on both platforms; just don't tell a Mac user to "look at the flashing icon". - `browser_raise_os_window` / `browser_focus_window` bring a window forward — **GATED the same way:   REFUSED (`foreground_reason_required`) unless you pass `foregroundReason`.** Use only for an   explicit user show-me; `browser_lower_os_window` tucks it back after. **Raise steals focus and can@@ -98,6 +102,10 @@ adom-desktop browser_open_window '{"sessionId":"demo-web","owner":"demo","url":"  ## Taskbar look — split vs grouped (user preference, `browser_configure`) +> **WINDOWS ONLY.** macOS has no taskbar, so this preference has no visible effect there —+> `browser_configure` still stores it (and says so in its reply, with `taskbarSupported:false`), but+> nothing changes on screen. Don't offer it to a Mac user as a way to tidy their windows.+ Each pup window wears the Adom Pup icon; how they arrange on the taskbar is the USER's choice:  - **`split` (default):** one taskbar button PER WINDOW, each badged with its own tab count