milaidy 1.0.0

package/docs/tools/browser-linux-troubleshooting.md

@@ -0,0 +1,139 @@
+---
+summary: "Fix Chrome/Brave/Edge/Chromium CDP startup issues for Milaidy browser control on Linux"
+read_when: "Browser control fails on Linux, especially with snap Chromium"
+title: "Browser Troubleshooting"
+---
+
+# Browser Troubleshooting (Linux)
+
+## Problem: "Failed to start Chrome CDP on port 18800"
+
+Milaidy's browser control server fails to launch Chrome/Brave/Edge/Chromium with the error:
+
+```
+{"error":"Error: Failed to start Chrome CDP on port 18800 for profile \"milaidy\"."}
+```
+
+### Root Cause
+
+On Ubuntu (and many Linux distros), the default Chromium installation is a **snap package**. Snap's AppArmor confinement interferes with how Milaidy spawns and monitors the browser process.
+
+The `apt install chromium` command installs a stub package that redirects to snap:
+
+```
+Note, selecting 'chromium-browser' instead of 'chromium'
+chromium-browser is already the newest version (2:1snap1-0ubuntu2).
+```
+
+This is NOT a real browser — it's just a wrapper.
+
+### Solution 1: Install Google Chrome (Recommended)
+
+Install the official Google Chrome `.deb` package, which is not sandboxed by snap:
+
+```bash
+wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
+sudo dpkg -i google-chrome-stable_current_amd64.deb
+sudo apt --fix-broken install -y  # if there are dependency errors
+```
+
+Then update your Milaidy config (`~/.milaidy/milaidy.json`):
+
+```json
+{
+  "browser": {
+    "enabled": true,
+    "executablePath": "/usr/bin/google-chrome-stable",
+    "headless": true,
+    "noSandbox": true
+  }
+}
+```
+
+### Solution 2: Use Snap Chromium with Attach-Only Mode
+
+If you must use snap Chromium, configure Milaidy to attach to a manually-started browser:
+
+1. Update config:
+
+```json
+{
+  "browser": {
+    "enabled": true,
+    "attachOnly": true,
+    "headless": true,
+    "noSandbox": true
+  }
+}
+```
+
+2. Start Chromium manually:
+
+```bash
+chromium-browser --headless --no-sandbox --disable-gpu \
+  --remote-debugging-port=18800 \
+  --user-data-dir=$HOME/.milaidy/browser/milaidy/user-data \
+  about:blank &
+```
+
+3. Optionally create a systemd user service to auto-start Chrome:
+
+```ini
+# ~/.config/systemd/user/milaidy-browser.service
+[Unit]
+Description=Milaidy Browser (Chrome CDP)
+After=network.target
+
+[Service]
+ExecStart=/snap/bin/chromium --headless --no-sandbox --disable-gpu --remote-debugging-port=18800 --user-data-dir=%h/.milaidy/browser/milaidy/user-data about:blank
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+```
+
+Enable with: `systemctl --user enable --now milaidy-browser.service`
+
+### Verifying the Browser Works
+
+Check status:
+
+```bash
+curl -s http://127.0.0.1:18791/ | jq '{running, pid, chosenBrowser}'
+```
+
+Test browsing:
+
+```bash
+curl -s -X POST http://127.0.0.1:18791/start
+curl -s http://127.0.0.1:18791/tabs
+```
+
+### Config Reference
+
+| Option                   | Description                                                          | Default                                                     |
+| ------------------------ | -------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `browser.enabled`        | Enable browser control                                               | `true`                                                      |
+| `browser.executablePath` | Path to a Chromium-based browser binary (Chrome/Brave/Edge/Chromium) | auto-detected (prefers default browser when Chromium-based) |
+| `browser.headless`       | Run without GUI                                                      | `false`                                                     |
+| `browser.noSandbox`      | Add `--no-sandbox` flag (needed for some Linux setups)               | `false`                                                     |
+| `browser.attachOnly`     | Don't launch browser, only attach to existing                        | `false`                                                     |
+| `browser.cdpPort`        | Chrome DevTools Protocol port                                        | `18800`                                                     |
+
+### Problem: "Chrome extension relay is running, but no tab is connected"
+
+You’re using the `chrome` profile (extension relay). It expects the Milaidy
+browser extension to be attached to a live tab.
+
+Fix options:
+
+1. **Use the managed browser:** `milaidy browser start --browser-profile milaidy`
+   (or set `browser.defaultProfile: "milaidy"`).
+2. **Use the extension relay:** install the extension, open a tab, and click the
+   Milaidy extension icon to attach it.
+
+Notes:
+
+- The `chrome` profile uses your **system default Chromium browser** when possible.
+- Local `milaidy` profiles auto-assign `cdpPort`/`cdpUrl`; only set those for remote CDP.

package/docs/tools/browser-login.md

@@ -0,0 +1,68 @@
+---
+summary: "Manual logins for browser automation + X/Twitter posting"
+read_when:
+  - You need to log into sites for browser automation
+  - You want to post updates to X/Twitter
+title: "Browser Login"
+---
+
+# Browser login + X/Twitter posting
+
+## Manual login (recommended)
+
+When a site requires login, **sign in manually** in the **host** browser profile (the milaidy browser).
+
+Do **not** give the model your credentials. Automated logins often trigger anti‑bot defenses and can lock the account.
+
+Back to the main browser docs: [Browser](/tools/browser).
+
+## Which Chrome profile is used?
+
+Milaidy controls a **dedicated Chrome profile** (named `milaidy`, orange‑tinted UI). This is separate from your daily browser profile.
+
+Two easy ways to access it:
+
+1. **Ask the agent to open the browser** and then log in yourself.
+2. **Open it via CLI**:
+
+```bash
+milaidy browser start
+milaidy browser open https://x.com
+```
+
+If you have multiple profiles, pass `--browser-profile <name>` (the default is `milaidy`).
+
+## X/Twitter: recommended flow
+
+- **Read/search/threads:** use the **bird** CLI skill (no browser, stable).
+  - Repo: https://github.com/steipete/bird
+- **Post updates:** use the **host** browser (manual login).
+
+## Sandboxing + host browser access
+
+Sandboxed browser sessions are **more likely** to trigger bot detection. For X/Twitter (and other strict sites), prefer the **host** browser.
+
+If the agent is sandboxed, the browser tool defaults to the sandbox. To allow host control:
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        mode: "non-main",
+        browser: {
+          allowHostControl: true,
+        },
+      },
+    },
+  },
+}
+```
+
+Then target the host browser:
+
+```bash
+milaidy browser open https://x.com --browser-profile milaidy --target host
+```
+
+Or disable sandboxing for the agent that posts updates.