mirror of
https://github.com/garrytan/gstack.git
synced 2026-09-10 15:09:00 +02:00
v1.81.0.0 feat: Aside is the browser gstack drives first; every browsing skill, the PDF/diagram renderer, and web research; the bundled browser stays the automatic fallback (#2810)
* feat(aside): browser-driver contract, cookbook, research and fallback resolvers
{{ASIDE_SETUP}} (readiness probe + ten rules for driving the user's real browser), {{ASIDE_COOKBOOK}} (script shapes verified live against Aside CLI 1.26: one flow per aside repl script, CDP console hook before navigation, evidence lines, session-directory artifact handoff, GSTACK_STEP_OK sentinel), {{ASIDE_RESEARCH}} (research through aside exec, WebSearch when Aside is absent, knowledge otherwise) and {{BROWSE_FALLBACK}} (the fifteen-row Aside-step to $B-command table plus the rules that differ, so every browsing skill keeps working on gstack's own headless browser). test/aside-driver.test.ts pins the sentences and asserts every browsing skill carries the Aside block followed by the fallback; test/helpers/aside-available.ts is the shared live-Aside probe.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* feat(render): Aside-first local-HTML renderer with the bundled browser as fallback
lib/aside-render.ts serves the HTML's directory on loopback (Aside refuses file:// URLs), opens it with waitUntil load, prints through CDP Page.printToPDF so tagged output, outlines, header/footer templates and page numbers survive, emulates device metrics for sized screenshots, and writes in-page evaluations to files; when Aside is absent it runs the same spec through the browse daemon (newtab, load, js, pdf, screenshot, closetab) and reports ENGINE=aside|browse. bin/gstack-render.ts is the CLI skill templates call. lib/claude-bin.ts and lib/error-handling.ts become the canonical copies (browse/src re-exports them).
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* refactor(browse): /browse drives Aside first, with the $B reference behind the fallback
Contract, cookbook, mode choice (aside repl by default, aside exec for reading), report format, the fallback section, and the full command reference carved on demand.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* refactor(qa): /qa and /qa-only drive Aside, fall back to $B
QA_METHODOLOGY runs every phase as Aside scripts (orient, explore, document, re-test, mobile viewport via CDP emulation, links via HEAD fetch); the authenticate phase is 'you are already signed in'; a 13th rule requires consent before mutating actions on non-local targets; the fallback section translates each step onto $B. The qa E2E tests run on whichever engine is present.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* refactor(design): design-review, design-consultation, design-shotgun, plan-design-review, design-html drive Aside
Design-system extraction is one script printing FONTS/COLORS/HEADINGS/TOUCH_TARGETS/NAV; competitor research confirms the exact URLs before opening them in the real browser and runs on the bundled browser when Aside is absent; design-html's viewport screenshots, sketches and comparison boards render through gstack-render.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* refactor(deploy): benchmark, canary, land-and-deploy Step 7, devex-review drive Aside
One aside repl script per page prints NAV/PAINT/LCP/RESOURCES/SCRIPTS/CSS/SUMMARY (benchmark), CONSOLE_ERRORS/NAV/TEXT + screenshot (canary, re-run every 60s), and the post-deploy check reads responseStatus from the navigation entry; each carries the $B fallback.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* feat(third-party-actions): Aside is the recommended driver; gstack's visible browser stays the fallback
The readiness probe is lifted from {{ASIDE_SETUP}} at gen time (byte-identity pinned) and rule 3 points at browse/SKILL.md for how to drive; the consent question offers Aside first and gstack's own visible browser (handoff/resume for sign-in) as the fallback, as v1.72 framed it.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* refactor(scrape): /scrape reads pages through Aside; the browser-skills runtime rides the fallback
Look-then-extract scripts build the JSON inside the page and print it between JSON_START/JSON_END; aside exec for fuzzy intents; on the $B fallback the browser-skills match/prototype flow and /skillify apply as before.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* refactor(make-pdf): print through Aside first, the bundled browser otherwise
asideClient.ts replaces the direct $B client with one render() call per PDF (the exact option mapping the browse pdf command had: paper, margins, header/footer/page numbers, tagged, outline, printBackground, preferCSSPageSize, Paged.js wait); the diagram pre-pass, oversized-image downscale and DOCX rasters each run as one render script with per-fence try/catch; exit 4 now means no browser is available and names both remedies; $P setup reports which engine it found. The e2e gates run on whichever engine is present, so the Linux lane exercises the fallback.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* refactor(diagram): the triplet is one gstack-render call
SVG, PNG and excalidraw from one invocation over the content-addressed bundle staged under /tmp/gstack-render; every diagram type gets an excalidraw export; gstack-render picks the engine and prints ENGINE=; the diagram E2E gates on either engine.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* feat(research): web research runs in Aside first, WebSearch second
The planning, review, design, security and investigate skills research through {{ASIDE_RESEARCH}}; WebSearch stays in allowed-tools as the fallback; testing.ts's bootstrap step follows; skeleton ceilings ratcheted for the research block.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* feat(setup,gen-skill-docs): prune renders of skills that no longer exist
setup gains _prune_stale_generated for every host tree and the doc generator removes gstack-* output dirs it did not write, so a skill removed from the source tree can never linger in an install.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* test: registries, budgets and suite reconciled for Aside-first with the $B fallback
Touchfiles + E2E tiers gain the Aside keys, coverage matrix and eval baselines updated, size budget re-baselined to parity-baseline-v1.80.0.0.json (the contract plus fallback ride in every browsing skill), parity ceilings ratcheted with measured values, LLM-judge prompts and the E2E fixtures speak Aside-first, browse-fallback.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* docs: Aside first, gstack browser fallback
README, BROWSER.md, docs/, CONTRIBUTING, CLAUDE.md, ARCHITECTURE, AGENTS.md, TODOS and the root router describe the one product story: Aside is the browser gstack drives first; the bundled headless browser is the automatic fallback (Linux, Windows, app closed) where cookie import, GStack Browser, pair-agent and browser-skills still apply.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* chore: regenerate SKILL.md docs, llms.txt, agents digest, ship goldens, context-budget fixture
bun run gen:skill-docs over the templates; goldens re-rendered; context-budget ceilings recaptured.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* v1.80.0.0: Aside is the browser gstack drives first; the bundled browser is the fallback
MINOR: new capability across ten skills, the renderer and research; nothing removed. CHANGELOG release summary + itemized changes; VERSION 1.80.0.0; package.json 1.80.0.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* docs(todos): file non-Claude host ownership-gate and version-heading pin follow-ups
Two follow-ups from the /plan-ceo-review + /plan-eng-review pass on merging
PR #2804 with main's v1.80.0.0 ownership gate: bring the Codex/Factory/
OpenCode/Cursor/Kiro copy loops and the stale-render prune under the
.gstack-owned marker rule, and a free test pinning that the CHANGELOG top
heading equals VERSION (the collision that git cannot see).
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* fix: pre-landing review fixes for the Aside-first branch
Review army + adversarial passes (Claude and Codex) on the merged branch:
setup
- _prune_stale_generated scans the host dirs too (the generator already
removed the render before setup ran, so the host branch was dead), skips
symlinks in the render tree (rm -rf on a slash-terminated link empties its
target), removes a host symlink only when it resolves into gstack, cleans a
bannered real dir through _cleanup_weak_dir, recognizes frontmatter-renamed
skills, and logs through log. The always-run codex render passes every host
dir that may link to it.
- NEEDS_BUILD checks all three binaries (with $_EXE) and lib/ sources; the
browser hint and the bootstrap summary honor GSTACK_SKIP_ASIDE, treat a
requested skip as a request, and derive one skill list.
lib/aside-render.ts + bin/gstack-render.ts
- The loopback server carries a per-render secret path, checks containment on
the real path (symlink escapes are 403), and rejects malformed encoding.
- Inline eval results are one base64 line, so page text cannot forge
ASIDE_DIR= or the sentinel; the last ASIDE_DIR wins.
- runProc escalates SIGTERM to SIGKILL, bounds every wait, and clears every
timer (an uncleared one kept gstack-render alive after printing OK).
- renderTmpDir refuses a shared /tmp name owned by someone else; the work dir
and server are created inside try; goto's budget follows the render budget.
- probeAside classifies a present-but-failing CLI as ASIDE_NOT_RUNNING like
the skills' bash probe; render() retries on gstack's own browser when Aside
could not start or its private CDP bridge is gone (never on a page error
or a timeout of a running script); the CLI reports the engine that actually
rendered, exits 0 on --help, rejects non-numeric flags, documents
--wait-timeout, fences EVAL/PAGE_ERRORS as untrusted content, and names the
daemon's cookie-import JS lock remedy.
- The browse path passes --scale only when asked (a scale change rebuilds
the daemon context) and restores the viewport after a sized screenshot.
resolvers / templates
- The bash probe honors GSTACK_SKIP_ASIDE and has a perl deadline on stock
macOS; .local is no longer LOCAL (mDNS); same-origin filters compare parsed
origins; link status is HEAD-checked only on LOCAL targets; every
aside exec goes through the receipted _aside_exec prelude
({{ASIDE_EXEC_PRELUDE}}), including nine template blocks that called it
bare; the design sketch and diagram staging use private directories.
- The generator prunes only bannered renders and never a host whose
generation failed.
Docs, stale comments and dead code cleaned; goldens re-rendered; tests
updated and added for every behavior above.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* test: coverage for the render CLI, setup rebuild check, make-pdf exit codes, and prose $B spans
New free tests from the ship coverage audit: test/gstack-render-cli.test.ts
(argv guards, --help, output contract with a fake daemon, failure and
serve-root paths, no-browser case, prompt exit), test/setup-needs-build.test.ts
(every binary and source set flips NEEDS_BUILD, Windows suffixes),
make-pdf/test/cli-exit-codes.test.ts and setup-smoke.test.ts (error to exit
code mapping, runSetup stages, renderPdf's engine), and prose-span cases for
extractBrowseCommands in test/skill-parser.test.ts.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* docs: CHANGELOG and TODOS cover the review fixes (v1.81.0.0)
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* docs: sync project docs with the v1.81.0.0 review fixes
BROWSER.md, ARCHITECTURE.md, CONTRIBUTING.md, README.md, CLAUDE.md,
docs/TESTING_INTERNALS.md and docs/PROJECT_STRUCTURE.md now describe the
shipped renderer and setup: the loopback render server's per-render secret
path and real-path containment, ENGINE= naming the engine that actually
rendered (mid-run retry on gstack's own browser), EVAL/PAGE_ERRORS fenced as
untrusted content, --wait-timeout and the CLI's argv guards, the receipted
_aside_exec prelude ({{ASIDE_EXEC_PRELUDE}} in the placeholder table), the
LOCAL host rule without .local, LOCAL-only HEAD checks in the links script,
GSTACK_SKIP_ASIDE across probe/renderer/setup, the ownership-gated
retired-skill prune, the widened NEEDS_BUILD check, and the new free tests
(gstack-render-cli, setup-prune-stale-generated, setup-browser-hint,
setup-needs-build, make-pdf cli-exit-codes and setup-smoke).
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* docs: CHANGELOG states the precise mid-run retry rule
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* fix(test): skill-e2e-bws slices the $B setup block from the Browser fallback section
browse/SKILL.md no longer has '## SETUP' / '## Core QA Patterns' (Aside is the
primary driver; the $B block moved under 'Browser fallback'), so the gate test
sliced an empty block and handed the agent nothing to run. Anchor on
'### Find the `$B` binary' up to the next heading. 7/7 pass.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* fix(test): gate POSIX-only fixtures off Windows
windows-free-tests: the gstack-render CLI tests drive a shebang fake browse
that CreateProcess cannot exec, and two NEEDS_BUILD cases assert an execute
bit and a bare-name miss that MSYS bash does not have (test -x ignores mode
bits and resolves design -> design.exe). Those describes and cases now
self-skip on win32; argument guards, --help, the no-browser case, and every
other rebuild-check case still run there.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* fix(render): runProc waits for the exit code until the kill deadline; newtab retries once on a cold daemon
A process whose pipes have reached EOF is exiting, but runProc gave the exit
code only five seconds to arrive and then returned null, which run() reports
as a failed command. Under CI's six-shard load one such render failed with the
artifact already written. The SIGTERM/SIGKILL timers already bound the wait,
so the exit race now runs to the kill deadline.
The first CLI call auto-starts the browse daemon; on a cold start it can
answer 'Unable to connect' once while the server is still coming up. That
single case is retried after 1.5s; every other newtab failure is not.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* test(aside-render): warm the daemon before live fallback cases; failures name the render error
- Live fallback cases run 'goto about:blank' up to twice before asserting and
skip (never fail) when the daemon cannot come up.
- expectOk() puts r.error and the browse transcript into the assertion so a
failed render is diagnosable from the CI log.
- The argv-contract cases dump the fake's log on a miss.
- File default timeout is 30s: the subject is the CLI contract, not latency.
- Two cases pin the cold-daemon newtab retry and that other errors are not
retried.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* docs: CHANGELOG notes the cold-start tolerance of the bundled-browser renderer
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---------
Co-authored-by: Sina <sdroid674+github@gmail.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Garry Tan
co-authored by
Claude Fable 5.1
Sina
Claude Fable 5.1
Sina
parent
c241216637
commit
0530392821
@@ -1,5 +1,7 @@
|
||||
# Browser / sidebar / server internals
|
||||
|
||||
> **Scope:** this is the internals reference for gstack's own browser engine — the `browse` daemon, GStack Browser, the sidebar extension. That engine is the automatic **fallback** when the Aside browser is not installed or not running (Linux, Windows, a closed Aside app); Aside is what every skill drives first. The Aside contract lives in `scripts/resolvers/aside.ts` and [BROWSER.md](../BROWSER.md).
|
||||
|
||||
Moved verbatim from CLAUDE.md (token-load reduction). These are the
|
||||
load-bearing invariants for `browse/src/server.ts`, the Chrome extension,
|
||||
the sidebar PTY, SSE endpoints, CDP sessions, and the sidebar security
|
||||
|
||||
+1
-1
@@ -110,7 +110,7 @@ Published to ClawHub. Install with `clawhub install`:
|
||||
|
||||
Source lives in `openclaw/skills/` in the gstack repo. These are hand-crafted
|
||||
adaptations of the gstack methodology for OpenClaw's conversational context.
|
||||
No gstack infrastructure (no browse, no telemetry, no preamble).
|
||||
No gstack infrastructure (no browser, no telemetry, no preamble).
|
||||
|
||||
## Spawned session detection
|
||||
|
||||
|
||||
@@ -6,7 +6,8 @@ Moved verbatim from CLAUDE.md (token-load reduction).
|
||||
|
||||
```
|
||||
gstack/
|
||||
├── browse/ # Headless browser CLI (Playwright)
|
||||
├── browse/ # /browse skill + gstack's own headless browser engine (Playwright) — the fallback when Aside is absent
|
||||
│ ├── SKILL.md.tmpl # /browse: Aside first ({{ASIDE_SETUP}} + cookbook), $B fallback
|
||||
│ ├── src/ # CLI + server + commands
|
||||
│ │ ├── commands.ts # Command registry (single source of truth)
|
||||
│ │ └── snapshot.ts # SNAPSHOT_FLAGS metadata array
|
||||
@@ -24,7 +25,7 @@ gstack/
|
||||
│ ├── gen-agents-digest.ts # Generates the budget-capped instruction-tier digest (agents-digest/)
|
||||
│ ├── host-config.ts # HostConfig interface + validator
|
||||
│ ├── host-config-export.ts # Shell bridge for setup script
|
||||
│ ├── resolvers/ # Template resolver modules (preamble, design, review, gbrain, etc.)
|
||||
│ ├── resolvers/ # Template resolver modules (preamble, aside = the Aside driver contract + research, browse = $B fallback setup + command reference, design, review, gbrain, etc.)
|
||||
│ ├── skill-check.ts # Health dashboard
|
||||
│ ├── test-free-shards.ts # Strict parallel free-suite runner (GSTACK_FREE_JOBS, opt-in flaky retry)
|
||||
│ ├── test-paid-shards.ts # Sharded paid-tier runner (one Bun process per shard)
|
||||
@@ -32,11 +33,14 @@ gstack/
|
||||
│ ├── sandbox-doctor.sh # One-command cloud-sandbox fixer: makes the free suite run green
|
||||
│ └── dev-skill.ts # Watch mode
|
||||
├── test/ # Skill validation + eval tests
|
||||
│ ├── helpers/ # skill-parser.ts, session-runner.ts, llm-judge.ts, eval-store.ts
|
||||
│ ├── helpers/ # skill-parser.ts, session-runner.ts, llm-judge.ts, eval-store.ts, aside-available.ts (Aside self-skip probe)
|
||||
│ ├── fixtures/ # Ground truth JSON, planted-bug fixtures, eval baselines
|
||||
│ ├── aside-driver.test.ts # Tier 1: pins the {{ASIDE_SETUP}} contract sentences + the fallback hand-off
|
||||
│ ├── aside-render.test.ts # Tier 1 pins + fake-executable runs on both engines + a live Aside render (self-skips without Aside)
|
||||
│ ├── gstack-render-cli.test.ts # Tier 1: bin/gstack-render.ts argv guards + output contract against a fake daemon
|
||||
│ ├── skill-validation.test.ts # Tier 1: static validation (free, <1s)
|
||||
│ ├── gen-skill-docs.test.ts # Tier 1: generator quality (free, <1s)
|
||||
│ ├── setup-*.test.ts, relink.test.ts, hook-scripts.test.ts # Tier 1: setup linker ownership + Chromium bootstrap (anchor-sliced from setup), gstack-relink, PreToolUse hooks (free)
|
||||
│ ├── setup-*.test.ts, relink.test.ts, hook-scripts.test.ts # Tier 1: setup linker ownership, retired-skill prune, browser hint, rebuild check + Chromium bootstrap (anchor-sliced from setup), gstack-relink, PreToolUse hooks (free)
|
||||
│ ├── skill-llm-eval.test.ts # Tier 3: LLM-as-judge (~$0.15/run)
|
||||
│ └── skill-e2e-*.test.ts # Tier 2: E2E via claude -p (~$3.85/run, split by category)
|
||||
├── qa-only/ # /qa-only skill (report-only QA, no fixes)
|
||||
@@ -59,7 +63,7 @@ gstack/
|
||||
├── freeze/ # /freeze skill; bin/check-freeze.sh (PreToolUse edit-boundary hook; sources careful/bin/hook-extract.sh, fails closed)
|
||||
├── guard/, unfreeze/ # /guard (careful + freeze in one), /unfreeze
|
||||
├── gstack-upgrade/ # /gstack-upgrade skill + migrations/ (run after ./setup during an upgrade)
|
||||
├── bin/ # CLI utilities (gstack-repo-mode, gstack-slug, gstack-config, gstack-wtree, gstack-evidence, gstack-issue-guard, gstack-relink, etc.)
|
||||
├── bin/ # CLI utilities (gstack-render.ts = render a local HTML file through Aside or the engine, gstack-repo-mode, gstack-slug, gstack-config, gstack-wtree, gstack-evidence, gstack-issue-guard, gstack-relink, etc.)
|
||||
├── document-release/ # /document-release skill (post-ship doc updates + Diataxis coverage map)
|
||||
├── document-generate/ # /document-generate skill (Diataxis doc generator: tutorial/how-to/reference/explanation)
|
||||
├── cso/ # /cso skill (OWASP Top 10 + STRIDE security audit)
|
||||
@@ -67,13 +71,18 @@ gstack/
|
||||
├── design-shotgun/ # /design-shotgun skill (visual design exploration)
|
||||
├── open-gstack-browser/ # /open-gstack-browser skill (launch GStack Browser)
|
||||
├── connect-chrome/ # symlink → open-gstack-browser (backwards compat)
|
||||
├── setup-browser-cookies/, pair-agent/, skillify/ # Fallback-engine skills (cookie import, shared-browser tunnel, codify a /scrape)
|
||||
├── qa/, qa-only/, scrape/ # Browser skills (with design-review/, canary/, benchmark/) — Aside first via {{ASIDE_SETUP}}, $B when Aside is absent
|
||||
├── make-pdf/ # /make-pdf skill + compiled `pdf` binary (embeds lib/aside-render.ts); test/ = unit tests (cli-exit-codes, setup-smoke, render) + e2e/*-gate.test.ts on whichever engine resolves
|
||||
├── diagram/ # /diagram skill (mermaid → SVG/PNG/.excalidraw through bin/gstack-render.ts + lib/diagram-render)
|
||||
├── design/ # Design binary CLI (GPT Image API)
|
||||
│ ├── src/ # CLI + commands (generate, variants, compare, serve, etc.)
|
||||
│ ├── test/ # Integration tests
|
||||
│ └── dist/ # Compiled binary
|
||||
├── agents-digest/ # Committed 2KB instruction-tier rules digest (gstack-AGENTS.md) for rules-reading hosts
|
||||
├── extension/ # Chrome extension (side panel + activity feed + CSS inspector)
|
||||
├── lib/ # Shared libraries (worktree.ts, egress-receipt.ts, context-bill.ts, redact-engine.ts, tracker-guard.ts, version-source.ts, code-intelligence/)
|
||||
├── lib/ # Shared libraries (aside-render.ts = local-HTML rendering, Aside first, engine fallback; claude-bin.ts, error-handling.ts, worktree.ts, egress-receipt.ts, context-bill.ts, redact-engine.ts, tracker-guard.ts, version-source.ts, code-intelligence/)
|
||||
│ └── diagram-render/ # Vendored mermaid + excalidraw runtimes, built into one offline bundle the renderer loads
|
||||
├── patches/ # bun `patchedDependencies` patches (playwright-core windowsHide)
|
||||
├── docs/designs/ # Design documents (incl. fork-port-residual-2026-09/ evaluation evidence)
|
||||
├── setup-deploy/ # /setup-deploy skill (one-time deploy config)
|
||||
@@ -82,7 +91,7 @@ gstack/
|
||||
│ └── docker/ # Dockerfile.ci (pre-baked toolchain + Playwright/Chromium)
|
||||
├── contrib/ # Contributor-only tools (never installed for users)
|
||||
│ └── add-host/ # /gstack-contrib-add-host skill
|
||||
├── setup # One-time setup: build binary + best-effort Chromium bootstrap + link skills (ownership-gated)
|
||||
├── setup # One-time setup: build the browse, design + make-pdf binaries (rebuilds when any is missing or browse/make-pdf/design/lib sources changed) + best-effort Chromium bootstrap + link skills + prune retired-skill renders (both ownership-gated)
|
||||
├── SKILL.md # Generated from SKILL.md.tmpl (don't edit directly)
|
||||
├── SKILL.md.tmpl # Template: edit this, run gen:skill-docs
|
||||
├── ETHOS.md # Builder philosophy (Boil the Ocean, Search Before Building)
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Remote Browser Access — How to Pair With a GStack Browser
|
||||
|
||||
> **Scope:** `/pair-agent` shares gstack's own browser engine, the **fallback** that runs when the Aside browser is absent (Linux, Windows, a closed Aside app). On a Mac with Aside open, every skill drives Aside instead, and there is no shared daemon to pair with — each agent that drives Aside opens its own tabs. See [BROWSER.md](../BROWSER.md) for when the fallback kicks in.
|
||||
|
||||
A GStack Browser server can be shared with any AI agent that can make HTTP requests.
|
||||
The agent gets scoped access to a real Chromium browser: navigate pages, read content,
|
||||
click elements, fill forms, take screenshots. Each agent gets its own tab.
|
||||
|
||||
+1
-1
@@ -29,7 +29,7 @@ on any slop-scan finding.
|
||||
code should use `safeUnlinkQuiet()` (swallows ALL errors). A cleanup path that throws
|
||||
on EPERM means the rest of cleanup doesn't run. That's worse.
|
||||
|
||||
### Utilities in `browse/src/error-handling.ts`
|
||||
### Utilities in `lib/error-handling.ts` (re-exported from `browse/src/error-handling.ts`)
|
||||
|
||||
| Function | Use when | Behavior |
|
||||
|----------|----------|----------|
|
||||
|
||||
@@ -44,6 +44,49 @@ a baseline, so a run can't compare against itself).
|
||||
|
||||
## Runners: how the suites execute (2026-08 overhaul)
|
||||
|
||||
**Aside-only E2E tests self-skip without a live Aside; browser-driving tests
|
||||
run on either engine.** Every skill that opens a web page drives the Aside AI
|
||||
browser first (`scripts/resolvers/aside.ts`) and falls back to gstack's own
|
||||
browse engine when Aside is absent (and Chromium bootstrapped). The cases that
|
||||
need Aside itself (`test/skill-e2e-aside.test.ts`, `design-review-fix` in
|
||||
`test/skill-e2e-design.test.ts`) call `asideAvailable()` from
|
||||
`test/helpers/aside-available.ts` (the same probe the skills run in BROWSER
|
||||
SETUP) and skip when the `aside` CLI or the Aside app is absent. CI runners have
|
||||
no Aside, so those run only on macOS dev machines and sit in the periodic tier;
|
||||
set `GSTACK_SKIP_ASIDE=1` to force the skip locally (which also exercises the
|
||||
fallback hand-off). The qa E2E files (`test/skill-e2e-qa-workflow.test.ts`,
|
||||
`test/skill-e2e-qa-bugs.test.ts`) gate on `asideAvailable() ||
|
||||
fs.existsSync(browseBin)`: the skill's own BROWSER SETUP picks the engine, so
|
||||
on a Mac they drive Aside and on Linux CI they drive the built browse binary,
|
||||
skipping only when neither exists. The `$B`-driven E2E cases and `browse/test/`
|
||||
run on every platform as before, so Linux CI proves the fallback engine live.
|
||||
|
||||
**The renderer picks the same way, so the render gates are engine-agnostic.**
|
||||
`/make-pdf`, `/diagram`, and design previews print and screenshot their local
|
||||
HTML through `lib/aside-render.ts` / `bin/gstack-render.ts`, which render in
|
||||
Aside when `probeAside()` says `READY` and through the browse engine otherwise.
|
||||
make-pdf's `*-gate.test.ts` and `test/skill-e2e-diagram.test.ts` (periodic,
|
||||
paid) gate on `browserAvailable()` (`make-pdf/test/e2e/browser-available.ts`:
|
||||
`asideAvailable() || resolveBrowseBin() !== null`) — on a Mac they print
|
||||
through Aside, on Linux CI through the browse binary `bun run build:gates`
|
||||
compiles, and they skip only when neither exists. Only
|
||||
`test/aside-render.test.ts`'s two live Aside cases (a full round-trip and a
|
||||
late-readiness `--wait-expr` poll) are Aside-only: its option
|
||||
mapping and generated-script pins run everywhere, and its fake-executable cases
|
||||
drive both engines hermetically (fake `aside` / `browse` scripts on PATH pin
|
||||
probe classification, the stdout contract, loopback-server policy, the timeout
|
||||
kill, engine choice and the mid-run fallback). `test/gstack-render-cli.test.ts`
|
||||
does the same for `bin/gstack-render.ts` with `GSTACK_SKIP_ASIDE=1` and
|
||||
`GSTACK_BROWSE_BIN` pointed at a fake daemon that logs every argv line. A green
|
||||
gate on Linux proves the fallback engine, not Aside; the Mac run is the Aside
|
||||
evidence.
|
||||
The browse-binary leg presumes Chromium bootstrapped: `resolveBrowseBin()`
|
||||
only checks that the binary (or the `find-browse` shim) exists, never that
|
||||
Chromium can launch, so on an install where the best-effort Chromium step
|
||||
was skipped (`GSTACK_SKIP_PLAYWRIGHT=1`) or failed, these gates run and fail
|
||||
at browser launch instead of skipping. Fix the bootstrap (or move the binary
|
||||
aside) before running them locally; CI always installs Chromium first.
|
||||
|
||||
**Free suite (`bun run test:free`).** `scripts/test-free-shards.ts` runs N
|
||||
concurrent shard processes (serial within each) with strict-output
|
||||
classification per shard. Full-suite shards are packed by RECORDED PER-FILE
|
||||
@@ -123,8 +166,9 @@ in the test trees must carry a `timeout`, enforced by
|
||||
ratchet.
|
||||
|
||||
**Anchor-sliced `setup` harnesses.** `setup` is one large bash script, so the
|
||||
free tests that pin its linker, cleanup, and Chromium-bootstrap behavior never
|
||||
run the whole thing. They slice the source by anchor (`extractFn(name)` takes
|
||||
free tests that pin its linker, cleanup, retired-skill prune, browser hint,
|
||||
rebuild decision, and Chromium-bootstrap behavior never run the whole thing.
|
||||
They slice the source by anchor (`extractFn(name)` takes
|
||||
`name() {` through the next `\n}\n`; `test/setup-playwright-best-effort.test.ts`
|
||||
slices the `# 2. Ensure Playwright's Chromium is available` block up to
|
||||
`# 2b.`), join the extracted functions with stubbed collaborators, and execute
|
||||
@@ -135,7 +179,14 @@ testing nothing, and `test/setup-link-ownership.test.ts` and
|
||||
`test/setup-playwright-best-effort.test.ts` throw on any `command not found` on
|
||||
stderr as harness drift (a helper the test forgot to extract) rather than
|
||||
letting it degrade into a pass. Files: `test/setup-link-ownership.test.ts`,
|
||||
`test/setup-cleanup-orphans.test.ts`, `test/setup-playwright-best-effort.test.ts`.
|
||||
`test/setup-cleanup-orphans.test.ts`, `test/setup-playwright-best-effort.test.ts`,
|
||||
`test/setup-prune-stale-generated.test.ts` (`_prune_stale_generated` against a
|
||||
temp render tree plus host dirs: host cleanup after the generator already
|
||||
pruned, symlink targets survive, frontmatter-renamed skills, foreign links),
|
||||
`test/setup-browser-hint.test.ts` (`_browser_hint` and the bootstrap summary
|
||||
across Aside present/absent, bootstrap ok/failed/skipped, `GSTACK_SKIP_ASIDE`),
|
||||
and `test/setup-needs-build.test.ts` (the `NEEDS_BUILD` block sliced between
|
||||
two anchors: every binary and source set flips it, Windows `.exe` suffixes).
|
||||
`test/relink.test.ts` shells out to a copy of the real `bin/gstack-relink`
|
||||
against a temp `GSTACK_INSTALL_DIR` / `GSTACK_SKILLS_DIR`, and
|
||||
`test/hook-scripts.test.ts` runs the real `careful/bin/check-careful.sh` and
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Domain Skills
|
||||
|
||||
> **Scope:** domain-skills are a feature of gstack's own browser engine (`$B`), the **fallback** that runs when the Aside browser is absent (Linux, Windows, a closed Aside app). Skills driving Aside record per-project learnings through `/learn` instead. See [BROWSER.md](../BROWSER.md).
|
||||
|
||||
Per-site notes the agent writes for itself. Compounds across sessions: once an
|
||||
agent figures out something non-obvious about a website, it saves a skill, and
|
||||
future sessions on that host get the note injected into their prompt context.
|
||||
|
||||
@@ -2,8 +2,13 @@
|
||||
|
||||
This guide covers the diagram + multi-format engine that ships with
|
||||
`/make-pdf` and `/diagram` (v1.58.0.0+). Everything here runs fully offline:
|
||||
the mermaid and excalidraw runtimes are vendored in `lib/diagram-render/`,
|
||||
loaded into the browse daemon's Chromium. No CDN, no network at render time.
|
||||
the mermaid and excalidraw runtimes are vendored in `lib/diagram-render/` and
|
||||
loaded into a browser by `bin/gstack-render.ts`, which serves the bundle from
|
||||
your machine on loopback for the length of one render. No CDN, no network at
|
||||
render time. The browser is your Aside browser when it is open (macOS 15+);
|
||||
when it is not — Linux, Windows, or the app closed — the same bundle renders in
|
||||
gstack's own bundled browser, so it renders offline on every platform (PNGs
|
||||
come out at 1x on the fallback, 2x through Aside).
|
||||
|
||||
## Render a mermaid diagram inside a PDF
|
||||
|
||||
@@ -13,7 +18,7 @@ Put a fence in your markdown. That's it.
|
||||
```mermaid title="Render pipeline"
|
||||
graph LR
|
||||
A[markdown] --> B[prepass]
|
||||
B --> C[Chromium]
|
||||
B --> C[browser]
|
||||
C --> D[PDF]
|
||||
```
|
||||
````
|
||||
@@ -142,5 +147,5 @@ break the build.
|
||||
boundaries silently disable `direction`).
|
||||
- **"[remote image blocked]" placeholder** → remote images are never fetched
|
||||
by default (offline posture); the tag is replaced with a visible
|
||||
placeholder so Chromium can't fetch it at print time either. Pass
|
||||
placeholder so the browser can't fetch it at print time either. Pass
|
||||
`--allow-network` to opt in.
|
||||
|
||||
+64
-52
@@ -14,21 +14,21 @@ Detailed guides for every gstack skill — philosophy, workflow, and examples.
|
||||
| [`/investigate`](#investigate) | **Debugger** | Systematic root-cause debugging. Iron Law: no fixes without investigation. Traces data flow, tests hypotheses, stops after 3 failed fixes. |
|
||||
| [`/design-review`](#design-review) | **Designer Who Codes** | Live-site visual audit + fix loop. 80-item audit, then fixes what it finds. Atomic commits, before/after screenshots. |
|
||||
| [`/design-shotgun`](#design-shotgun) | **Design Explorer** | Generate multiple AI design variants, open a comparison board in your browser, and iterate until you approve a direction. Taste memory biases toward your preferences. |
|
||||
| [`/design-html`](#design-html) | **Design Engineer** | Generates production-quality Pretext-native HTML. Works with approved mockups, CEO plans, design reviews, or from scratch. Text reflows on resize, heights adjust to content. Smart API routing per design type. Framework detection for React/Svelte/Vue. |
|
||||
| [`/design-html`](#design-html) | **Design Engineer** | Generates production-quality Pretext-native HTML. Works with approved mockups, CEO plans, design reviews, or from scratch. Text reflows on resize, heights adjust to content. Smart API routing per design type. Framework detection for React/Svelte/Vue. Previews render through your Aside browser. |
|
||||
| [`/qa`](#qa) | **QA Lead** | Test your app, find bugs, fix them with atomic commits, re-verify. Auto-generates regression tests for every fix. |
|
||||
| [`/qa-only`](#qa) | **QA Reporter** | Same methodology as /qa but report only. Use when you want a pure bug report without code changes. |
|
||||
| [`/scrape`](#scrape) | **Browser Data Extractor** | Pull data from a web page. First call prototypes via `$B`; subsequent calls on a matching intent run a codified browser-skill in ~200ms. |
|
||||
| [`/skillify`](#skillify) | **Skill Codifier** | Walks back through your conversation, finds the last `/scrape` prototype, synthesizes script + test + fixture, runs the test, asks before committing. |
|
||||
| [`/scrape`](#browse) | **Browser Data Extractor** | Pull structured data off a web page — tables, lists, prices — in your Aside browser with the page's real logged-in state. Same driver contract as `/browse`. On the fallback browser, a codified browser-skill answers a repeat intent in ~200ms. |
|
||||
| [`/skillify`](#browse) | **Skill Codifier** | Fallback-browser skill: walks back through your conversation, finds the last `/scrape` prototype, synthesizes script + test + fixture, runs the test, asks before committing. On Aside, durable per-site automation belongs to Aside's own skills. |
|
||||
| [`/ship`](#ship) | **Release Engineer** | Sync main, run tests, audit coverage, push, open PR. Bootstraps test frameworks if you don't have one. One command. |
|
||||
| [`/land-and-deploy`](#land-and-deploy) | **Release Engineer** | Merge the PR, wait for CI and deploy, verify production health. One command from "approved" to "verified in production." |
|
||||
| [`/canary`](#canary) | **SRE** | Post-deploy monitoring loop. Watches for console errors, performance regressions, and page failures using the browse daemon. |
|
||||
| [`/canary`](#canary) | **SRE** | Post-deploy monitoring loop. Watches for console errors, performance regressions, and page failures in your Aside browser. |
|
||||
| [`/benchmark`](#benchmark) | **Performance Engineer** | Baseline page load times, Core Web Vitals, and resource sizes. Compare before/after on every PR. Track trends over time. |
|
||||
| [`/cso`](#cso) | **Chief Security Officer** | OWASP Top 10 + STRIDE threat modeling security audit. Scans for injection, auth, crypto, and access control issues. |
|
||||
| [`/document-release`](#document-release) | **Technical Writer** | Update all project docs to match what you just shipped. Catches stale READMEs automatically. |
|
||||
| [`/document-generate`](#document-generate) | **Technical Writer** | Generate Diataxis docs (tutorial / how-to / reference / explanation) for a feature from code. |
|
||||
| [`/retro`](#retro) | **Eng Manager** | Team-aware weekly retro. Per-person breakdowns, shipping streaks, test health trends, growth opportunities. |
|
||||
| [`/browse`](#browse) | **QA Engineer** | Give the agent eyes. Real Chromium browser, real clicks, real screenshots. ~100ms per command. |
|
||||
| [`/setup-browser-cookies`](#setup-browser-cookies) | **Session Manager** | Import cookies from your real browser (Chrome, Arc, Brave, Edge) into the headless session. Test authenticated pages. |
|
||||
| [`/browse`](#browse) | **QA Engineer** | Give the agent eyes. Drives your Aside browser first — real sessions, real clicks, real screenshots — through deterministic `aside repl` scripts, and falls back to gstack's own Chromium (~100ms per command) when Aside isn't there. |
|
||||
| [`/setup-browser-cookies`](#setup-browser-cookies) | **Session Manager** | Fallback-browser skill: import cookies from your real browser (Chrome, Arc, Brave, Edge) into gstack's headless session to test authenticated pages. Unnecessary on Aside, which already has your sessions. |
|
||||
| [`/autoplan`](#autoplan) | **Review Pipeline** | One command, fully reviewed plan. Runs CEO → design → DX → eng review automatically (eng always last, so the shipping gate reviews the final amended plan) with encoded decision principles. Surfaces only taste decisions for your approval. |
|
||||
| [`/plan-devex-review`](#plan-devex-review) | **DX Reviewer** | Plan-stage DX review. TTHW (time-to-hello-world), magical moments, friction points, persona traces. Three modes: Expansion, Polish, Triage. |
|
||||
| [`/devex-review`](#devex-review) | **DX Reviewer (live)** | Live developer experience audit. Walks the actual onboarding flow, measures TTHW, catches the docs lies. |
|
||||
@@ -43,7 +43,7 @@ Detailed guides for every gstack skill — philosophy, workflow, and examples.
|
||||
| | | |
|
||||
| **Multi-AI** | | |
|
||||
| [`/codex`](#codex) | **Second Opinion** | Independent review from OpenAI Codex CLI. Three modes: code review (pass/fail gate), adversarial challenge, and open consultation with session continuity. Cross-model analysis when both `/review` and `/codex` have run. |
|
||||
| [`/pair-agent`](#pair-agent) | **Remote Agent Bridge** | Pair a remote AI agent (OpenClaw, Codex, Cursor, Hermes) with your browser. Scoped tunnel, locked allowlist, session token. |
|
||||
| [`/pair-agent`](#browse) | **Remote Agent Bridge** | Pair a remote AI agent (OpenClaw, Codex, Cursor, Hermes) with gstack's own browser. Scoped tunnel, locked allowlist, session token. Fallback-browser skill; agents driving Aside open their own tabs. |
|
||||
| [`/setup-gbrain`](#setup-gbrain) | **Memory Sync** | Set up gbrain for cross-machine session memory sync. One command from zero to live. |
|
||||
| [`/sync-gbrain`](#sync-gbrain) | **Keep Brain Current** | Refresh gbrain against this repo's code; teach the agent when to use `gbrain search`/`code-def` over Grep. Idempotent; safe to re-run. |
|
||||
| | | |
|
||||
@@ -52,11 +52,11 @@ Detailed guides for every gstack skill — philosophy, workflow, and examples.
|
||||
| [`/freeze`](#safety--guardrails) | **Edit Lock** | Restrict all file edits to a single directory. Blocks Edit and Write outside the boundary. Accident prevention for debugging. |
|
||||
| [`/guard`](#safety--guardrails) | **Full Safety** | Combines /careful + /freeze in one command. Maximum safety for prod work. |
|
||||
| [`/unfreeze`](#safety--guardrails) | **Unlock** | Remove the /freeze boundary, allowing edits everywhere again. |
|
||||
| [`/open-gstack-browser`](#open-gstack-browser) | **GStack Browser** | Launch GStack Browser with sidebar, anti-bot stealth, auto model routing, cookie import, and Claude Code integration. Watch every action live. |
|
||||
| [`/open-gstack-browser`](#open-gstack-browser) | **GStack Browser** | Launch gstack's own browser headed, with sidebar, anti-bot stealth, auto model routing, cookie import, and Claude Code integration. The visible face of the fallback engine; with Aside open you watch the agent's tabs there. |
|
||||
| [`/setup-deploy`](#setup-deploy) | **Deploy Configurator** | One-time setup for `/land-and-deploy`. Detects your platform, production URL, and deploy commands. |
|
||||
| [`/gstack-upgrade`](#gstack-upgrade) | **Self-Updater** | Upgrade gstack to the latest version. Detects global vs vendored install, syncs both, shows what changed. |
|
||||
| [`/make-pdf`](#make-pdf) | **PDF Generator** | Turn any markdown file into a publication-quality PDF. Proper margins, page numbers, cover pages, clickable TOC. Mermaid/excalidraw fences render as vector diagrams; `--to html\|docx` for other formats. |
|
||||
| [`/diagram`](#diagram) | **Diagram Maker** | English in, diagram out: mermaid source + editable `.excalidraw` (open it on excalidraw.com, hand-drawn style) + rendered SVG/PNG. Fully offline. |
|
||||
| [`/make-pdf`](#make-pdf) | **PDF Generator** | Turn any markdown file into a publication-quality PDF. Proper margins, page numbers, cover pages, clickable TOC. Mermaid/excalidraw fences render as vector diagrams; `--to html\|docx` for other formats. Prints through your Aside browser (macOS 15+), or gstack's bundled browser when Aside is absent. |
|
||||
| [`/diagram`](#diagram) | **Diagram Maker** | English in, diagram out: mermaid source + editable `.excalidraw` (open it on excalidraw.com, hand-drawn style) + rendered SVG/PNG. Fully offline, rendered through your Aside browser (macOS 15+) or gstack's bundled browser when Aside is absent. |
|
||||
| [`/ios-qa`](#ios-qa) | **iOS QA Lead** | Live-device iOS QA via USB CoreDevice tunnel + embedded StateServer. Reads Swift source, codegens accessors, drives the real iPhone. Optionally exposes the device over Tailscale for remote agents. |
|
||||
| [`/ios-fix`](#ios-fix) | **iOS Autonomous Fixer** | Closes the find→fix→verify loop on a real iPhone. Captures a reproducing snapshot, fixes the source, rebuilds, redeploys, verifies. |
|
||||
| [`/ios-design-review`](#ios-design-review) | **iOS Designer's Eye** | 10-dimension Apple HIG audit on a real iPhone. Rates each screen, says what would make it a 10. |
|
||||
@@ -397,7 +397,7 @@ This is my **designer who codes mode**.
|
||||
|
||||
`/plan-design-review` reviews your plan before implementation. `/design-review` audits and fixes the live site after.
|
||||
|
||||
It runs an 80-item visual audit on your live site, then enters a fix loop: for each design finding, it locates the source file, makes the minimal CSS/styling change, commits with `style(design): FINDING-NNN`, re-navigates to verify, and takes before/after screenshots. One commit per fix, fully bisectable.
|
||||
It runs an 80-item visual audit on your live site — in your Aside browser, so it sees exactly what a logged-in you sees — then enters a fix loop: for each design finding, it locates the source file, makes the minimal CSS/styling change, commits with `style(design): FINDING-NNN`, re-navigates to verify, and takes before/after screenshots. One commit per fix, fully bisectable.
|
||||
|
||||
The self-regulation heuristic is tuned for design work — CSS-only changes get a free pass (they are inherently safe and reversible), but changes to component JSX/TSX files count against the risk budget. Hard cap at 30 fixes. If the risk score exceeds 20%, it stops and asks.
|
||||
|
||||
@@ -605,7 +605,7 @@ This is my **QA lead mode**.
|
||||
|
||||
`/browse` gives the agent eyes. `/qa` gives it a testing methodology.
|
||||
|
||||
The most common use case: you're on a feature branch, you just finished coding, and you want to verify everything works. Just say `/qa` — it reads your git diff, identifies which pages and routes your changes affect, spins up the browser, and tests each one. No URL required. No manual test plan.
|
||||
The most common use case: you're on a feature branch, you just finished coding, and you want to verify everything works. Just say `/qa` — it reads your git diff, identifies which pages and routes your changes affect, opens them in tabs of your Aside browser, and tests each one. No URL required. No manual test plan.
|
||||
|
||||
Four modes:
|
||||
|
||||
@@ -635,7 +635,7 @@ Claude: [Explores 12 pages, fills 3 forms, tests 2 flows]
|
||||
[Full report with screenshots saved to .gstack/qa-reports/]
|
||||
```
|
||||
|
||||
**Testing authenticated pages:** Use `/setup-browser-cookies` first to import your real browser sessions, then `/qa` can test pages behind login.
|
||||
**Testing authenticated pages:** with Aside, nothing to set up. Aside is your browser, so `/qa` already has your sessions; if it hits a sign-in wall, sign in inside Aside and tell it you're done — it re-runs the step. It never types a password for you. On the fallback browser, run `/setup-browser-cookies` first to import your real sessions, or log in once in headed mode.
|
||||
|
||||
---
|
||||
|
||||
@@ -665,7 +665,7 @@ A lot of branches die when the interesting work is done and only the boring rele
|
||||
|
||||
### Third-party web actions (v1.72.0.0+)
|
||||
|
||||
Sometimes the release work leaves the terminal: registering an API key, creating a vendor account, wiring a webhook or OAuth app. Instead of handing you a manual step list, `/ship` (and `/spec`, `/office-hours`, `/land-and-deploy`, `/setup-deploy`) offers to drive the browser for you. The recommended driver is the Aside AI browser when it's installed — it acts across your real logged-in sessions, which is exactly what vendor dashboards need. gstack's own visible browser (`$B` headed mode with handoff for sign-in) is the fallback on every platform.
|
||||
Sometimes the release work leaves the terminal: registering an API key, creating a vendor account, wiring a webhook or OAuth app. Instead of handing you a manual step list, `/ship` (and `/spec`, `/office-hours`, `/land-and-deploy`, `/setup-deploy`) offers to drive the browser for you. Aside first — it acts across your real logged-in sessions, which is exactly what vendor dashboards need. No Aside? gstack's own visible browser (headed `$B` with handoff for sign-in) is the fallback on every platform, with one pointer to aside.com (macOS 15+) per task.
|
||||
|
||||
The consent rules are strict and pin-tested: one explicit question per task naming the exact site and actions, no standing permission, no auto-install ever (on a Mac without Aside you get one download pointer — aside.com, macOS 15+ — once per task). Passwords, payment, CAPTCHAs, and identity verification stay yours; Apple credential creation is never a drive target in any skill. A captured secret never appears in chat — it lands in an owner-only file and gets verified with one read-only API call before gstack claims success.
|
||||
|
||||
@@ -705,7 +705,7 @@ Claude: Merging PR #42...
|
||||
|
||||
This is my **post-deploy monitoring mode**.
|
||||
|
||||
After deploy, `/canary` watches the live site for trouble. It loops through your key pages using the browse daemon, checking for console errors, performance regressions, page failures, and visual anomalies. Takes periodic screenshots and compares against pre-deploy baselines.
|
||||
After deploy, `/canary` watches the live site for trouble. It loops through your key pages in your Aside browser (one `aside repl` script per page, so every cycle is a fresh load), checking for console errors, performance regressions, page failures, and visual anomalies. Takes periodic screenshots and compares against pre-deploy baselines.
|
||||
|
||||
Use it right after `/land-and-deploy`, or schedule it to run periodically after a risky deploy.
|
||||
|
||||
@@ -731,7 +731,7 @@ This is my **performance engineer mode**.
|
||||
|
||||
`/benchmark` establishes performance baselines for your pages: load time, Core Web Vitals (LCP, CLS, INP), resource counts, and total transfer size. Run it before and after a PR to catch regressions.
|
||||
|
||||
It uses the browse daemon for real Chromium measurements, not synthetic estimates. Multiple runs averaged. Results persist so you can track trends across PRs.
|
||||
It measures in your Aside browser — the page's own `performance` navigation and resource entries from a real load, not synthetic estimates. Multiple runs averaged. Results persist so you can track trends across PRs.
|
||||
|
||||
```
|
||||
You: /benchmark https://myapp.com
|
||||
@@ -810,7 +810,7 @@ Claude: Week of Mar 1: 47 commits (3 contributors), 3.2k LOC, 38% tests, 12 PRs,
|
||||
|
||||
## Your Week
|
||||
32 commits, +2.4k LOC, 41% tests. Peak hours: 9-11pm.
|
||||
Biggest ship: cookie import system (browser decryption + picker UI).
|
||||
Biggest ship: one browser contract for every browser skill (Aside).
|
||||
What you did well: shipped a complete feature with encryption, UI, and
|
||||
18 unit tests in one focused push...
|
||||
|
||||
@@ -837,45 +837,51 @@ This is my **QA engineer mode**.
|
||||
|
||||
`/browse` is the skill that closes the loop. Before it, the agent could think and code but was still half blind. It had to guess about UI state, auth flows, redirects, console errors, empty states, and broken layouts. Now it can just go look.
|
||||
|
||||
It is a compiled binary that talks to a persistent Chromium daemon — built on [Playwright](https://playwright.dev/) by Microsoft. First call starts the browser (~3s). Every call after that: ~100-200ms. The browser stays running between commands, so cookies, tabs, and localStorage carry over.
|
||||
It drives the [Aside](https://aside.com) AI browser — your real browser, with your real logged-in sessions — through `aside repl` scripts: Playwright-style JavaScript that opens a tab, does the work, prints its evidence as labelled lines, and closes the tab. One flow per script, no state carried between calls, nothing to import. Every other browser skill (`/qa`, `/qa-only`, `/design-review`, `/canary`, `/benchmark`, `/scrape`) is built on the same contract. `/scrape` is the data-extraction flavor: point it at a page and it hands back the table, list, or prices as structured data.
|
||||
|
||||
### Example
|
||||
|
||||
```
|
||||
You: /browse staging.myapp.com — log in, test the signup flow, and check
|
||||
You: /browse staging.myapp.com — test the signup flow and check
|
||||
every page I changed in this branch
|
||||
|
||||
Claude: [18 tool calls, ~60 seconds]
|
||||
Claude: Submitting the signup form on staging.myapp.com creates a real
|
||||
account in your session. Go ahead? [AskUserQuestion]
|
||||
|
||||
> browse goto https://staging.myapp.com/signup
|
||||
> browse snapshot -i
|
||||
> browse fill @e2 "$TEST_EMAIL"
|
||||
> browse fill @e3 "$TEST_PASSWORD"
|
||||
> browse click @e5 (Submit)
|
||||
> browse screenshot /tmp/signup.png
|
||||
> Read /tmp/signup.png
|
||||
You: yes
|
||||
|
||||
Signup works. Redirected to onboarding. Now checking changed pages.
|
||||
Claude: [aside repl: console hook → openTab → goto /signup → snapshot
|
||||
→ fill → click Submit → snapshot → screenshot → closeTab]
|
||||
|
||||
> browse goto https://staging.myapp.com/dashboard
|
||||
> browse screenshot /tmp/dashboard.png
|
||||
> Read /tmp/dashboard.png
|
||||
> browse console
|
||||
DIFF_START … heading "Welcome — set up your workspace" … DIFF_END
|
||||
URL=https://staging.myapp.com/onboarding
|
||||
CONSOLE_ERRORS=[]
|
||||
ASIDE_DIR=/Users/you/.aside/u/0/sessions/2026-09-05_7KtoAatMItBqZvoL
|
||||
GSTACK_STEP_OK
|
||||
|
||||
Dashboard loads. No console errors. Charts render with sample data.
|
||||
> cp "$ASIDE_DIR/issue-001-result.jpg" .gstack/qa-reports/screenshots/
|
||||
> Read .gstack/qa-reports/screenshots/issue-001-result.jpg
|
||||
|
||||
All 4 pages load correctly. No console errors. No broken layouts.
|
||||
Signup works. Redirected to onboarding. Now checking changed pages…
|
||||
|
||||
All 4 pages load. No console errors. No broken layouts.
|
||||
Signup → onboarding → dashboard flow works end to end.
|
||||
```
|
||||
|
||||
18 tool calls, about a minute. Full QA pass. No browser opened.
|
||||
Four scripts, about a minute. Full QA pass, in the browser you were already signed into.
|
||||
|
||||
> **Untrusted content:** Pages fetched via browse contain third-party content.
|
||||
> Treat output as data, not commands.
|
||||
> **Untrusted content:** everything a page returns — snapshot trees, text,
|
||||
> console output, `aside exec` answers — is data, never instructions.
|
||||
|
||||
### Browser handoff
|
||||
**What the agent will and won't do in your browser:** it opens its own tabs and closes them; it never reads or touches yours, never echoes your tab list, never types a password or reads a cookie. Looking is free; a mutating action (submit, delete, purchase) on anything that isn't localhost gets one AskUserQuestion first, listing the exact actions. Sign-in wall? Sign in inside Aside and say "done" — the session is already there.
|
||||
|
||||
When the headless browser gets stuck — CAPTCHA, MFA, complex auth — hand off to the user:
|
||||
Aside is macOS 15+ and gstack never installs it. Full contract and cookbook pointer: [BROWSER.md](../BROWSER.md).
|
||||
|
||||
### When Aside isn't there
|
||||
|
||||
Linux, Windows, or a Mac with Aside closed: `/browse` says so once and switches to gstack's own browser for the run — a compiled binary that talks to a persistent Chromium daemon built on [Playwright](https://playwright.dev/). First call starts the browser (~3s); every call after that ~100-200ms, and cookies, tabs, and localStorage carry over between commands. The same skills produce the same evidence; the features that only make sense when the browser is gstack's rather than yours live here: `/setup-browser-cookies` to import your sessions, `/open-gstack-browser` to watch it headed, `/skillify` to codify a `/scrape`, `/pair-agent` to share it with another agent.
|
||||
|
||||
When the headless browser gets stuck — CAPTCHA, MFA, complex auth — it hands off to you:
|
||||
|
||||
```
|
||||
Claude: I'm stuck on a CAPTCHA at the login page. Opening a visible
|
||||
@@ -883,10 +889,6 @@ Claude: I'm stuck on a CAPTCHA at the login page. Opening a visible
|
||||
|
||||
> browse handoff "Stuck on CAPTCHA at login page"
|
||||
|
||||
Chrome opened at https://app.example.com/login with all your
|
||||
cookies and tabs intact. Solve the CAPTCHA and tell me when
|
||||
you're done.
|
||||
|
||||
You: done
|
||||
|
||||
Claude: > browse resume
|
||||
@@ -894,19 +896,17 @@ Claude: > browse resume
|
||||
Got a fresh snapshot. Logged in successfully. Continuing QA.
|
||||
```
|
||||
|
||||
The browser preserves all state (cookies, localStorage, tabs) across the handoff. After `resume`, the agent gets a fresh snapshot of wherever you left off. If the browse tool fails 3 times in a row, it automatically suggests using `handoff`.
|
||||
The browser preserves all state across the handoff, and after `resume` the agent gets a fresh snapshot of wherever you left off. If a browse command fails 3 times in a row, it suggests `handoff` automatically.
|
||||
|
||||
**Security note:** `/browse` runs a persistent Chromium session. Cookies, localStorage, and session state carry over between commands. Do not use it against sensitive production environments unless you intend to — it is a real browser with real state. The session auto-shuts down after 30 minutes of idle time.
|
||||
|
||||
For the full command reference, see [BROWSER.md](../BROWSER.md).
|
||||
**Security note:** the fallback is a persistent Chromium session — cookies, localStorage, and session state carry over between commands. Do not use it against sensitive production environments unless you intend to. The session auto-shuts down after 30 minutes of idle time. Full `$B` command reference: [BROWSER.md](../BROWSER.md#the-fallback-engine--complete-reference).
|
||||
|
||||
---
|
||||
|
||||
## `/setup-browser-cookies`
|
||||
|
||||
This is my **session manager mode**.
|
||||
This is my **session manager mode** — for the fallback browser. With Aside open, `/qa` and `/browse` already run in your real sessions and this skill has nothing to do.
|
||||
|
||||
Before `/qa` or `/browse` can test authenticated pages, they need cookies. Instead of manually logging in through the headless browser every time, `/setup-browser-cookies` imports your real sessions directly from your daily browser.
|
||||
Before `/qa` or `/browse` can test authenticated pages on gstack's own browser, they need cookies. Instead of manually logging in through the headless browser every time, `/setup-browser-cookies` imports your real sessions directly from your daily browser.
|
||||
|
||||
It auto-detects installed Chromium browsers (Comet, Chrome, Arc, Brave, Edge), decrypts cookies via the macOS Keychain, and loads them into the Playwright session. An interactive picker UI lets you choose exactly which domains to import — no cookie values are ever displayed.
|
||||
|
||||
@@ -933,6 +933,18 @@ Claude: Imported 12 cookies for github.com from Comet.
|
||||
|
||||
---
|
||||
|
||||
## `/make-pdf`
|
||||
|
||||
Turn any markdown file into a publication-quality PDF: proper margins, page numbers, cover page, clickable TOC, mermaid and excalidraw fences rendered as vector diagrams, `--to html|docx` when you need another format. The compiled `pdf` binary does the typesetting; the printing happens in a browser — your Aside browser first. make-pdf serves the finished HTML from your machine on loopback, opens it in a tab Aside closes when it is done, prints through the browser's own PDF engine (tagged PDF, document outline, header and footer templates all intact), and copies the file out. Nothing leaves the box. When Aside is absent (Linux, Windows, or the app closed) the same pipeline prints through gstack's bundled browser instead, so a PDF comes out on every platform. Full guide to fences and formats: [howto-diagrams-and-formats.md](howto-diagrams-and-formats.md).
|
||||
|
||||
---
|
||||
|
||||
## `/diagram`
|
||||
|
||||
English in, diagram out. Describe the diagram (or paste mermaid source) and you get a triplet: the mermaid source, an editable `.excalidraw` file you can open on excalidraw.com in hand-drawn style, and rendered SVG + PNG. The mermaid and excalidraw runtimes are vendored in `lib/diagram-render/` and rendered by `bin/gstack-render.ts`, the same one-script render make-pdf uses — through your Aside browser when it is open, through gstack's bundled browser otherwise — so it is fully offline on every platform.
|
||||
|
||||
---
|
||||
|
||||
## `/autoplan`
|
||||
|
||||
This is my **review autopilot mode**.
|
||||
@@ -990,9 +1002,9 @@ Claude: 23 learnings for this project (14 high confidence, 6 medium, 3 low)
|
||||
|
||||
## `/open-gstack-browser`
|
||||
|
||||
This is my **co-presence mode**.
|
||||
This is my **co-presence mode** — for the fallback browser. With Aside open, you already watch the agent's tabs in Aside; this skill is how you watch it when the browser is gstack's own.
|
||||
|
||||
`/browse` runs headless by default. You don't see what the agent sees. `/open-gstack-browser` changes that. It launches GStack Browser (rebranded Chromium with anti-bot stealth) controlled by Playwright, with the sidebar extension auto-loaded. You watch every action in real time.
|
||||
Without Aside, `/browse` runs headless by default. You don't see what the agent sees. `/open-gstack-browser` changes that. It launches GStack Browser (rebranded Chromium with anti-bot stealth) controlled by Playwright, with the sidebar extension auto-loaded. You watch every action in real time.
|
||||
|
||||
The sidebar chat is a Claude instance that controls the browser. It auto-routes to the right model: Sonnet for navigation and actions (click, goto, fill, screenshot), Opus for reading and analysis (summarize, find bugs, describe). One-click cookie import from the sidebar footer. The browser stays alive as long as the window is open... no idle timeout in headed mode. The menu bar says "GStack Browser" instead of "Chrome for Testing."
|
||||
|
||||
@@ -1126,7 +1138,7 @@ Claude: Current version: 0.7.4
|
||||
Latest version: 0.8.2
|
||||
|
||||
What's new:
|
||||
- Browse handoff for CAPTCHAs and auth walls
|
||||
- Browser skills now drive your Aside browser
|
||||
- /codex multi-AI second opinion
|
||||
- /qa always uses browser now
|
||||
- Safety skills: /careful, /freeze, /guard
|
||||
|
||||
Reference in New Issue
Block a user