@cyrusxc5/better-ego-browser 0.0.0-stage → 0.3.6

package/skills/ego-browser/learnings/github/browser-tools/repo-stats.js

@@ -0,0 +1,10 @@
+async function(args) {
+  const stats = {
+    stars: document.querySelector('a[href*="stargazers"]')?.innerText?.replace(/\s/g, '') || '',
+    forks: document.querySelector('a[href*="forks"]')?.innerText?.replace(/\s/g, '') || '',
+    language: document.querySelector('[itemprop="programmingLanguage"]')?.innerText?.trim() || '',
+    name: document.querySelector('[data-target="repo-banner.repoName"]')?.innerText?.trim() || '',
+    description: document.querySelector('[data-testid="about-section-notice-p"]')?.nextElementSibling?.innerText?.trim() || '',
+  };
+  return stats;
+}

package/skills/ego-browser/learnings/github/manifest.json

@@ -0,0 +1,61 @@
+{
+  "id": "github",
+  "name": "GitHub",
+  "domains": ["github.com", "*.github.com"],
+  "notes": ["notes/overview.md"],
+  "nodeTools": {
+    "search_repos": {
+      "description": "Search GitHub repositories and extract results.",
+      "path": "tools/search-repos.js",
+      "callable": "searchRepos",
+      "args": {
+        "query": {
+          "type": "string",
+          "required": true,
+          "description": "Search query for repos."
+        },
+        "maxResults": {
+          "type": "integer",
+          "required": false,
+          "description": "Maximum number of repos to extract."
+        }
+      },
+      "returns": {
+        "type": "array",
+        "description": "Array of {name, owner, stars, description} objects."
+      }
+    },
+    "get_open_issues": {
+      "description": "Extract open issues from a repository.",
+      "path": "tools/open-issues.js",
+      "callable": "getOpenIssues",
+      "args": {
+        "owner": {
+          "type": "string",
+          "required": true,
+          "description": "Repository owner (username or org)."
+        },
+        "repo": {
+          "type": "string",
+          "required": true,
+          "description": "Repository name."
+        }
+      },
+      "returns": {
+        "type": "array",
+        "description": "Array of {title, number, state} objects."
+      }
+    }
+  },
+  "browserTools": {
+    "get_repo_stats": {
+      "description": "Extract stars, forks, and language from a GitHub repo page.",
+      "path": "browser-tools/repo-stats.js",
+      "args": {},
+      "returns": {
+        "type": "object",
+        "description": "Object with stars, forks, language."
+      }
+    }
+  }
+}

package/skills/ego-browser/learnings/github/notes/overview.md

@@ -0,0 +1,21 @@
+# GitHub Overview
+
+## Page structure
+- Navigation: Header with logo, search, notifications
+- Repository page: `[data-view-component]` wraps the repo body
+- File tree: `#repo-files-toc` or `Box-row`
+- Issues: `[data-test-id="issue-list-item"]` for issue rows
+
+## Navigation patterns
+- Repo URL: `https://github.com/{owner}/{repo}`
+- Search URL: `https://github.com/search?q={query}&type=repositories`
+- Issues URL: `https://github.com/{owner}/{repo}/issues`
+- PR URL: `https://github.com/{owner}/{repo}/pulls`
+
+## Common selectors
+- Repo name: `[data-target="repo-banner.repoName"]`
+- Stars button: `a.Link--muted[data-hydro-click*="stargazers"]`
+- Forks button: `a.Link--muted[data-hydro-click*="forks"]`
+- Language: `[itemprop="programmingLanguage"]`
+- Description: About section content
+- Search input: `input[data-testid="search-input"]` or `input.repository-search-bar-input`

package/skills/ego-browser/learnings/github/tools/open-issues.js

@@ -0,0 +1,24 @@
+const OWNER_RE = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/;
+const REPO_RE = /^[A-Za-z0-9._-]+$/;
+
+export async function getOpenIssues(ctx, args = {}) {
+  const owner = args.owner || "";
+  const repo = args.repo || "";
+  if (!OWNER_RE.test(owner) || !REPO_RE.test(repo)) {
+    throw new Error("valid GitHub owner and repo are required");
+  }
+
+  await ctx.openOrReuseTab(`https://github.com/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/issues`, { wait: true });
+  await ctx.waitForLoad();
+
+  const issues = await ctx.js(String.raw`(() => {
+    const rows = [...document.querySelectorAll('[data-test-id="issue-list-item"]')]
+    return rows.map(el => {
+      const title = el.querySelector('a[aria-label*="issue"]')?.innerText?.trim() || el.querySelector('h2 a')?.innerText?.trim() || ''
+      const number = el.querySelector('[itemprop="discussionUrl"]')?.innerText?.trim() || ''
+      return { title, number }
+    }).filter(i => i.title)
+  })()`);
+
+  return issues;
+}

