jorgex-stack 1.0.31 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # JorgeX Stack
 
-Portable multi-agent harness: one configuration source — 15 agents, 17 skills, hooks, persistent memory ([Engram](https://github.com/Gentleman-Programming/engram)), MCPs, and system prompt — installable with one command in **Claude Code**, **Codex CLI**, and **OpenCode**.
+Portable multi-agent harness: one configuration source — 15 agents, 19 skills, hooks, persistent memory ([Engram](https://github.com/Gentleman-Programming/engram)), MCPs, and system prompt — installable with one command in **Claude Code**, **Codex CLI**, and **OpenCode**.
 
 > Inspired by [gentle-ai](https://github.com/Gentleman-Programming/gentle-ai), rebuilt for the JorgeX stack.
 
@@ -78,13 +78,45 @@ Programmatic mode does **not** provide:
 - Any special stdout streaming guarantee — the runtime's normal output rules apply.
 - Telemetry, JSONL streams, or runtime token-budget enforcement.
 
+### Browser automation
+
+Browser automation is opt-in and explicit. The legacy `agent-browser` integration has been removed; rely on the two surfaces below.
+
+- **Playwright CLI** (recommended): `@playwright/cli@0.1.17` plus a vendored skill that ships pinned with the stack. The skill is loaded on demand, contributes no permanent MCP schemas, and declares `allowed-tools: Bash(playwright-cli:*)` only (no `Bash(pnpm:*)`). This is the skill's declaration, not a security boundary: effective permissions still come from the adapter/runtime, and OpenCode/full-bash may expose broader Bash or other capabilities. See [docs/references/browser-automation.md](docs/references/browser-automation.md) for the full lifecycle, the security profile and troubleshooting.
+- **Chrome DevTools MCP** (advanced diagnostics, opt-in): exposes ~29 tools and ~5,800–7,700 tokens of schemas in full mode. Disabled by default, selected per runtime, version-pinned, and launched with a fixed argv `pnpm dlx chrome-devtools-mcp@1.6.0 --isolated --redact-network-headers --no-performance-crux --no-usage-statistics`. `--isolated` starts Chrome with an ephemeral, isolated profile that is deleted when Chrome closes (no persistent dedicated profile, no shared cookies/extensions/sessions with your personal Chrome); `--redact-network-headers` redacts sensitive headers in captured network traffic, but not request/response bodies, which may contain tokens or PII. Avoid authenticated sessions or sensitive data, or disable network capture manually outside the stack when needed. `--no-performance-crux` disables CrUX reporting; `--no-usage-statistics` disables telemetry. `--slim` and Playwright MCP are intentionally excluded.
+
+Setup that respects the zero-secrets, pnpm-only and explicit-consent rules:
+
+```bash
+# Interactive (TTY): the install prompt suggests Playwright CLI but defaults to "No" (opt-in consent). Press `y` to install.
+pnpm dlx jorgex-stack install
+
+# Non-interactive / agent: --playwright authorizes the global install.
+pnpm dlx jorgex-stack install --yes --playwright
+
+# Enable Chrome DevTools MCP explicitly per runtime.
+pnpm dlx jorgex-stack install --devtools
+pnpm dlx jorgex-stack install --no-devtools
+```
+
+Under the hood, `--playwright` runs two `pnpm` argv-only plans back to back: `pnpm add --global @playwright/cli@0.1.17` (the package) and then `pnpm dlx @playwright/cli@0.1.17 install-browser` (the browser binary cache). Removal is `pnpm remove --global @playwright/cli` (no version suffix). If installation fails, the error identifies the failed phase — global package, browser download, or preference persistence — and recommends `jorgex-stack install --playwright`; the preference is not marked enabled unless the complete plan succeeds.
+
+Daily operation:
+
+- `sync` reconciles configuration without installing global tools or browsers; if Playwright is enabled but the binary or browser cache is `missing`, it warns and points to `install --playwright`; if the cache is `unreadable`, the warning includes its resolved path and filesystem error code. The cache probe retains the path for both states and an error code when the filesystem provides one. Under `--target-dir`, `sync`/`install`/`uninstall` never read or write the real browser state (`~/.jorgex-stack/playwright-cli.json` and `~/.jorgex-stack/devtools-mcp.json` are untouched, `detectPlaywrightCli()` is not called, no MCP ownership is persisted).
+- `doctor` reports the Playwright CLI state (`disabled`, `healthy`, `missing:package`, `missing:browser`, `unreadable`, `broken`, `outdated`) without opening sites or repairing state. An `unreadable` browser cache includes its exact path and filesystem error code so permissions or another local cause can be investigated. If either preference file is corrupt, doctor prints the exact path and the remedy (`Corrige o borra ese archivo antes de reintentar`) before any other browser check; in that case `install`/`uninstall`/`update`/`update --check` will abort with exit 1 until the file is fixed, so the corruption cannot be reconciled destructively.
+- `update --check` only inspects Playwright CLI when its preference is `enabled` (a binary appearing in `PATH` is not consent). It compares the installed version against the approved pin `0.1.17` — it does not consult npm latest, and a Playwright CLI binary-only update does not require `sync` afterwards.
+- `uninstall` preserves the global `@playwright/cli` package and all browser data by default; `--remove-playwright` removes the package only (never the browser cache, profiles, cookies, storage state, traces, screenshots or videos). If `pnpm remove --global @playwright/cli` exits non-zero, `uninstall` reports the failure instead of a success outro. For DevTools MCP, ownership is released only after the corresponding unmerge is applied; if no unmerge action is written, the ownership marker is preserved for a later retry.
+- `install`/`sync` also inject (and `disable`/`uninstall` remove) a marked section `<!-- jorgex:browser -->` in `AGENTS.md` (OpenCode, Codex) or `CLAUDE.md` (Claude Code): the section only contains Playwright guidance when its setup succeeded, and DevTools guidance only in the runtimes that selected it; the rest of the file outside the markers is preserved. `--target-dir` never reads the real preferences, so by default no section is emitted in target-dir runs — but explicit flags like `--devtools` simulate the MCP entry (and the corresponding DevTools block of the section) inside the temp target without touching the real global state, and `install --dry-run --playwright` projects the Playwright section into the plan preview without installing anything. If the post-setup reconciliation of the system prompt leaves the section in a partial state, the CLI exits non-zero and recommends `jorgex-stack sync` to repair it; the package and the preference stay installed. See [docs/references/browser-automation.md](docs/references/browser-automation.md) §2.7 for the full lifecycle.
+
 ### Update: Interactive Flow
 
-`update` manages two sources for the end user, plus a maintainer-only one:
+`update` manages three sources for the end user, plus a maintainer-only one:
 
 1. **Stack** (jorgex-stack): detects whether it is a git clone or a global install, then offers an update with confirmation.
 2. **Engram** (binary): detects the installed version and offers an update through the **native channel** (brew -> `go install` -> release URL). Nothing needs to be stopped: as in upstream macOS/Linux, live processes keep using the old version until clients restart; on Windows, the in-use `.exe` is rotated by rename before installation. **Automatic DB backup before updating**. The database and memories are never touched.
-3. **Vendored skills** (maintainer only): third-party skills ship **pinned** with the stack version, so the installed package never reaches out to their upstreams. Only when running from a git clone (`pnpm cli update`) does `update` scan the upstreams in `upstreams.json`, download to a temp directory, **show a mandatory diff**, and ask for confirmation — so the review and re-pin persist in the repo and get published. Skills with local changes (`modified: true`) warn and require double confirmation.
+3. **Playwright CLI** (only when explicitly enabled): compares the detected binary with the approved bundle pin and offers to realign it with explicit confirmation. The realignment re-applies **both** plans — `pnpm add --global @playwright/cli@0.1.17` (package) and `pnpm dlx @playwright/cli@0.1.17 install-browser` (browser cache) — and fails closed if either step returns non-zero. The error identifies whether the package-update or browser-download phase failed and recommends `jorgex-stack install --playwright` to retry both; a Playwright update does not require `sync`.
+4. **Vendored skills** (maintainer only): third-party skills ship **pinned** with the stack version, so the installed package never reaches out to their upstreams. Only when running from a git clone (`pnpm cli update`) does `update` scan the upstreams in `upstreams.json`, download to a temp directory, **show a mandatory diff**, and ask for confirmation — so the review and re-pin persist in the repo and get published. Skills with local changes (`modified: true`) warn and require double confirmation.
 
 Usage:
 - `update --check`: scans versions without applying changes.