From 77804e3b0a24df1cec3d78472915e7dc30bbd422 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Mon, 16 Mar 2026 10:51:12 -0500 Subject: [PATCH] docs: update CONTRIBUTING.md and BROWSER.md for v0.4.2 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CONTRIBUTING.md: update contributor mode description — now describes periodic 0-10 reflection loop instead of passive friction detection. BROWSER.md: add js/eval async documentation — await expressions are auto-wrapped in async context, single-line eval returns values directly. Co-Authored-By: Claude Opus 4.6 --- BROWSER.md | 12 ++++++++++++ CONTRIBUTING.md | 10 ++++++---- 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/BROWSER.md b/BROWSER.md index 2d828ebe..df4a6d1d 100644 --- a/BROWSER.md +++ b/BROWSER.md @@ -127,6 +127,18 @@ The `console`, `network`, and `dialog` commands read from the in-memory buffers, Dialogs (alert, confirm, prompt) are auto-accepted by default to prevent browser lockup. The `dialog-accept` and `dialog-dismiss` commands control this behavior. For prompts, `dialog-accept ` provides the response text. All dialogs are logged to the dialog buffer with type, message, and action taken. +### JavaScript execution (`js` and `eval`) + +`js` runs a single expression, `eval` runs a JS file. Both support `await` — expressions containing `await` are automatically wrapped in an async context: + +```bash +$B js "await fetch('/api/data').then(r => r.json())" # works +$B js "document.title" # also works (no wrapping needed) +$B eval my-script.js # file with await works too +``` + +For `eval` files, single-line files return the expression value directly. Multi-line files need explicit `return` when using `await`. Comments containing "await" don't trigger wrapping. + ### Multi-workspace support Each workspace gets its own isolated browser instance with its own Chromium process, tabs, cookies, and logs. State is stored in `.gstack/` inside the project root (detected via `git rev-parse --show-toplevel`). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b06b837e..4af2e889 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,9 +22,11 @@ bin/dev-teardown # deactivate — back to your global install ## Contributor mode -Contributor mode is for people who want to fix gstack when it annoys them. Enable it -and Claude Code will automatically log issues to `~/.gstack/contributor-logs/` as you -work — what you were doing, what went wrong, repro steps, raw output. +Contributor mode turns gstack into a self-improving tool. Enable it and Claude Code +will periodically reflect on its gstack experience — rating it 0-10 at the end of +each major workflow step. When something isn't a 10, it thinks about why and files +a report to `~/.gstack/contributor-logs/` with what happened, repro steps, and what +would make it better. ```bash ~/.claude/skills/gstack/bin/gstack-config set gstack_contributor true @@ -36,7 +38,7 @@ the issue, fix it, and open a PR. ### The contributor workflow -1. **Hit friction while using gstack** — contributor mode logs it automatically +1. **Use gstack normally** — contributor mode reflects and logs issues automatically 2. **Check your logs:** `ls ~/.gstack/contributor-logs/` 3. **Fork and clone gstack** (if you haven't already) 4. **Symlink your fork into the project where you hit the bug:**