package/skills/ego-browser/learnings/github/tools/search-repos.js

@@ -0,0 +1,30 @@
+function boundedInteger(value, fallback, max) {
+  const number = value === undefined ? fallback : Number(value);
+  if (!Number.isFinite(number)) return fallback;
+  return Math.max(1, Math.min(max, Math.trunc(number)));
+}
+
+export async function searchRepos(ctx, args = {}) {
+  const query = args.query || "";
+  const maxResults = boundedInteger(args.maxResults, 25, 100);
+  if (!query) throw new Error("search query is required");
+
+  await ctx.openOrReuseTab(`https://github.com/search?q=${encodeURIComponent(query)}&type=repositories&s=stars&o=desc`, {
+    wait: true,
+  });
+  await ctx.waitForLoad();
+
+  const repos = await ctx.js(String.raw`(() => {
+    const repos = [...document.querySelectorAll('[data-hydro-click*="repo"]')]
+    return repos.slice(0, ${maxResults}).map(el => {
+      const name = el.querySelector('h2 a')?.innerText?.trim() || ''
+      const link = el.querySelector('h2 a')?.getAttribute('href') || ''
+      const parts = link.split('/')
+      const owner = parts[1] || ''
+      const stars = el.querySelector('a[href*="stargazers"]')?.innerText?.replace(/\s/g, '') || ''
+      return { name: parts[2] || name, owner, stars, link }
+    }).filter(r => r.name)
+  })()`);
+
+  return repos;
+}

package/skills/ego-browser/learnings/google/browser-tools/autocomplete.js

@@ -0,0 +1,11 @@
+async function(args) {
+  const suggestionEls = document.querySelectorAll('span.gsqphr');
+  if (suggestionEls.length) {
+    return [...suggestionEls].map(el => el.innerText?.trim() || '').filter(Boolean);
+  }
+  const lis = document.querySelectorAll('.ssb-a');
+  if (lis.length) {
+    return [...lis].map(li => li.innerText?.trim() || '').filter(Boolean);
+  }
+  return [];
+}

package/skills/ego-browser/learnings/google/manifest.json

@@ -0,0 +1,40 @@
+{
+  "id": "google",
+  "name": "Google Search",
+  "domains": ["google.com", "*.google.com", "www.google.com"],
+  "notes": ["notes/overview.md"],
+  "nodeTools": {
+    "search_and_extract": {
+      "description": "Perform a Google search and extract top organic results.",
+      "path": "tools/search-extract.js",
+      "callable": "searchAndExtract",
+      "args": {
+        "query": {
+          "type": "string",
+          "required": true,
+          "description": "Search query string."
+        },
+        "maxResults": {
+          "type": "integer",
+          "required": false,
+          "description": "Maximum number of results to extract."
+        }
+      },
+      "returns": {
+        "type": "array",
+        "description": "Array of {title, url, snippet} objects."
+      }
+    }
+  },
+  "browserTools": {
+    "get_autocomplete_suggestions": {
+      "description": "Get autocomplete suggestions for the current search query.",
+      "path": "browser-tools/autocomplete.js",
+      "args": {},
+      "returns": {
+        "type": "array",
+        "description": "Array of suggestion strings."
+      }
+    }
+  }
+}

package/skills/ego-browser/learnings/google/notes/overview.md

@@ -0,0 +1,20 @@
+# Google Search Overview
+
+## Page structure
+- Search input: `textarea[name="q"]` or `input[name="q"]`
+- Results container: `div#search`
+- Individual result items: `div.g`
+- Result title: `h3` inside `div.g`
+- Result link: `a[href]` inside `div.g a`
+- Result snippet: text content below the title
+
+## Navigation
+- Use `openOrReuseTab` with `https://www.google.com/search?q=...`
+- Results load immediately, no infinite scroll on first page
+- Pagination links at bottom: `a[href*="/search?q="]`
+
+## Common selectors
+- Query box: `textarea[name="q"]`
+- Search button: `input[type="submit"]`
+- Auto-complete dropdown: `div[role="listbox"]`
+- Auto-complete items: `.ssb-a`

package/skills/ego-browser/learnings/google/tools/search-extract.js

@@ -0,0 +1,25 @@
+function boundedInteger(value, fallback, max) {
+  const number = value === undefined ? fallback : Number(value);
+  if (!Number.isFinite(number)) return fallback;
+  return Math.max(1, Math.min(max, Math.trunc(number)));
+}
+
+export async function searchAndExtract(ctx, args = {}) {
+  const query = args.query || "";
+  const maxResults = boundedInteger(args.maxResults, 10, 100);
+  if (!query) throw new Error("search query is required");
+
+  await ctx.openOrReuseTab(`https://www.google.com/search?q=${encodeURIComponent(query)}`, { wait: true });
+  await ctx.waitForLoad();
+
+  const results = await ctx.js(String.raw`(() => {
+    const items = [...document.querySelectorAll('div.g')]
+    return items.slice(0, ${maxResults}).map(el => ({
+      title: el.querySelector('h3')?.innerText?.trim() || '',
+      url: el.querySelector('a')?.getAttribute('href') || '',
+      snippet: el.querySelector('[data-sncf]')?.innerText?.trim() || el.querySelector('span')?.innerText?.trim() || '',
+    })).filter(r => r.title)
+  })()`);
+
+  return results;
+}

package/skills/ego-browser/learnings/x-com/browser-tools/extract-post.js

@@ -0,0 +1,9 @@
+async function(args) {
+  const el = document.querySelector('[data-testid="tweet"]:focus') || document.querySelector('[data-testid="tweet"]');
+  if (!el) return { error: 'no active tweet found' };
+  return {
+    text: el.querySelector('[data-testid="tweetText"]')?.innerText?.trim() || '',
+    author: el.querySelector('[data-testid="User-Name"] span')?.innerText?.trim() || '',
+    timestamp: el.querySelector('time')?.getAttribute('datetime') || '',
+  };
+}

package/skills/ego-browser/learnings/x-com/manifest.json

@@ -0,0 +1,51 @@
+{
+  "id": "x-com",
+  "name": "X (Twitter)",
+  "domains": ["x.com", "*.x.com", "twitter.com", "*.twitter.com"],
+  "notes": ["notes/overview.md", "notes/timeline.md"],
+  "nodeTools": {
+    "get_timeline_posts": {
+      "description": "Extract posts from the current X timeline using the anti-click-wrap pattern.",
+      "path": "tools/timeline.js",
+      "callable": "getTimelinePosts",
+      "args": {
+        "maxPosts": {
+          "type": "integer",
+          "required": false,
+          "description": "Maximum number of posts to extract."
+        }
+      },
+      "returns": {
+        "type": "array",
+        "description": "Array of post objects with text, author, and timestamp."
+      }
+    },
+    "search_users": {
+      "description": "Search for users on X.",
+      "path": "tools/search-users.js",
+      "callable": "searchUsers",
+      "args": {
+        "query": {
+          "type": "string",
+          "required": true,
+          "description": "Search query string."
+        }
+      },
+      "returns": {
+        "type": "array",
+        "description": "Array of user info objects."
+      }
+    }
+  },
+  "browserTools": {
+    "post_from_active_element": {
+      "description": "Extract tweet data from the currently focused element in the timeline.",
+      "path": "browser-tools/extract-post.js",
+      "args": {},
+      "returns": {
+        "type": "object",
+        "description": "Tweet text, author, timestamp."
+      }
+    }
+  }
+}

package/skills/ego-browser/learnings/x-com/notes/overview.md

@@ -0,0 +1,18 @@
+# X (Twitter) Overview
+
+## Page structure
+- Main navigation: Left sidebar `[data-testid="AppTabBar"]`
+- Timeline content: `[data-testid="primaryColumn"]`
+- Tweet items: `[data-testid="tweet"]` — each contains text, author, timestamp
+- Compose box: `[data-testid="twaCreateTweetText"]`
+
+## Anti-click-wrap
+- Tweet text is inside `[data-testid="tweetText"]`, click target is `[data-testid="tweet"]`
+- Actions (reply/retweet/like) are inside `div[role="group"]` at the bottom of each tweet card
+
+## Common selectors
+- Tweet text: `[data-testid="tweetText"]`
+- Author name: `[data-testid="User-Name"] span`
+- Timestamp: `time` element with `datetime` attribute
+- Search input: `[data-testid="SearchBox_Search_Input"]`
+- Compose textarea: `[data-testid="twaCreateTweetTextarea"]`

package/skills/ego-browser/learnings/x-com/notes/timeline.md

@@ -0,0 +1,16 @@
+# X Timeline Navigation
+
+## Scrolling timeline
+- Timeline is inside `[data-testid="primaryColumn"]`
+- Posts load lazily as you scroll — use `scrollToBottomUntil` to load more
+- Virtual list: DOM only renders visible articles + buffer
+
+## Extracting posts
+- Query `[data-testid="tweet"]` for post elements
+- Each post has `[data-testid="tweetText"]` for content
+- Author info at `[data-testid="User-Name"]`
+- Always extract in one pass via browser-side closure
+
+## Pinned post
+- Pinned post is the first `[data-testid="tweet"]` in timeline
+- To filter pinned post, skip the first element only when at top of timeline

package/skills/ego-browser/learnings/x-com/tools/search-users.js

@@ -0,0 +1,18 @@
+export async function searchUsers(ctx, args = {}) {
+  const query = args.query || "";
+  if (!query) throw new Error("search query is required");
+
+  await ctx.openOrReuseTab(`https://x.com/search?f=user&q=${encodeURIComponent(query)}`, { wait: true });
+  await ctx.waitForLoad();
+
+  const users = await ctx.js(String.raw`(() => {
+    const results = [...document.querySelectorAll('[data-testid="cellInnerDiv"]')]
+    return results.map(el => ({
+      name: el.querySelector('[data-testid="User-Name"] span')?.innerText?.trim() || '',
+      handle: el.querySelector('[data-testid="User-Name"] a')?.innerText?.trim() || '',
+      followers: el.querySelector('[data-testid="Follow"]')?.previousElementSibling?.innerText?.trim() || '',
+    })).filter(u => u.name || u.handle)
+  })()`);
+
+  return users;
+}

package/skills/ego-browser/learnings/x-com/tools/timeline.js

@@ -0,0 +1,21 @@
+function boundedInteger(value, fallback, max) {
+  const number = value === undefined ? fallback : Number(value);
+  if (!Number.isFinite(number)) return fallback;
+  return Math.max(1, Math.min(max, Math.trunc(number)));
+}
+
+export async function getTimelinePosts(ctx, args = {}) {
+  const maxPosts = boundedInteger(args.maxPosts, 50, 100);
+
+  const posts = await ctx.js(String.raw`(() => {
+    const articles = [...document.querySelectorAll('[data-testid="tweet"]')]
+    return articles.slice(0, ${maxPosts}).map(el => ({
+      text: el.querySelector('[data-testid="tweetText"]')?.innerText?.trim() || '',
+      author: el.querySelector('[data-testid="User-Name"]')?.querySelector('span')?.innerText?.trim() || '',
+      handle: el.querySelector('[data-testid="User-Name"]')?.querySelector('a')?.getAttribute('href') || '',
+      timestamp: el.querySelector('time')?.getAttribute('datetime') || '',
+    }))
+  })()`);
+
+  return posts;
+}

package/skills/ego-browser/references/clearing-state.md

@@ -0,0 +1,64 @@
+# Clearing cookies, cache, and storage
+
+Read this file before clearing any cookie, cache, or storage. These commands look interchangeable but differ in how far they reach. A task space picks a browser profile when it is created, and that profile's cookie jar and HTTP cache are shared with the user's own tabs and with every other task space on the same profile. Measured from inside an agent space on a default profile: the current page saw 1 cookie, the profile held 3478 across 1161 domains.
+
+## What each command reaches
+
+| Command                                           | Reaches               | Getting the state back |
+| ------------------------------------------------- | --------------------- | ---------------------- |
+| `Network.deleteCookies`                           | one named cookie      | sign in to that site   |
+| `Storage.clearDataForOrigin`                      | one origin            | sign in to that site   |
+| `Page.reload` with `ignoreCache: true`            | one Page load         | nothing was lost       |
+| `Network.clearBrowserCookies`                     | **the whole profile** | **nothing you can do** |
+| `Network.clearBrowserCache`                       | **the whole profile** | **nothing you can do** |
+| `Storage.clearCookies` without `browserContextId` | **the whole profile** | **nothing you can do** |
+
+The three profile-wide commands take no scope parameter. There is no narrower way to call them, so reach for a different command rather than a different argument.
+
+Once a profile-wide clear has run you cannot undo it: the agent has no way to recover the sessions it destroyed, and every site on that profile is signed out. Do not run one intending to restore the state afterwards.
+
+## The entry point does not limit the scope
+
+`page.cdp()` selects which target session carries the command. It does not limit what the command touches. `Network.clearBrowserCookies` can only be sent through a Page session — the Network domain does not exist on the browser-level connection — yet it empties the profile's entire cookie jar. A command sent "through this Page" is not a command scoped to this Page.
+
+Do not read a rejection from one entry point as permission to use another. If `task.cdp()` refuses a command, sending the same command through `page.cdp()` does not make it safer; it reaches exactly as far.
+
+## Recipes
+
+Sign-in wall or a session you want anonymous — clear that one site, not the profile:
+
+```js
+await page.cdp("Storage.clearDataForOrigin", {
+  origin: new URL(await page.url()).origin,
+  storageTypes: "cookies",
+});
+```
+
+A stale document or a resource that will not reload — reload past the cache instead of emptying it:
+
+```js
+await page.cdp("Page.reload", { ignoreCache: true });
+```
+
+To drop one site's Cache API entries and service workers, use `storageTypes: "cache_storage,service_workers"` with the same `Storage.clearDataForOrigin` call.
+
+One specific cookie, such as a stale session or search id:
+
+```js
+const { cookies } = await page.cdp("Network.getAllCookies");
+for (const c of cookies.filter((c) => c.domain.includes("example.com"))) {
+  await page.cdp("Network.deleteCookies", {
+    name: c.name,
+    domain: c.domain,
+    path: c.path,
+  });
+}
+```
+
+`Network.deleteCookies` removes `httpOnly` cookies, which `document.cookie` cannot. Needing to clear an `httpOnly` cookie is not a reason to widen the scope to the whole profile.
+
+## Profile-wide clears need user approval
+
+Treat the three profile-wide commands the way you treat `claimTaskSpace()` and `takeOverTaskSpace()`: only after user approval. Before asking, confirm a scoped command cannot do the job — clearing one site's data is almost always what a single-site problem calls for.
+
+When you do need one, tell the user what it costs before running it: how many cookies and domains the profile holds (`Network.getAllCookies`), and which other task spaces share the profile (`listTaskSpaces()` entries carry `profileId` when the runtime reports it). Signing the user out of every site on that profile is not something the agent can put back, and the user may not connect the loss to this task.

package/skills/ego-browser/references/install-macos.md

@@ -0,0 +1,59 @@
+# Install ego lite on macOS
+
+Read `install.md` first; it covers upgrading an older ego lite and the onboarding step shared by every platform. This file has the macOS install steps, the commands that confirm the installation, and macOS troubleshooting.
+
+## Run the install script
+
+The install script lives at `scripts/install.sh` in this skill and supports macOS only (`uname -s` is `Darwin`). It will:
+
+- Download the ego lite installer (a DMG) for your CPU architecture (arm64 / x64).
+- Install `ego lite.app` to `/Applications` (falling back to `~/Applications` when needed).
+- Strip the quarantine attribute to keep Gatekeeper from blocking the first launch.
+- After installing, launch the `ego lite` app.
+
+Run the script (use the script's actual path under this skill's directory):
+
+```bash
+sh skills/ego-browser/scripts/install.sh
+```
+
+After installing, the script opens the ego lite app directly. If ego lite is already installed, the script skips the download and opens the app directly.
+
+After the script opens the ego lite app, the user completes the first-run onboarding in the app (see `install.md`). Onboarding registers the `ego-browser` command on the PATH, usually under `~/.local/bin`.
+
+## After installing: confirm `ego-browser` is available
+
+Once the user has finished onboarding, confirm the command is ready:
+
+```bash
+command -v ego-browser
+```
+
+If it reports that the command isn't found, `~/.local/bin` is most likely not on the current PATH. Fix it temporarily and retry:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+command -v ego-browser
+```
+
+Once the command exists, verify the runtime:
+
+```bash
+ego-browser nodejs <<'EOF'
+console.log('ego-browser ready')
+EOF
+```
+
+Printing `ego-browser ready` means the environment is ready. Finally confirm that the installed ego lite prints its usage guide:
+
+```bash
+ego-browser skill
+```
+
+Then return to the user's original task, as `install.md` describes.
+
+## Troubleshooting
+
+- **Download failed**: the script retries 3 times automatically; if it still fails, it's usually a network issue — have the user check their network and retry.
+- **Gatekeeper still blocks it**: the script already tries to strip quarantine; if the first launch is still blocked, have the user allow ego lite manually under System Settings → Privacy & Security.
+- **Command still unavailable after onboarding**: confirm `~/.local/bin` is on the PATH (see above). Otherwise have the user reopen ego lite, finish onboarding, and retry.

package/skills/ego-browser/references/install-windows.md

@@ -0,0 +1,58 @@
+# Install ego lite on Windows
+
+Read `install.md` first; it covers upgrading an older ego lite and the onboarding step shared by every platform. This file has the Windows install steps, the commands that confirm the installation, and Windows troubleshooting.
+
+## Run the installer
+
+There is no install script for Windows. Have the user download the installer from https://lite.ego.app/ and run it, then open ego lite.
+
+After the app opens, the user completes the first-run onboarding in the app (see `install.md`). Onboarding registers the `ego-browser` command on the PATH. The PATH entry only reaches processes started afterwards, so open a new terminal before checking for the command.
+
+## After installing: confirm `ego-browser` is available
+
+Once the user has finished onboarding, open a new terminal and confirm the command is ready. The command depends on the shell.
+
+PowerShell:
+
+```powershell
+Get-Command ego-browser
+```
+
+cmd:
+
+```bat
+where ego-browser
+```
+
+Git Bash:
+
+```bash
+command -v ego-browser
+```
+
+Once the command exists, verify the runtime. In PowerShell or cmd, where heredoc does not exist:
+
+```powershell
+ego-browser nodejs -e "console.log('ego-browser ready')"
+```
+
+In Git Bash:
+
+```bash
+ego-browser nodejs <<'EOF'
+console.log('ego-browser ready')
+EOF
+```
+
+Printing `ego-browser ready` means the environment is ready. Finally confirm that the installed ego lite prints its usage guide:
+
+```powershell
+ego-browser skill
+```
+
+Then return to the user's original task, as `install.md` describes.
+
+## Troubleshooting
+
+- **SmartScreen blocks the installer**: have the user choose "More info" and then "Run anyway" in the SmartScreen dialog.
+- **Command still unavailable after onboarding**: open a new terminal first, because an existing one keeps the PATH it started with. Otherwise have the user reopen ego lite, finish onboarding, and retry.

package/skills/ego-browser/references/install.md

@@ -0,0 +1,38 @@
+# Install or upgrade ego lite
+
+Read this file only when `ego-browser` is not found, when `ego-browser skill` reports an unknown command, or when the user asks to install ego lite. For day-to-day browser work, run `ego-browser skill` and follow its output.
+
+The ego-browser skill depends on the ego lite browser: the `ego-browser` command is provided by the ego lite app. Once ego lite is installed and you've completed onboarding, no additional setup is normally needed.
+
+ego lite website: https://lite.ego.app/
+
+## Upgrade an older ego lite
+
+If `ego-browser` exists but `ego-browser skill` reports `Unknown command: skill`, the installed ego lite is older than this skill. Ask the user for approval, then run:
+
+```bash
+ego-browser upgrade
+```
+
+If `upgrade` is also an unknown command, reinstall with the steps for the user's operating system. Then continue with "After installing: confirm `ego-browser` is available" in that file.
+
+## Install
+
+The install steps, the commands that confirm the installation, and the troubleshooting differ by operating system. Read the file for the machine you are running on and follow it to the end:
+
+- macOS: [install-macos.md](install-macos.md)
+- Windows: [install-windows.md](install-windows.md)
+- Other platforms: there is no installer. Have the user check https://lite.ego.app/ for a build; if none exists, ego-browser is not available on this machine.
+
+## Onboarding
+
+Onboarding is a step the user completes in the GUI, on every platform:
+
+- Choose to import data from Chrome or another browser as needed.
+- Onboarding registers the `ego-browser` command on the PATH.
+
+After the app opens, wait for the user to confirm they've finished onboarding before continuing. The per-platform file explains how to confirm the command is available afterwards.
+
+## After that, return to the original task
+
+Once the environment is ready, return to the user's original task: run `ego-browser skill` and follow its output.